トークン発行者エンドポイント

/oauth2/token の OAuth 2.0 トークンエンドポイントは、認証コードとクライアント認証情報の付与フローを完了するアプリケーションに JSON ウェブトークン (JWT) を発行します。これらのトークンは、ユーザープールによる認証の最終結果です。これには、ユーザー (ID トークン）、ユーザーのアクセスレベル (アクセストークン）、サインインセッションを継続するユーザーの権限 (更新トークン) に関する情報が含まれます。OpenID Connect (OIDC) 依拠しているパーティライブラリは、このエンドポイントへのリクエストとこのエンドポイントからの応答ペイロードを処理します。トークンは、検証可能な認証証拠、プロファイル情報、バックエンドシステムへのアクセスメカニズムを提供します。

ユーザープール OAuth 2.0 認可サーバーは、トークンエンドポイントから以下のタイプのセッションに JSON ウェブトークン (JWT) を発行します。

ユーザープールにドメインを追加すると、トークンエンドポイントが公開されます。HTTP POST リクエストを受け入れます。アプリケーションのセキュリティを最適化するには、認可コードのサインインイベントで PKCE を使用します。PKCE は、認可コードを渡すユーザーが、認証したユーザーと同じであることを確認します。PKCE の詳細については、IETF RFC 7636 を参照してください。

ユーザープールのアプリケーションクライアントと付与タイプ、クライアントシークレット、許可されているスコープ、クライアント ID の詳細については、「アプリケーションクライアントによるアプリケーション固有の設定」を参照してください。M2M 認可、クライアント認証情報の付与、アクセストークンスコープによる認可の詳細については、「リソースサーバーを使用したスコープ、M2M、および API」を参照してください。

アクセストークンからユーザーに関する情報を取得するには、それを userInfo エンドポイント または GetUser API リクエストに渡します。アクセストークンには、これらのリクエストに適したスコープが含まれている必要があります。

トークンエンドポイントへの POST リクエストをフォーマットする

/oauth2/token エンドポイントは HTTPS POST のみをサポートします。このエンドポイントはユーザーインタラクティブではありません。トークンリクエストは、アプリケーションの OpenID Connect (OIDC) ライブラリを使用して処理されます。

トークンエンドポイントは client_secret_basic と client_secret_post をサポートしています。OIDC 仕様の詳細については、「クライアント認証」を参照してください。OpenID Connect 仕様のトークンエンドポイントの詳細については、「トークンエンドポイント」を参照してください。

ヘッダーのリクエストパラメータ

リクエストのヘッダーで、以下のパラメータをトークンエンドポイントに渡すことができます。

本文のリクエストパラメータ

トークンエンドポイントへのリクエスト本文で x-www-form-urlencoded 形式を使用してリクエストできるパラメータは、以下のとおりです。

トークン用の認可コードの交換

次のリクエストは、認証コード付与による認証後に ID、アクセストークン、更新トークンを正常に生成します。リクエストは、クライアントシークレットを client_secret_basic の形式で Authorization ヘッダーに渡します。

POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token&
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

grant_type=authorization_code&
client_id=1example23456789&
code=AUTHORIZATION_CODE&
redirect_uri=com.myclientapp://myclient/redirect

レスポンスは、追加のメタデータとともに、新しい ID、アクセストークン、更新トークンをユーザーに発行します。

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

{
    "access_token": "eyJra1example",
    "id_token": "eyJra2example",
    "refresh_token": "eyJj3example",
    "token_type": "Bearer",
    "expires_in": 3600
}

基本認可によるクライアント認証情報

M2M アプリケーションからの次のリクエストは、クライアント認証情報の付与をリクエストします。クライアント認証情報にはクライアントシークレットが必要であるため、リクエストはアプリケーションクライアント ID とシークレットから派生した Authorization ヘッダーを使用して認可されます。リクエストにより、リクエストされた 2 つのスコープを持つアクセストークンが生成されます。リクエストには、IP アドレス情報を提供するクライアントメタデータと、付与対象であるユーザーに発行されたトークンも含まれます。Amazon Cognito は、クライアントメタデータをトークン生成前の Lambda トリガーに渡します。

POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token >
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

grant_type=client_credentials&
client_id=1example23456789&
scope=resourceServerIdentifier1%2Fscope1%20resourceServerIdentifier2%2Fscope2&
&aws_client_metadata=%7B%22onBehalfOfToken%22%3A%22eyJra789ghiEXAMPLE%22,%20%22ClientIpAddress%22%3A%22192.0.2.252%22%7D

Amazon Cognito は、次の入力イベントをトークン生成前の Lambda トリガーに渡します。

{
    version: '3',
    triggerSource: 'TokenGeneration_ClientCredentials',
    region: 'us-east-1',
    userPoolId: 'us-east-1_EXAMPLE',
    userName: 'ClientCredentials',
    callerContext: {
        awsSdkVersion: 'aws-sdk-unknown-unknown',
        clientId: '1example23456789'
    },
    request: {
        userAttributes: {},
        groupConfiguration: null,
        scopes: [
           'resourceServerIdentifier1/scope1',
           'resourceServerIdentifier2/scope2'
        ],
        clientMetadata: {
            'onBehalfOfToken': 'eyJra789ghiEXAMPLE',
            'ClientIpAddress': '192.0.2.252'
        }
    },
    response: { claimsAndScopeOverrideDetails: null }
}

レスポンスはアクセストークンを返します。クライアント認証情報の付与は、Machine to Machine (M2M) 認可用であり、アクセストークンのみを返します。

HTTP/1.1 200 OK
Content-Type: application/json
{
    "access_token": "eyJra1example",
    "token_type": "Bearer",
    "expires_in": 3600
}
                    

POST 本文認可によるクライアント認証情報

次のクライアント認証情報の付与リクエストには、リクエスト本文に client_secret パラメータが含まれ、Authorization ヘッダーは含まれていません。このリクエストでは、client_secret_post 認可構文を使用しています。リクエストにより、リクエストされたスコープを持つアクセストークンが生成されます。リクエストには、IP アドレス情報を提供するクライアントメタデータと、付与対象であるユーザーに発行されたトークンも含まれます。Amazon Cognito は、クライアントメタデータをトークン生成前の Lambda トリガーに渡します。

POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
X-Amz-Target: AWSCognitoIdentityProviderService.Client credentials request
User-Agent: USER_AGENT
Accept: /
Accept-Encoding: gzip, deflate, br
Content-Length: 177
Referer: http://auth.example.com/oauth2/token
Host: auth.example.com
Connection: keep-alive

grant_type=client_credentials&
client_id=1example23456789&
scope=my_resource_server_identifier%2Fmy_custom_scope&
client_secret=9example87654321&
aws_client_metadata=%7B%22onBehalfOfToken%22%3A%22eyJra789ghiEXAMPLE%22,%20%22ClientIpAddress%22%3A%22192.0.2.252%22%7D

Amazon Cognito は、次の入力イベントをトークン生成前の Lambda トリガーに渡します。

{
    version: '3',
    triggerSource: 'TokenGeneration_ClientCredentials',
    region: 'us-east-1',
    userPoolId: 'us-east-1_EXAMPLE',
    userName: 'ClientCredentials',
    callerContext: {
        awsSdkVersion: 'aws-sdk-unknown-unknown',
        clientId: '1example23456789'
    },
    request: {
        userAttributes: {},
        groupConfiguration: null,
        scopes: [
           'resourceServerIdentifier1/my_custom_scope'
        ],
        clientMetadata: {
            'onBehalfOfToken': 'eyJra789ghiEXAMPLE',
            'ClientIpAddress': '192.0.2.252'
        }
    },
    response: { claimsAndScopeOverrideDetails: null }
}

レスポンスはアクセストークンを返します。クライアント認証情報の付与は、Machine to Machine (M2M) 認可用であり、アクセストークンのみを返します。

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Tue, 05 Dec 2023 16:11:11 GMT
x-amz-cognito-request-id: 829f4fe2-a1ee-476e-b834-5cd85c03373b

{
    "access_token": "eyJra12345EXAMPLE",
    "expires_in": 3600,
    "token_type": "Bearer"
}

PKCE による認証コード付与

次のリクエスト例では、PKCE を使用した認証コード付与リクエストに code_challenge_method パラメータと code_challenge パラメータが含まれた認可リクエストを完了します。

POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

grant_type=authorization_code&
client_id=1example23456789&
code=AUTHORIZATION_CODE&
code_verifier=CODE_VERIFIER&
redirect_uri=com.myclientapp://myclient/redirect

レスポンスは、アプリケーションによる正常な PKCE 検証から ID、アクセストークン、更新トークンを返します。

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

{
    "access_token": "eyJra1example",
    "id_token": "eyJra2example",
    "refresh_token": "eyJj3example",
    "token_type": "Bearer",
    "expires_in": 3600
}

更新トークンのローテーションなしのトークン更新

次のリクエスト例では、更新トークンのローテーションが非アクティブなアプリケーションクライアントに更新トークンを提供します。アプリケーションクライアントにはクライアントシークレットがあるため、リクエストは Authorization ヘッダーを提供します。

POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token >
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

grant_type=refresh_token&
client_id=1example23456789&
refresh_token=eyJj3example

レスポンスは、新しい ID トークンとアクセストークンを返します。

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

{
    "access_token": "eyJra1example",
    "id_token": "eyJra2example",
    "token_type": "Bearer",
    "expires_in": 3600
}

更新トークンのローテーションによるトークン更新

次のリクエスト例では、更新トークンのローテーションがアクティブなアプリケーションクライアントに更新トークンを提供します。アプリケーションクライアントにはクライアントシークレットがあるため、リクエストは Authorization ヘッダーを提供します。

POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token >
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

grant_type=refresh_token&
client_id=1example23456789&
refresh_token=eyJj3example

レスポンスは、新しい ID、アクセス、更新トークンを返します。

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

{
    "access_token": "eyJra1example",
    "id_token": "eyJra2example",
    "refresh_token": "eyJj4example",
    "token_type": "Bearer",
    "expires_in": 3600
}

否定応答の例

不正な形式のリクエストは、トークンエンドポイントからエラーを生成します。トークンリクエストがエラーを生成したときのレスポンス本文の一般的なマップは、以下のとおりです。

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
"error":"invalid_request|invalid_client|invalid_grant|unauthorized_client|unsupported_grant_type"
}