AWS cognito medium security documentation change
Summary
Updated token endpoint documentation with expanded examples, clarified parameters, added PKCE details, and refresh token rotation guidance
Security assessment
Added explicit requirement for access tokens to include appropriate scopes for user info requests (prevents unauthorized data access). Emphasized use of OIDC libraries to handle tokens securely. Documented PKCE code verifier usage to mitigate authorization code interception. Added details about refresh token rotation (security feature to mitigate token replay attacks). These changes directly address security controls and best practices.
Diff
diff --git a/cognito/latest/developerguide/token-endpoint.md b/cognito/latest/developerguide/token-endpoint.md index 4431b332f..d67df9869 100644 --- a//cognito/latest/developerguide/token-endpoint.md +++ b//cognito/latest/developerguide/token-endpoint.md @@ -5 +5 @@ -POST /oauth2/tokenExample requests with positive responses +POST /oauth2/tokenExample requests with positive responsesExamples of negative responses @@ -21 +21 @@ Your user pool OAuth 2.0 authorization server issues JSON web tokens (JWTs) from -Users who sign in with an authorization code grant in managed login or through federation can always refresh their tokens from the token endpoint. Users who sign in with the API operations `InitiateAuth` and `AdminInitiateAuth` can refresh their tokens with the token endpoint when [remembered devices](./amazon-cognito-user-pools-device-tracking.html) is _not_ active in your user pool. If remembered devices is active, refresh tokens with the `AuthFlow` of `REFRESH_TOKEN_AUTH` in `InitiateAuth` or `AdminInitiateAuth` API requests. +Users who sign in with an authorization code grant in managed login or through federation can always refresh their tokens from the token endpoint. Users who sign in with the API operations `InitiateAuth` and `AdminInitiateAuth` can refresh their tokens with the token endpoint when [remembered devices](./amazon-cognito-user-pools-device-tracking.html) is _not_ active in your user pool. If remembered devices is active, refresh tokens with the [relevant API or SDK token-refresh operation](./amazon-cognito-user-pools-using-the-refresh-token.html#using-the-refresh-token-api) for your app client. @@ -28 +28 @@ The token endpoint becomes publicly available when you add a domain to your user -You can learn more about the user pool app clients and their grant types, client secrets, authorized scopes, and client IDs at [Application-specific settings with app clients](./user-pool-settings-client-apps.html). You can learn more about M2M authorization, client credentials grants, and authorization with access token scopes at [Scopes, M2M, and APIs with resource servers](./cognito-user-pools-define-resource-servers.html). +You can learn more about the user pool app clients and their grant types, client secrets, allowed scopes, and client IDs at [Application-specific settings with app clients](./user-pool-settings-client-apps.html). You can learn more about M2M authorization, client credentials grants, and authorization with access token scopes at [Scopes, M2M, and APIs with resource servers](./cognito-user-pools-define-resource-servers.html). @@ -30 +30 @@ You can learn more about the user pool app clients and their grant types, client -To retrieve information about a user from their access token, pass it to your [userInfo endpoint](./userinfo-endpoint.html) or to a [GetUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html) API request. +To retrieve information about a user from their access token, pass it to your [userInfo endpoint](./userinfo-endpoint.html) or to a [GetUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html) API request. The access token must contain the appropriate scopes for these requests, @@ -34 +34 @@ To retrieve information about a user from their access token, pass it to your [u -The `/oauth2/token` endpoint only supports `HTTPS POST`. Your app makes requests to this endpoint directly, not through the user's browser. +The `/oauth2/token` endpoint only supports `HTTPS POST`. This endpoint is not user-interactive. Handle token requests with an [OpenID Connect (OIDC) library](https://openid.net/developers/certified-openid-connect-implementations/) in your application. @@ -36 +36 @@ The `/oauth2/token` endpoint only supports `HTTPS POST`. Your app makes requests -The token endpoint supports `client_secret_basic` and `client_secret_post` authentication. For more information about the OpenID Connect specification, see [Client Authentication](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication). For more information about the token endpoint from the OpenID Connect specification, see [Token Endpoint](http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint). +The token endpoint supports `client_secret_basic` and `client_secret_post` authentication. For more information about the OIDC specification, see [Client Authentication](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication). For more information about the token endpoint from the OpenID Connect specification, see [Token Endpoint](http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint). @@ -40 +40 @@ The token endpoint supports `client_secret_basic` and `client_secret_post` authe -The following are headers that you can pass to the authorization endpoint. +You can pass the following parameters in the header of your request to the token endpoint. @@ -59 +59 @@ Set the value of this parameter to `'application/x-www-form-urlencoded'`. -The following are parameters that you can request in `x-www-form-urlencoded` format in the request body to the authorization endpoint. +The following are parameters that you can request in `x-www-form-urlencoded` format in the request body to the token endpoint. @@ -64 +64,3 @@ The following are parameters that you can request in `x-www-form-urlencoded` for -(Required) The type of OIDC grant that you want to request. +Required. + +The type of OIDC grant that you want to request. @@ -76,0 +79,4 @@ Must be `authorization_code` or `refresh_token` or `client_credentials`. You can +###### Note + +The token endpoint returns a refresh token only when the `grant_type` is `authorization_code`. + @@ -80 +86,3 @@ Must be `authorization_code` or `refresh_token` or `client_credentials`. You can -(Optional) The ID of an app client in your user pool. Specify the same app client that authenticated your user. +Optional. Not required when you provide the app client ID in the `Authorization` header. + +The ID of an app client in your user pool. Specify the same app client that authenticated your user. @@ -87 +95,3 @@ You must provide this parameter if the client is public and does not have a secr -(Optional) The client secret for the app client that authenticated your user. Required if your app client has a client secret and you did not send an `Authorization` header. +Optional. Not required when you provide the client secret in the `Authorization` header and when the app client doesn't have a secret. + +The app client secret, if the app client has one, for `client_secret_post` authorization. @@ -92 +102 @@ You must provide this parameter if the client is public and does not have a secr -(Optional) Can be a combination of any custom scopes that are associated with an app client. Any scope that you request must be activated for the app client. If not, Amazon Cognito will ignore it. If the client doesn't request any scopes, the authentication server assigns all custom scopes that you authorized in your app client configuration. +Optional. @@ -94 +104 @@ You must provide this parameter if the client is public and does not have a secr -Only used if the `grant_type` is `client_credentials`. +Can be a combination of any scopes that are associated with your app client. Amazon Cognito ignores scopes in the request that aren't allowed for the requested app client. If you don't provide this request parameter, the authorization server returns an access token `scope` claim with all authorization scopes that you enabled in your app client configuration. You can request any of the scopes allowed for the requested app client: standard scopes, custom scopes from resource servers, and the `aws.cognito.signin.user.admin` user self-service scope. @@ -99 +109,3 @@ Only used if the `grant_type` is `client_credentials`. -(Optional) Must be the same `redirect_uri` that was used to get `authorization_code` in `/oauth2/authorize`. +Optional. Not required for client-credentials grants. + +Must be the same `redirect_uri` that was used to get `authorization_code` in `/oauth2/authorize`. @@ -106 +118,5 @@ You must provide this parameter if `grant_type` is `authorization_code`. -(Optional) To generate new access and ID tokens for a user's session, set the value of a `refresh_token` parameter in your `/oauth2/token` request to a previously issued refresh token from the same app client. +Optional. Used only when the user already has a refresh token and wishes to get new ID and access tokens. + +To generate new access and ID tokens for a user's session, set the value of `refresh_token` to a valid refresh token that the requested app client issued. + +Returns a new refresh token with new ID and access token when [refresh token rotation](./amazon-cognito-user-pools-using-the-refresh-token.html#using-the-refresh-token-rotation) is active, otherwise returns only ID and access tokens. @@ -111 +127,3 @@ You must provide this parameter if `grant_type` is `authorization_code`. -(Optional) The authorization code from an authorization code grant. You must provide this parameter if your authorization request included a `grant_type` of `authorization_code`. +Optional. Only required in authorization-code grants. + +The authorization code from an authorization code grant. You must provide this parameter if your authorization request included a `grant_type` of `authorization_code`. @@ -116 +134,3 @@ You must provide this parameter if `grant_type` is `authorization_code`. -(Optional) The arbitrary value that you used to calculate the `code_challenge` in an authorization code grant request with PKCE. +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). @@ -119,0 +140,19 @@ You must provide this parameter if `grant_type` is `authorization_code`. +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. + +###### Topics + + * Exchanging an authorization code for tokens + + * 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 + + + + @@ -122 +161 @@ You must provide this parameter if `grant_type` is `authorization_code`. -**Example – POST request** +The following request successfully generates ID, access, and refresh tokens after authentication with an authorization-code grant. The request passes the client secret in `client_secret_basic` format in the `Authorization` header. @@ -134 +173 @@ You must provide this parameter if `grant_type` is `authorization_code`. -**Example – response** +The response issues new ID, access, and refresh tokens to the user, with additional metadata. @@ -148,5 +187 @@ You must provide this parameter if `grant_type` is `authorization_code`. -###### Note - -The token endpoint returns `refresh_token` only when the `grant_type` is `authorization_code`. - -### Exchanging client credentials for an access token: client secret in authorization header +### Client credentials with basic authorization @@ -154 +189 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -**Example – POST request** +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. @@ -166 +201 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -**Example – response** +The response returns an access token. Client credentials grants are for machine-to-machine (M2M) authorization and only return access tokens. @@ -178 +213 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -### Exchanging client credentials for an access token: client secret in request body +### Client credentials with POST body authorization @@ -180 +215 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -**Example – POST request** +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. @@ -196 +231 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -**Example – response** +The response returns an access token. Client credentials grants are for machine-to-machine (M2M) authorization and only return access tokens. @@ -210 +245 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -### Exchanging an authorization code grant with PKCE for tokens +### Authorization code grant with PKCE @@ -212 +247 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -**Example – POST request** +The following example request completes an authorization request that included `code_challenge_method` and `code_challenge` parameters in an authorization code grant request with [PKCE](./using-pkce-in-authorization-code.html). @@ -225 +260 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -**Example – response** +The response returns ID, access, and refresh tokens from the successful PKCE verification by the application. @@ -239,3 +274 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -###### Note - -The token endpoint returns `refresh_token` only when the `grant_type` is `authorization_code`. +### Token refresh without refresh token rotation @@ -243,3 +276 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -### Exchanging a refresh token for tokens - -**Example – POST request** +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. @@ -256 +287 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -**Example – response** +The response returns new ID and access tokens. @@ -269 +300 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -###### Note +### Token refresh with refresh token rotation @@ -271 +302,24 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -The token endpoint returns `refresh_token` only when the `grant_type` is `authorization_code`. +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. + + + 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 + +The response returns new ID, access, and refresh tokens. + + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "access_token": "eyJra1example", + "id_token": "eyJra2example", + "refresh_token": "eyJj4example", + "token_type": "Bearer", + "expires_in": 3600 + } @@ -273 +327 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -### Examples of negative responses +## Examples of negative responses @@ -275 +329 @@ The token endpoint returns `refresh_token` only when the `grant_type` is `author -**Example – error response** +The following are some negative responses you might get from a request to the token endpoint.