AWS cognito documentation change
Summary
Restructured token endpoint documentation with new examples, added aws_client_metadata parameter details, and expanded client credentials/PKCE/refresh token rotation explanations
Security assessment
Added documentation for aws_client_metadata parameter which enables passing security context to pre-token Lambda triggers. Enhanced examples show security best practices like PKCE and refresh token rotation. No evidence of addressing a specific vulnerability.
Diff
diff --git a/cognito/latest/developerguide/token-endpoint.md b/cognito/latest/developerguide/token-endpoint.md index d67df9869..9e79e7ff9 100644 --- a//cognito/latest/developerguide/token-endpoint.md +++ b//cognito/latest/developerguide/token-endpoint.md @@ -5 +5 @@ -POST /oauth2/tokenExample requests with positive responsesExamples of negative responses +Request formatExample: authorization codeExample: client credentials with basic authorizationExample: client credentials with body authorizationExample: authorization code with PKCEExample: refresh token grant without rotationExample: refresh token rotationError responses @@ -9 +9 @@ POST /oauth2/tokenExample requests with positive responsesExamples of negative r -The OAuth 2.0 [token endpoint](https://www.rfc-editor.org/rfc/rfc6749#section-3.2) at `/oauth2/token` issues JSON web tokens (JWTs). These tokens are the end result of authentication with a user pool. They contain information about the user (ID token), the user's level of access (access token), and the user's entitlement to persist their signed-in session (refresh token). OpenID Connect (OIDC) relying-party libraries handle requests to and response payloads from this endpoint. Tokens provide verifiable proof of authentication, profile information, and a mechanism for access to back-end systems. +The OAuth 2.0 [token endpoint](https://www.rfc-editor.org/rfc/rfc6749#section-3.2) at `/oauth2/token` issues JSON web tokens (JWTs) to applications that want to complete authorization-code and client-credentials grant flows. These tokens are the end result of authentication with a user pool. They contain information about the user (ID token), the user's level of access (access token), and the user's entitlement to persist their signed-in session (refresh token). OpenID Connect (OIDC) relying-party libraries handle requests to and response payloads from this endpoint. Tokens provide verifiable proof of authentication, profile information, and a mechanism for access to back-end systems. @@ -32 +32 @@ To retrieve information about a user from their access token, pass it to your [u -## POST /oauth2/token +## Format a POST request to the token endpoint @@ -64 +64 @@ The following are parameters that you can request in `x-www-form-urlencoded` for -Required. +_Required._ @@ -86 +86 @@ The token endpoint returns a refresh token only when the `grant_type` is `author -Optional. Not required when you provide the app client ID in the `Authorization` header. +_Optional. Not required when you provide the app client ID in the`Authorization` header._ @@ -95 +95 @@ You must provide this parameter if the client is public and does not have a secr -Optional. Not required when you provide the client secret in the `Authorization` header and when the app client doesn't have a secret. +_Optional. Not required when you provide the client secret in the`Authorization` header and when the app client doesn't have a secret._ @@ -102 +102 @@ The app client secret, if the app client has one, for `client_secret_post` autho -Optional. +_Optional._ @@ -109 +109 @@ Can be a combination of any scopes that are associated with your app client. Ama -Optional. Not required for client-credentials grants. +_Optional. Not required for client-credentials grants._ @@ -118 +118 @@ You must provide this parameter if `grant_type` is `authorization_code`. -Optional. Used only when the user already has a refresh token and wishes to get new ID and access tokens. +_Optional. Used only when the user already has a refresh token and wishes to get new ID and access tokens._ @@ -127 +127 @@ Returns a new refresh token with new ID and access token when [refresh token rot -Optional. Only required in authorization-code grants. +_Optional. Only required in authorization-code grants._ @@ -131,8 +131 @@ The authorization code from an authorization code grant. You must provide this p -**`code_verifier`** - - -Optional. Required only if you provided `code_challenge_method` and `code_challenge` parameters in your initial authorization request. - -The generated code verifier that your application calculated the `code_challenge` from in an authorization code grant request with [PKCE](./using-pkce-in-authorization-code.html). - -## Example requests with positive responses +**`aws_client_metadata`** @@ -140 +132,0 @@ The generated code verifier that your application calculated the `code_challenge -The syntax of your token request depends on the grant type that you request, the configuration of your app client, and whether you use PKCE. @@ -142 +134 @@ The syntax of your token request depends on the grant type that you request, the -###### Topics +_Optional._ @@ -144 +136 @@ The syntax of your token request depends on the grant type that you request, the - * Exchanging an authorization code for tokens +Information that you want to pass to the [Pre token generation Lambda trigger](./user-pool-lambda-pre-token-generation.html). Your application can collect context information about the user or machine session and pass it in this parameter. When you pass `aws_client_metadata` in URL-encoded JSON format, Amazon Cognito includes it in the input event to your trigger Lambda function. Your pre token trigger event version or global Lambda trigger version must be configured for version two or later. @@ -146,9 +138 @@ The syntax of your token request depends on the grant type that you request, the - * Client credentials with basic authorization - - * Client credentials with POST body authorization - - * Authorization code grant with PKCE - - * Token refresh without refresh token rotation - - * Token refresh with refresh token rotation +**`code_verifier`** @@ -156,0 +141 @@ The syntax of your token request depends on the grant type that you request, the +Optional. Required only if you provided `code_challenge_method` and `code_challenge` parameters in your initial authorization request. @@ -157,0 +143 @@ The syntax of your token request depends on the grant type that you request, the +The generated code verifier that your application calculated the `code_challenge` from in an authorization code grant request with [PKCE](./using-pkce-in-authorization-code.html). @@ -159 +145 @@ The syntax of your token request depends on the grant type that you request, the -### Exchanging an authorization code for tokens +## Exchanging an authorization code for tokens @@ -187 +173 @@ The response issues new ID, access, and refresh tokens to the user, with additio -### Client credentials with basic authorization +## Client credentials with basic authorization @@ -189 +175 @@ The response issues new ID, access, and refresh tokens to the user, with additio -The following request is for a client-credentials grant. Because client credentials requires a client secret, the request is authorized with an `Authorization` header derived from the app client ID and secret. +The following request from an M2M application requests a client credentials grant. Because client credentials requires a client secret, the request is authorized with an `Authorization` header derived from the app client ID and secret. The request results in an access token with the two requested scopes. The request also includes client metadata that provides IP-address information and a token issued to the user who this grant is on behalf of. Amazon Cognito passes the client metadata to the pre token generation Lambda trigger. @@ -198 +184,2 @@ The following request is for a client-credentials grant. Because client credenti - scope=resourceServerIdentifier1/scope1 resourceServerIdentifier2/scope2 + scope=resourceServerIdentifier1%2Fscope1%20resourceServerIdentifier2%2Fscope2& + &aws_client_metadata=%7B%22onBehalfOfToken%22%3A%22eyJra789ghiEXAMPLE%22,%20%22ClientIpAddress%22%3A%22192.0.2.252%22%7D @@ -199,0 +187,27 @@ The following request is for a client-credentials grant. Because client credenti +Amazon Cognito passes the following input event to the pre token generation Lambda trigger. + + + { + 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 } + } @@ -213 +227 @@ The response returns an access token. Client credentials grants are for machine- -### Client credentials with POST body authorization +## Client credentials with POST body authorization @@ -215 +229 @@ The response returns an access token. Client credentials grants are for machine- -The following client-credentials grant request includes the `client_secret` parameter in the request body and doesn't include an `Authorization` header. This request uses the `client_secret_post` authorization syntax. +The following client-credentials grant request includes the `client_secret` parameter in the request body and doesn't include an `Authorization` header. This request uses the `client_secret_post` authorization syntax. The request results in an access token with the requested scope. The request also includes client metadata that provides IP-address information and a token issued to the user who this grant is on behalf of. Amazon Cognito passes the client metadata to the pre token generation Lambda trigger. @@ -229 +243,32 @@ The following client-credentials grant request includes the `client_secret` para - grant_type=client_credentials&client_id=1example23456789&scope=my_resource_server_identifier%2Fmy_custom_scope&client_secret=9example87654321 + 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 passes the following input event to the pre token generation Lambda trigger. + + + { + 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 } + } @@ -245 +290 @@ The response returns an access token. Client credentials grants are for machine- -### Authorization code grant with PKCE +## Authorization code grant with PKCE @@ -274 +319 @@ The response returns ID, access, and refresh tokens from the successful PKCE ver -### Token refresh without refresh token rotation +## Token refresh without refresh token rotation @@ -276 +321 @@ The response returns ID, access, and refresh tokens from the successful PKCE ver -The following example requests provides a refresh token to an app client where refresh token rotation is inactive. Because the app client has a client secret, the request provides an `Authorization` header. +The following example requests provides a refresh token to an app client where [refresh token rotation](./amazon-cognito-user-pools-using-the-refresh-token.html#using-the-refresh-token-rotation) is inactive. Because the app client has a client secret, the request provides an `Authorization` header. @@ -300 +345 @@ The response returns new ID and access tokens. -### Token refresh with refresh token rotation +## Token refresh with refresh token rotation @@ -302 +347 @@ The response returns new ID and access tokens. -The following example requests provides a refresh token to an app client where refresh token rotation is active. Because the app client has a client secret, the request provides an `Authorization` header. +The following example requests provides a refresh token to an app client where [refresh token rotation](./amazon-cognito-user-pools-using-the-refresh-token.html#using-the-refresh-token-rotation) is active. Because the app client has a client secret, the request provides an `Authorization` header. @@ -329 +374 @@ The response returns new ID, access, and refresh tokens. -The following are some negative responses you might get from a request to the token endpoint. +Malformed requests generate errors from the token endpoint. The following is a general map of the response body when token requests generate an error.