このページは Authlete 2.x 向けのドキュメントです。3.0 の内容は OAuth 2.0 Basics（3.0）をご覧ください。

はじめに

このドキュメントでは、OAuth 2.0 の Authorization Code Grant Flow に対応した認可サーバーを構築する際の、Authlete 2.x API（api.authlete.com）の基本的な利用方法について説明します。

構成

本チュートリアルでは以下の構成を想定します。なお、実サービスとして動作するのは、Authlete のコンソールと API だけです。認可サーバーとリソースサーバーはいずれも実際には存在しませんが、それぞれのサーバーがクライアントから認可リクエストやトークンリクエスト、そしてトークンイントロスペクションリクエストを受信したときに、どのような API リクエストを Authlete に行うかを、curl コマンドを用いて試行します。

各サービスの FQDN は以下の通りです。上述の通り認可サーバーとクライアントは存在しませんが、OAuth のフローを説明する上で FQDN が最低限必要となります。

サービス	FQDN
Authlete API	`api.authlete.com`
サービス管理者コンソール (Service Owner Console)	`so.authlete.com`
開発者コンソール (Developer Console)	`cd.authlete.com`
認可サーバー (Authorization Server)	`as.example.com`
クライアント (Client)	`client.example.org`
リソースサーバー (Resource Server)	N/A

環境設定

チュートリアル「サインアップから Authlete サービス作成までの手順」に従い、新規 Authlete API サービスの作成と、そのサービスへのクライアント登録を行います。本チュートリアルでは、環境設定の結果として以下の値を生成・指定したものとします。

項目	値
クライアント ID	自動生成された値（例: `12800697055611`）
クライアントシークレット	自動生成された値（例: `dcDHEXr_tXNi7QdIMXLSXpXAy_j7Cr4C4LT2xAukQcW_09E2Ag1jTBdwpQrG-HBxflPF4Bz_Nb9Zd_ySAxOs6A`）
クライアントタイプ	`CONFIDENTIAL`
リダイレクト URI	`https://client.example.org/cb/example.com`
クライアント認証方式	`CLIENT_SECRET_BASIC`

この構成を用いて、次のセクションで認可コードグラントフローを試してみましょう。

認可コードグラントフローの実行からトークン利用までの流れ

シーケンス図を以下に示します。以降の説明においては、この図にあるメッセージ番号を併せてご参照ください。

1. クライアントから認可サーバーへの認可リクエスト送信

クライアントはユーザーエージェントを経由して、認可サーバーに認可リクエストを送信します（メッセージ番号 2, 3）。ここでは認可リクエストのパラメーターとして以下が指定されていたものとします。

項目	値
`client_id`	`12800697055611`
`response_type`	`code`
`redirect_uri`	`https://client.example.org/cb/example.com`

認可サーバーは、ユーザーエージェントからのリクエストのクエリストリングとして、以下の内容（一部折り返しています）を受信することになります（メッセージ番号 3）。

redirect_uri=https://client.example.org/cb/example.com \
  &response_type=code \
  &client_id=12800697055611

認可サーバーは、本来はこれらのパラメーターの検証を自ら行う必要があります。典型的な検証としては、以下のようなものがあります。

クライアント ID 12800697055611 に相当するクライアントが、認可サーバーに登録されているかどうか
リダイレクト URI https://client.example.org/cb/example.com が、そのクライアントに事前登録されているリダイレクト URI のどれかに合致するか
そのほかのパラメーター（response_type や、今回は指定していませんが scope など）が、そのクライアントに許可されている（クライアントが指定可能である）かどうか

この検証プロセスを代行するのが Authlete の POST /auth/authorization API です。認可サーバーの立場になり、この API にリクエストしてみましょう。

Linux/Mac

curl -s -X POST https://api.authlete.com/api/auth/authorization \
  -u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "redirect_uri=https://client.example.org/cb/example.com&response_type=code&client_id=<Client ID e.g. 12800697055611>" }'

Windows (PowerShell)

curl.exe -s -X POST https://api.authlete.com/api/auth/authorization `
  -u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' `
  -H 'Content-Type: application/json' `
  -d '{\"parameters\" : \"redirect_uri=https://client.example.org/cb/example.com&response_type=code&client_id=<Client ID e.g. 12800697055611>\"}'

リクエストが適切な場合、Authlete から以下のようなレスポンス（見やすさのため改行し一部省略）が返却されます（メッセージ番号 5）。

{
  "resultMessage": "[A004001] Authlete has successfully issued a ticket to the service (API Key = 10723797812772) for the authorization request from the client (ID = 12800697055611). [response_type=code, openid=false]",
  "resultCode": "A004001",
  "client": { /* ... */ },
  "ticket": "bi2Kxe2WW5mK_GZ_fDFOpK1bnY6xTy40Ap_8nxf-7AU",
  "action": "INTERACTION",
  "service": {
    "supportedClaims": [ /* ... */ ],
    "supportedScopes": [ /* ... */ ]
  }
}

このうち、とくに注目すべきキーは resultMessage, action, ticket です。

resultMessage: リクエストの処理結果をわかりやすく示しています。（参考: Authlete の result code について）
action: 認可サーバーが次に何をすべきかを示します（ここでは INTERACTION）。
ticket: 認可フロー処理の次のステップにて、後述する別の Authlete API を呼ぶときに必要な値となります。

それ以外に返却される値として、サービス情報とクライアント情報があります。認可サーバーはこれらの値を用いて、ユーザーに「どのようなサービスに対する、どのようなアクセス権限を、どのようなクライアントに許可するか」を確認することになります。

2. ユーザー認証とアクセス権限付与の確認

このチュートリアルの中では、ユーザーと具体的にどのようなインタラクションを行うかについては言及しません。多くの場合、認可サーバーはユーザーを何らかの方法（ID/パスワードなど）を用いて認証し、ユーザーのロールや権限を確認したのちに、クライアントに対するアクセス権限付与の確認を行います（メッセージ番号 6, 7）。ここでは、ユーザー認証とアクセス権限付与の確認が成功し、ユーザーを一意に識別する値（subject）として testuser01 を用いるものとします。

3. 認可コードの発行

ユーザー認証とアクセス権限付与確認が完了すると、認可サーバーは Authlete の POST /auth/authorization/issue API を用いて認可コードの発行を指示します。認可サーバーは、ステップ 1 の /auth/authorization API のレスポンスから取得した ticket と、subject（testuser01）を、この API へのリクエストのパラメーターとして指定します。

Linux/Mac

curl -s -X POST https://api.authlete.com/api/auth/authorization/issue \
  -u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' \
  -H 'Content-Type: application/json' \
  -d '{ "ticket": "<Ticket e.g. bi2Kxe2WW5mK_GZ_fDFOpK1bnY6xTy40Ap_8nxf-7AU>", "subject": "testuser01" }'

Windows (PowerShell)

curl.exe -s -X POST https://api.authlete.com/api/auth/authorization/issue `
  -u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' `
  -H 'Content-Type: application/json' `
  -d '{ \"ticket\": \"<Ticket e.g. bi2Kxe2WW5mK_GZ_fDFOpK1bnY6xTy40Ap_8nxf-7AU>\", \"subject\": \"testuser01\" }'

リクエストが適切な場合、Authlete から以下のようなレスポンス（見やすさのため改行）が返却されます（メッセージ番号 9）。

{
  "action": "LOCATION",
  "resultCode": "A040001",
  "accessTokenDuration": 0,
  "accessTokenExpiresAt": 0,
  "resultMessage": "[A040001] The authorization request was processed successfully.",
  "responseContent": "https://client.example.org/cb/example.com?code=GrYz5vtk6VaF0jxfnDrB2yvmk4deIrnMkrGT07JdM5U",
  "authorizationCode": "GrYz5vtk6VaF0jxfnDrB2yvmk4deIrnMkrGT07JdM5U"
}

このうち、特に注目すべきキーは resultMessage, action, responseContent です。

resultMessage, action: 先の /auth/authorization API と同様に、リクエストの処理結果と、認可サーバーが次に何をすべきかを示します。今回は action の値として LOCATION が指定されています。これは、認可サーバーはクライアントにリダイレクトレスポンスを返却してくださいという意味です。
responseContent: レスポンスの内容として指定する値です。

結果的に、認可サーバーは以下のレスポンス（一部折り返しています）をユーザーエージェントに返却することが期待されます（メッセージ番号 10）。

HTTP/1.1 302 Found
Location: https://client.example.org/cb/example.com?code=GrYz5vtk6VaF0jxfnDrB2yvmk4deIrnMkrGT07JdM5U

なお、もしユーザー認証とアクセス権限付与確認の結果、クライアントに対するトークン発行を行わないことになった場合には、認可サーバーは Authlete の POST /auth/authorization/fail API を用いて、適切なエラーレスポンスを生成します。つまり認可サーバーは、ユーザーの認証・認可の結果に応じて、/auth/authorization/issue もしくは /auth/authorization/fail を使い分けることになります。

4. トークンリクエスト

認可コードを含むリダイレクトを受け取ったクライアントは、code の値を抽出してトークンリクエストを組み立て、認可サーバーに送信します（メッセージ番号 12）。ここではトークンエンドポイントを https://as.example.com/token とします。

POST /token HTTP/1.1
Host: as.example.com
Authorization: Basic base64(12800697055611:dcDHEXr_tXNi7QdIMXLSXpXAy_j7Cr4C4LT2xAukQcW_09E2Ag1jTBdwpQrG-HBxflPF4Bz_Nb9Zd_ySAxOs6A)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
 &code=GrYz5vtk6VaF0jxfnDrB2yvmk4deIrnMkrGT07JdM5U
 &redirect_uri=https://client.example.org/cb/example.com

このトークンリクエストの検証とレスポンス生成を自ら実装する代わりに、Authlete の POST /auth/token API に委譲できます。

Linux/Mac

curl -s -X POST https://api.authlete.com/api/auth/token \
  -u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' \
  -H 'Content-Type: application/json' \
  -d '{ "clientId": "<Client ID e.g. 12800697055611>", "clientSecret": "<Client Secret e.g. dcDHEXr_tXNi7QdIMXLSXpXAy_j7Cr4C4LT2xAukQcW_09E2Ag1jTBdwpQrG-HBxflPF4Bz_Nb9Zd_ySAxOs6A>", "parameters": "grant_type=authorization_code&code=<Code e.g. GrYz5vtk6VaF0jxfnDrB2yvmk4deIrnMkrGT07JdM5U>&redirect_uri=https://client.example.org/cb/example.com" }'

Windows (PowerShell)

curl.exe -s -X POST https://api.authlete.com/api/auth/token `
  -u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' `
  -H 'Content-Type: application/json' `
  -d '{ \"clientId\": \"<Client ID e.g. 12800697055611>\", \"clientSecret\": \"<Client Secret e.g. dcDHEXr_tXNi7QdIMXLSXpXAy_j7Cr4C4LT2xAukQcW_09E2Ag1jTBdwpQrG-HBxflPF4Bz_Nb9Zd_ySAxOs6A>\", \"parameters\": \"grant_type=authorization_code&code=<Code e.g. GrYz5vtk6VaF0jxfnDrB2yvmk4deIrnMkrGT07JdM5U>&redirect_uri=https://client.example.org/cb/example.com\" }'

リクエストが適切な場合、Authlete から以下のようなレスポンス（見やすさのため改行）が返却されます（メッセージ番号 14）。

{
  "resultMessage": "[A050001] The token request (grant_type=authorization_code) was processed successfully.",
  "action": "OK",
  "clientIdAliasUsed": false,
  "subject": "testuser01",
  "resultCode": "A050001",
  "refreshTokenExpiresAt": 1559288344881,
  "grantType": "AUTHORIZATION_CODE",
  "accessToken": "7FfwOnGjVHwxXhs2Wr67XV1-ZhQaoy3ctKcGkLyKxuY",
  "responseContent": "{\"access_token\":\"7FfwOnGjVHwxXhs2Wr67XV1-ZhQaoy3ctKcGkLyKxuY\",\"refresh_token\":\"T1h7fJ6k55CyipDtXNPbzN8ta3FgAAf4QKjo36OVfIE\",\"scope\":null,\"token_type\":\"Bearer\",\"expires_in\":86400}",
  "accessTokenDuration": 86400,
  "refreshToken": "T1h7fJ6k55CyipDtXNPbzN8ta3FgAAf4QKjo36OVfIE",
  "accessTokenExpiresAt": 1558510744881,
  "refreshTokenDuration": 864000,
  "clientId": 12800697055611
}

このうち、特に注目すべきキーは resultMessage, action, responseContent です。

resultMessage, action: これまでと同様に、リクエストの処理結果と、認可サーバーが次に何をすべきかを示します。今回は action の値として OK が指定されています。これは、正常に処理が完了したので認可サーバーはクライアントにレスポンスを返却してくださいという意味です。
responseContent: レスポンスの内容として指定する値です。

認可サーバーは、以下のレスポンスをクライアントに返却することが期待されます（メッセージ番号 15）。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token":"7FfwOnGjVHwxXhs2Wr67XV1-ZhQaoy3ctKcGkLyKxuY",
  "refresh_token":"T1h7fJ6k55CyipDtXNPbzN8ta3FgAAf4QKjo36OVfIE",
  "scope":null,
  "token_type":"Bearer",
  "expires_in":86400
}

以上により、認可サーバーはトークンを生成し、クライアントに提供することができました。Authlete の API を活用することにより、認可サーバーは複雑な処理を実装せずとも、認可リクエストやトークンリクエストのパラメーターを正しく検証し、正しいレスポンス内容を返却することができます。

5. API リクエスト（アクセストークン検証）

このあと実際には、クライアントはリソースサーバーに対してアクセストークンを含むリクエストを送信し、API の利用を試みます（メッセージ番号 16）。アクセストークンを受け取ったリソースサーバーは、以下を行う必要があります。

トークンが有効で、有効期限が切れていないかを確認する。
トークンに付随するユーザー（subject）とクライアント（clientId）の情報を取得する。
API リクエストにどう応答すべきかを判断する。

Authlete には、トークンの有効性を検証しその結果を返却する /auth/introspection API が存在します。<API Key>, <API Secret>, <Token> はご自身の値に置き換えてください。

Linux/Mac

curl -s -X POST https://api.authlete.com/api/auth/introspection \
  -u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' \
  -H 'Content-Type: application/json' \
  -d '{ "token": "<Token e.g. 7FfwOnGjVHwxXhs2Wr67XV1-ZhQaoy3ctKcGkLyKxuY>" }'

Windows (PowerShell)

curl.exe -s -X POST https://api.authlete.com/api/auth/introspection `
  -u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' `
  -H 'Content-Type: application/json' `
  -d '{ \"token\": \"<Token e.g. 7FfwOnGjVHwxXhs2Wr67XV1-ZhQaoy3ctKcGkLyKxuY>\" }'

リクエストが適切な場合、Authlete から以下のようなレスポンス（見やすさのため改行）が返却されます（メッセージ番号 18）。

{
  "clientIdAliasUsed": false,
  "resultCode": "A056001",
  "responseContent": "Bearer error=\"invalid_request\"",
  "action": "OK",
  "subject": "testuser01",
  "expiresAt": 1558510744000,
  "existent": true,
  "resultMessage": "[A056001] The access token is valid.",
  "refreshable": true,
  "sufficient": true,
  "usable": true,
  "clientId": 12800697055611
}

リソースサーバーはこのレスポンス結果から、アクセストークンの有効性（usable, sufficient, expiresAt）や、アクセス認可を行なったユーザーの識別子（subject）、クライアント（clientId）などを取得します。そしてそれらの値に基づいて、クライアントに対する API レスポンスを決定できるようになります（メッセージ番号 19）。

まとめ

本チュートリアルでは、/auth/authorization、/auth/authorization/issue、/auth/token、/auth/introspection を用いて、認可サーバーに OAuth 2.0 の認可コードグラントフローを実装する際の Authlete 2.x API の利用方法について、実際の動作を確認しました。

次のステップ

認可コードフローで PKCE を必須化する: PKCE (2.x)
OAuth 2.0 の上に OpenID Connect を追加する: OIDC Basics (2.x)
エラーレスポンスの生成方法を学ぶ: 「fail」API を用いたエラーレスポンスの生成
トークンの管理と失効: トークンのライフサイクルとポリシー
参考となる認可サーバー実装を調べる: 認可サーバー実装（参考: デモ認可サーバーの利用 (2.x)）

Authlete の紹介

クイックスタート

コアコンセプト

開発者リソース

ツール

OAuth 2.0 Basics

はじめに

構成

環境設定

認可コードグラントフローの実行からトークン利用までの流れ

1. クライアントから認可サーバーへの認可リクエスト送信

Linux/Mac

Windows (PowerShell)

2. ユーザー認証とアクセス権限付与の確認

3. 認可コードの発行

Linux/Mac

Windows (PowerShell)

4. トークンリクエスト

Linux/Mac

Windows (PowerShell)

5. API リクエスト（アクセストークン検証）

Linux/Mac

Windows (PowerShell)

まとめ

次のステップ

​はじめに

​構成

​環境設定

​認可コードグラントフローの実行からトークン利用までの流れ

​1. クライアントから認可サーバーへの認可リクエスト送信

​Linux/Mac

​Windows (PowerShell)

​2. ユーザー認証とアクセス権限付与の確認

​3. 認可コードの発行

​Linux/Mac

​Windows (PowerShell)

​4. トークンリクエスト

​Linux/Mac

​Windows (PowerShell)

​5. API リクエスト（アクセストークン検証）

​Linux/Mac

​Windows (PowerShell)

​まとめ

​次のステップ

はじめに

構成

環境設定

認可コードグラントフローの実行からトークン利用までの流れ

1. クライアントから認可サーバーへの認可リクエスト送信

Linux/Mac

Windows (PowerShell)

2. ユーザー認証とアクセス権限付与の確認

3. 認可コードの発行

Linux/Mac

Windows (PowerShell)

4. トークンリクエスト

Linux/Mac

Windows (PowerShell)

5. API リクエスト（アクセストークン検証）

Linux/Mac

Windows (PowerShell)

まとめ

次のステップ