メインコンテンツへスキップ
このページは Authlete 3.0 用です。2.x については こちらのページ をご覧ください。認可・トークン・イントロスペクションの API は API リファレンス で試すこともできます。

​
前書き

このチュートリアルでは、OAuth 2.0 の認可コードグラントフローをサポートする認可サーバーを実装するために Authlete API を使用する基本的な方法を説明します。また、リソースサーバーがアクセス トークンを迅速に検証し、安全で認可された API へのアクセスを提供するために Authlete API を使用する方法も示します。 前提条件:

​
コンポーネント

一般的な OAuth 2.0 アーキテクチャには、以下のフロー図に示すように、複数のコンポーネントが含まれます。このチュートリアルでは、Authlete 管理コンソール と、米国リージョンで稼働する Authlete API クラスター (https://us.authlete.com) のパブリッククラウドバージョンを使用します。認可サーバーおよびリソースサーバーは curl コマンドを使用してシミュレートし、認可、トークン発行、およびイントロスペクションのために Authlete へ API リクエストを行う方法を示します。 各コンポーネントの FQDN は以下の通りです。認可サーバーおよびクライアントは curl でシミュレーションするため実際には FQDN は利用されませんが、以下の値を使用して OAuth フローを説明します。
コンポーネントFQDN
Authlete API - 米国クラスターus.authlete.com
Authlete 管理コンソールconsole.authlete.com
認可サーバーas.example.com
クライアントclient.example.org
リソースサーバーN/A

​
環境セットアップ

クイックスタート、およびクライアントの作成に従って、新しい Authlete サービスとクライアントを作成してください。以下の入力欄に値を入れると、下の curl 例が自動で更新されます。
Authlete API - 米国クラスター
サービス ID
サービスアクセストークン
クライアント ID
クライアントシークレット
リダイレクト URI
クライアントタイプCONFIDENTIAL
クライアント認証方法CLIENT_SECRET_BASIC

​
ウォークスルー

以下のシーケンス図は、このチュートリアルで使用される OAuth 2.0 フロー全体を示しています。各ステップを進める際に参照してください。

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

クライアントは、ユーザーエージェントを介して認可サーバーに認可リクエストを行います（ステップ 3 および 4）。 このチュートリアルでは、以下の値がリクエストのパラメータとして指定されているものと仮定します。環境セットアップの入力欄の値が下表と下文に反映されます。
パラメータ値
client_id
response_typecode
redirect_uri
上記例では認可サーバーがユーザーエージェントから以下のような HTTP GET クエリ文字列を受け取ることが期待されます。（可読性のため折り返しを追加しています。）
shell
一般的な認可サーバーは、以下のルールを評価してから認可コードグラントフローを進める必要があります。
  • クライアント ID 「」に関連付けられたクライアントが認可サーバーに登録されていることを確認する。
  • リダイレクト URI 「」がクライアントに登録された URI のいずれかと一致することを確認する。
  • response_type や scope などの他のパラメータ値がクライアントによってリクエスト内で指定されることが許可されていることを確認する。
Authlete の /auth/authorization API は、認可サーバーに代わってこれらのリクエスト検証を実行します。 以下の curl コマンドを使用して Authlete API に認可リクエストを行います（ステップ 5）。入力欄の値を変えるとコマンドが自動で更新されます。 Linux / Mac:
bash
Windows (PowerShell):
powershell
API Explorer (/auth/authorization) 用のリクエストボディ例。Service ID は環境セットアップの入力値 を使用。
json
リクエストが有効である場合、Authlete は以下のような応答を返します（ステップ 6）。 
{
    "action": "INTERACTION",
    "resultCode": "A004001",
    "resultMessage": "[A004001] Authlete has successfully issued a ticket to the service (API Key = 933860280) for the authorization request from the client (ID = 2800496004). [response_type=code, openid=false]",
    "ticket": "cElOaH9j4mS6AiIGR9oLqHlDn9jpvcNjqSgyRqfcmAE",
    "client": { "..." },
    "service": { "..." },
}
  • resultMessage は、リクエスト処理の結果を人間が読める形式で提供します（詳細は Authlete の結果コードの解釈 を参照）。
  • action は、認可サーバーが次に何を行うべきかを示します。
  • ticket は、次のステップで別の API にリクエストを行うために認可サーバーが必要とする値です。
Authlete はまた、応答内でサービスおよびクライアント情報を提供します。認可サーバーはこれを利用して、リソース所有者にクライアントがサービスへのアクセスを許可するかどうかを尋ねます。

​
ユーザー認証とアクセス許可の確認

リソース所有者と認可サーバーの間の実際のやり取りは、このチュートリアルの範囲外です。通常、認可サーバーはユーザーの資格情報（例: ID とパスワード）を使用してユーザーを認証し、ユーザーの役割や権限を特定し、クライアントにアクセスを許可するかどうかを尋ねます（ステップ 7、8、9）。

​
認可コードの発行

認可サーバーが次の状態に達したと仮定します。
  • 認可サーバーはリソース所有者を認証し、subject パラメータの値として Authlete に共有する識別子が john.s@example.com であると判断しました。
  • 認可サーバーはリソース所有者の同意を得ました。
認可サーバーは次に、Authlete の /auth/authorization/issue にリクエストを行い、認可コードを発行します。この際、subject および /auth/authorization API 応答の ticket の値をリクエストパラメータとして含めます（ステップ 10）。以下の入力欄に値を入れると、curl と API Explorer 用 JSON が更新されます。
チケット
サブジェクト
Linux / Mac:
bash
Windows (PowerShell):
powershell
API Explorer (/auth/authorization/issue) 用のリクエストボディ例。Service ID は環境セットアップの入力値 を使用。
json
リクエストが有効である場合、Authlete は以下のような応答を生成します（ステップ 11）。 
{
    "action": "LOCATION",
    "authorizationCode": "tJlGEKt8y0DLpjIA_jweywRtJs2fh83ZGNiwFRmIwYI",
    "idToken": null,
    "jwtAccessToken": null,
    "responseContent": "https://client.example.org/cb/example.com?code=tJlGEKt8y0DLpjIA_jweywRtJs2fh83ZGNiwFRmIwYI&iss=https%3A%2F%2Fauthlete.com",
    "resultCode": "A040001",
    "resultMessage": "[A040001] 認可リクエストは正常に処理されました。",
    "ticketInfo": {
        "context": null
    }
}
  • resultMessage は、リクエスト処理の結果を人間が読める形式で提供します（詳細は Authlete の結果コードの解釈 を参照）。
  • action は、認可サーバーが次に何を行うべきかを示します。この応答では LOCATION という値が指定されており、認可サーバーはユーザーエージェントにリダイレクト応答を返す必要があります。
  • responseContent は、認可サーバーからの応答内容を表します。
認可サーバーは以下のような応答をユーザーエージェントに送信することが期待されます（ステップ 12）。 
HTTP/1.1 302 Found
Location: https://client.example.org/cb/example.com
 ?code=tJlGEKt8y0DLpjIA_jweywRtJs2fh83ZGNiwFRmIwYI
クライアントにトークンを発行しない場合の状況もあります。たとえば、前の認証やユーザーの同意確認の結果、またはトークン発行を妨げるその他の文脈が欠落している場合です。このような場合、認可サーバーはプロトコル応答を通じて認可フローが終了したことをクライアントに通知する必要があります。 Authlete の /auth/authorization/fail API は、クライアントに送信されるメッセージや応答の転送方法に関する終了プロセスをサポートします。 要約すると、認可サーバーは通常、ユーザー認証および同意の結果に応じて /auth/authorization/issue または /auth/authorization/fail API のいずれかにリクエストを送信します。

​
トークンリクエスト

ここでは、ユーザーエージェントが認可サーバーからのリダイレクト応答を受信したものと仮定します。その後、以下のようなリクエストがクライアントに送信されます（ステップ 13）。（可読性のため折り返しを追加しています。入力欄の認可コードを入れると下の GET が更新されます。） 以下の入力欄に認可コード（前ステップの応答で得た code）を入れると、curl が更新されます。
認可コード (code)
http
クライアントは code パラメータの値を抽出し、この値を使用してトークンリクエストを作成し、以下のように認可サーバーに送信します。このチュートリアルでは、https://as.example.com/token をトークンエンドポイント URI と仮定します（ステップ 14）。入力欄の値が反映されます。
http
認可サーバーはリクエスト内のパラメータを評価し、その後、クライアントにトークン応答を返します。 このチュートリアルでは、Authlete の /auth/token API を使用してリクエストを評価し、応答を生成します。 Linux / Mac:
bash
Windows (PowerShell):
powershell
API Explorer (/auth/token) 用のリクエストボディ例。Service ID は環境セットアップの入力値 を使用。
json
リクエストが有効である場合、Authlete は以下のような応答を返します（ステップ 16）。 
{
    "accessToken": "gV5ByjqCVjyinFugV9Wlc0oAxkEP0osifSajXSfJV9g",
    "accessTokenDuration": 86400,
    "accessTokenExpiresAt": 1730203012061,
    "action": "OK",
    "clientAuthMethod": "CLIENT_SECRET_BASIC",
    "clientId": 2800496004,
    "grantType": "AUTHORIZATION_CODE",
    "refreshToken": "1mQRm2XRwaBNYRIjxjO0ls9hb4eDKo9I3ChU0yy8lHo",
    "refreshTokenDuration": 864000,
    "refreshTokenExpiresAt": 1730980612061,
    "responseContent": "{\"access_token\":\"gV5ByjqCVjyinFugV9Wlc0oAxkEP0osifSajXSfJV9g\",\"token_type\":\"Bearer\",\"expires_in\":86400,\"scope\":null,\"refresh_token\":\"1mQRm2XRwaBNYRIjxjO0ls9hb4eDKo9I3ChU0yy8lHo\"}",
    "resultCode": "A050001",
    "resultMessage": "[A050001] トークンリクエスト (grant_type=authorization_code) が正常に処理されました。",
    "subject": "john.s@example.com",
}
  • resultMessage は、リクエスト処理の結果を人間が読める形式で提供します（詳細は Authlete の結果コードの解釈 を参照）。
  • action は、認可サーバーが次に何を行うべきかを示します。この応答では OK という値が指定されており、認可サーバーはクライアントにトークン応答を送信する必要があります。
  • responseContent には、認可サーバーからの応答内容が含まれています。
認可サーバーは以下のような応答をクライアントに送信することが期待されます（ステップ 17）。 
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token":"gV5ByjqCVjyinFugV9Wlc0oAxkEP0osifSajXSfJV9g",
  "refresh_token":"1mQRm2XRwaBNYRIjxjO0ls9hb4eDKo9I3ChU0yy8lHo",
  "scope":null,
  "token_type":"Bearer",
  "expires_in":86400
}
認可サーバーはこれでトークンを正常に作成し、クライアントに提供しました。Authlete API を利用することで、認可サーバーは認可およびトークンリクエストのパラメータを評価するための複雑なロジックを実装する必要がなくなり、適切な方法で応答することができます。

​
API リクエスト（アクセストークンのイントロスペクション）

通常、クライアントはアクセストークンを使用してリソースサーバーにリクエストを送信し、API にアクセスします（ステップ 18）。リソースサーバーは、トークンの有効性を評価し、トークンに関連付けられたユーザーおよびクライアントに関する情報を取得し、API リクエストへの応答方法を決定します。 Authlete は、この目的のために /auth/introspection API を提供しています。この API はトークンの有効性を検証し、必要な情報を提供します。 ここでは、リソースサーバーがクライアントから受け取ったアクセストークンを以下の入力欄に設定し、curl でイントロスペクトします。
アクセストークン (access_token)
Linux / Mac:
bash
Windows (PowerShell):
powershell
API Explorer (/auth/introspection) 用のリクエストボディ例。Service ID は環境セットアップの入力値 を使用。
json
リクエストが有効である場合、Authlete は以下のような応答を返します（ステップ 20）。 
{
    "action": "OK",
    "authTime": 0,
    "clientId": 2800496004,
    "expiresAt": 1730203012000,
    "grantType": "AUTHORIZATION_CODE",
    "issuableCredentials": null,
    "properties": null,
    "refreshable": true,
    "resources": null,
    "responseContent": "Bearer error=\"invalid_request\"",
    "resultCode": "A056001",
    "resultMessage": "[A056001] アクセストークンは有効です。",
    "scopeDetails": null,
    "scopes": null,
    "serviceAttributes": null,
    "subject": "john.s@example.com",
    "sufficient": false,
    "usable": true
}
リソースサーバーは、この応答から以下のような情報を取得できます。
  • トークンの有効期限（expiresAt）
  • アクセスを承認したユーザーの識別子（subject）
  • トークンを取得するために使用されたグラントタイプ（grantType）
  • クライアント識別子（clientId）
リソースサーバーはこれらの情報を使用して、API リクエストへの応答方法を決定します（ステップ 21）。

​
まとめ

このチュートリアルでは、Authlete API を使用して認可コードグラントフローを認可サーバーに実装する方法を説明しました。Authlete API によって、認可サーバーは複雑なロジックを実装することなく、認可およびトークンリクエストを正確に評価し適切な応答を生成できます。

​
次のステップ

Authlete の以下の機能をさらに探索してみましょう。