AWS cognito medium security documentation change
Summary
Expanded documentation for OAuth2 authorization endpoint parameters, added detailed examples for PKCE, re-authentication, silent auth, and token grants. Enhanced parameter descriptions with security recommendations.
Security assessment
The changes add explicit security recommendations for parameters like 'state' (CSRF protection), 'nonce' (replay attack prevention), and 'prompt=login' (re-authentication enforcement). The PKCE example documentation directly addresses authorization code interception mitigation. These are concrete security features/best practices.
Diff
diff --git a/cognito/latest/developerguide/authorization-endpoint.md b/cognito/latest/developerguide/authorization-endpoint.md index dd550bca2..b95de3bef 100644 --- a//cognito/latest/developerguide/authorization-endpoint.md +++ b//cognito/latest/developerguide/authorization-endpoint.md @@ -5 +5 @@ -GET /oauth2/authorizeExample requests with positive responsesExamples of negative responses +GET /oauth2/authorizeExample: authorization code grantExample: authorization code grant with PKCEExample: require re-authentication with prompt=loginExample: silent authentication with prompt=noneExample: Token (implicit) grant without openid scopeExample: Token (implicit) grant with openid scopeError responses @@ -39 +39,3 @@ You can learn more about the definition of the authorization endpoint in the Ope -(Required) The response type. Must be `code` or `token`. +Required. + +The response type. Must be `code` or `token`. @@ -48 +50,3 @@ A successful request with a `response_type` of `token` returns an implicit grant -(Required) The app client ID. +Required. + +The app client ID. @@ -55 +59,3 @@ The value of `client_id` must be the ID of an app client in the user pool where -(Required) The URL where the authentication server redirects the browser after Amazon Cognito authorizes the user. +Required. + +The URL where the authentication server redirects the browser after Amazon Cognito authorizes the user. @@ -77 +83,3 @@ Amazon Cognito also supports app callback URLs such as `myapp://example`. -(Optional, recommended) When your app adds a _state_ parameter to a request, Amazon Cognito returns its value to your app when the `/oauth2/authorize` endpoint redirects your user. +Optional, recommended. + +When your app adds a _state_ parameter to a request, Amazon Cognito returns its value to your app when the `/oauth2/authorize` endpoint redirects your user. @@ -86 +94,3 @@ You can't set the value of a `state` parameter to a URL-encoded JSON string. To -(Optional) Add this parameter to bypass managed login and redirect your user to a provider sign-in page. The value of the _identity_provider_ parameter is the name of the identity provider (IdP) as it appears in your user pool. +Optional. + +Add this parameter to bypass managed login and redirect your user to a provider sign-in page. The value of the _identity_provider_ parameter is the name of the identity provider (IdP) as it appears in your user pool. @@ -100 +110,3 @@ You can't set the value of a `state` parameter to a URL-encoded JSON string. To -(Optional) Add this parameter to redirect to a provider with an alternative name for the _identity_provider_ name. You can enter identifiers for your SAML 2.0 and OIDC IdPs from the **Social and external providers** menu of the Amazon Cognito console. +Optional. + +Add this parameter to redirect to a provider with an alternative name for the _identity_provider_ name. You can enter identifiers for your SAML 2.0 and OIDC IdPs from the **Social and external providers** menu of the Amazon Cognito console. @@ -105 +117,3 @@ You can't set the value of a `state` parameter to a URL-encoded JSON string. To -(Optional) Can be a combination of any system-reserved scopes or custom scopes that are associated with a client. Scopes must be separated by spaces. System reserved scopes are `openid`, `email`, `phone`, `profile`, and `aws.cognito.signin.user.admin`. Any scope used must be associated with the client, or it will be ignored at runtime. +Optional. + +Can be a combination of any system-reserved scopes or custom scopes that are associated with a client. Scopes must be separated by spaces. System reserved scopes are `openid`, `email`, `phone`, `profile`, and `aws.cognito.signin.user.admin`. Any scope used must be associated with the client, or it will be ignored at runtime. @@ -114 +128,3 @@ An ID token is only returned if `openid` scope is requested. The access token ca -(Optional) The hashing protocol that you used to generate the challenge. The [PKCE RFC](https://tools.ietf.org/html/rfc7636) defines two methods, S256 and plain; however, Amazon Cognito authentication server supports only S256. +Optional. + +The hashing protocol that you used to generate the challenge. The [PKCE RFC](https://tools.ietf.org/html/rfc7636) defines two methods, S256 and plain; however, Amazon Cognito authentication server supports only S256. @@ -119 +135,3 @@ An ID token is only returned if `openid` scope is requested. The access token ca -(Optional) The proof of key code exchange (PKCE) challenge that you generated from the `code_verifier`. For more information, see [Using PKCE in authorization code grants](./using-pkce-in-authorization-code.html). +Optional. + +The proof of key code exchange (PKCE) challenge that you generated from the `code_verifier`. For more information, see [Using PKCE in authorization code grants](./using-pkce-in-authorization-code.html). @@ -126 +144,3 @@ Required only when you specify a `code_challenge_method` parameter. -(Optional) A random value that you can add to the request. The nonce value that you provide is included in the ID token that Amazon Cognito issues. To guard against replay attacks, your app can inspect the `nonce` claim in the ID token and compare it to the one you generated. For more information about the `nonce` claim, see [ID token validation](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation) in the _OpenID Connect standard_. +Optional. + +A random value that you can add to the request. The nonce value that you provide is included in the ID token that Amazon Cognito issues. To guard against replay attacks, your app can inspect the `nonce` claim in the ID token and compare it to the one you generated. For more information about the `nonce` claim, see [ID token validation](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation) in the _OpenID Connect standard_. @@ -130,0 +151,2 @@ Required only when you specify a `code_challenge_method` parameter. +Optional. + @@ -135,0 +158,2 @@ The language that you want to display user-interactive pages in. Managed login p +Optional. + @@ -140 +164 @@ When your authorization request invokes a redirect to OIDC IdPs or Google, Amazo -## Example requests with positive responses +**`prompt`** @@ -142 +165,0 @@ When your authorization request invokes a redirect to OIDC IdPs or Google, Amazo -The following examples illustrate the format of HTTP requests to the `/oauth2/authorize` endpoint. @@ -144 +167 @@ The following examples illustrate the format of HTTP requests to the `/oauth2/au -### Authorization code grant +Optional. @@ -146 +169,7 @@ The following examples illustrate the format of HTTP requests to the `/oauth2/au -This is an example request for an authorization code grant. +An OIDC parameter that controls authentication behavior for existing sessions. Available in the managed login branding version only, not in the classic hosted UI. For more information from the OIDC specification, see [Authentication request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). The values `none` and `login` have an effect on user pool authentication behavior. + +Amazon Cognito forwards all values of `prompt` except `none` to your IdPs when users select authentication with third-party providers. This is true when the URL that users access includes an `identity_provider` or `idp_identifier` parameter, or when the authorization server redirects them to the [Login endpoint](./login-endpoint.html) and they select and IdP from the available buttons. + +###### Prompt parameter values + +`prompt=none` @@ -148 +177,23 @@ This is an example request for an authorization code grant. -**Example – GET request** + +Amazon Cognito silently continues authentication for users who have a valid authenticated session. With this prompt, users can silently authenticate between different app clients in your user pool. If the user is not already authenticated, the authorization server returns a `login_required` error. + +`prompt=login` + + +Amazon Cognito requires users to re-authenticate even if they have an existing session. Send this value when you want to verify the user's identity again. Authenticated users who have an existing session can return to sign-in without invalidating that session. When a user who has an existing session signs in again, Amazon Cognito assigns them a new session cookie. This parameter can also be forwarded to your IdPs. IdPs that accept this parameter also request a new authentication attempt from the user. + +`prompt=select_account` + + +This value has no effect on local sign-in and must be submitted in requests that redirect to IdPs. When included in your authorization request, this parameter adds `prompt=select_account` to the URL path for the IdP redirect destination. When IdPs support this parameter, they request that users select the account that they want to log in with. + +`prompt=consent` + + +This value has no effect on local sign-in and must be submitted in requests that redirect to IdPs. When included in your authorization request, this parameter adds `prompt=consent` to the URL path for the IdP redirect destination. When IdPs support this parameter, they request user consent before they redirect back to your user pool. + +When you omit the `prompt` parameter from your request, managed login follows the default behavior: users must sign in unless their browser has a valid managed login session cookie. You can combine multiple values for `prompt` with a space-character delimiter, for example `prompt=login consent`. + +## Example: authorization code grant + +This is an example request for an authorization code grant. @@ -161,2 +211,0 @@ The following request initiates a session to retrieve an authorization code that -###### **Example – response** - @@ -170 +219 @@ The Amazon Cognito authentication server redirects back to your app with the aut -### Authorization code grant with PKCE +## Example: authorization code grant with PKCE @@ -172 +221 @@ The Amazon Cognito authentication server redirects back to your app with the aut -This is an example request for an authorization code grant with [PKCE](./using-pkce-in-authorization-code.html#using-pkce-in-authorization-code.title). +This example flow performs an authorization code grant with [PKCE](./using-pkce-in-authorization-code.html#using-pkce-in-authorization-code.title). @@ -174,3 +223 @@ This is an example request for an authorization code grant with [PKCE](./using-p -**Example – GET request** - -The following request adds a `code_challenge` parameter to the previous request. To complete the exchange of a code for a token, you must include the `code_verifier` parameter in your request to the `/oauth2/token` endpoint. +This request adds a `code_challenge` parameter. To complete the exchange of a code for a token, you must include the `code_verifier` parameter in your request to the `/oauth2/token` endpoint. @@ -189,3 +236 @@ The following request adds a `code_challenge` parameter to the previous request. -###### **Example – response** - -The authentication server redirects back to your application with the authorization code and state. The code and state must be returned in the query string parameters and not in the fragment: +The authorization server redirects back to your application with the authorization code and state. Your application processes the authorization code and exchanges it for tokens. @@ -198 +243,15 @@ The authentication server redirects back to your application with the authorizat -### Token grant without `openid` scope +## Example: require re-authentication with `prompt=login` + +The following request adds a `prompt=login` parameter that requires the user to authenticate again, even if they have an existing session. + + + GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? + response_type=code& + client_id=1example23456789& + redirect_uri=https://www.example.com& + state=abcdefg& + scope=openid+profile+aws.cognito.signin.user.admin& + prompt=login + +The authorization server redirects to the [login endpoint](./login-endpoint.html), requiring re-authentication. + @@ -200 +259 @@ The authentication server redirects back to your application with the authorizat -This is an example request that generates an implicit grant and returns JWTs directly to the user's session. + HTTP/1.1 302 Found Location: https://mydomain.auth.us-east-1.amazoncognito.com/login?response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com&state=abcdefg&scope=openid+profile+aws.cognito.signin.user.admin&prompt=login @@ -202 +261 @@ This is an example request that generates an implicit grant and returns JWTs dir -**Example – GET request** +## Example: silent authentication with `prompt=none` @@ -204 +263,26 @@ This is an example request that generates an implicit grant and returns JWTs dir -The following request is for an implicit grant from your authorization server. The access token from Amazon Cognito authorizes self-service API operations. +The following request adds a `prompt=none` parameter that silently checks if the user has a valid session. + + + GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? + response_type=code& + client_id=1example23456789& + redirect_uri=https://www.example.com& + state=abcdefg& + scope=openid+profile+aws.cognito.signin.user.admin& + prompt=none + +When no valid session exists, the authorization server returns an error to the redirect URI + + + HTTP/1.1 302 Found Location: https://www.example.com?error=login_required&state=abcdefg + +When a valid session exists, the authorization server returns an authorization code. + + + HTTP/1.1 302 Found Location: https://www.example.com?code=AUTHORIZATION_CODE&state=abcdefg + +## Example: Token (implicit) grant without `openid` scope + +This example flow generates an implicit grant and returns JWTs directly to the user's session. + +The request is for an implicit grant from your authorization server. It requests scopes in the access token that authorize user profile self-service operations. @@ -215,3 +299 @@ The following request is for an implicit grant from your authorization server. T -###### **Example – response** - -The Amazon Cognito authorization server redirects back to your app with access token. Because `openid` scope was not requested, Amazon Cognito doesn't return an ID token. Also, Amazon Cognito doesn't return a refresh token in this flow. Amazon Cognito returns the access token and state in the fragment and not in the query string: +The authorization server redirects back to your application with an access token only. Because `openid` scope was not requested, Amazon Cognito doesn't return an ID token. Also, Amazon Cognito doesn't return a refresh token in this flow. @@ -221,2 +303 @@ The Amazon Cognito authorization server redirects back to your app with access t - Location: https://YOUR_APP/redirect_uri#access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600&state=STATE - + Location: https://example.com/callback#access_token=eyJra456defEXAMPLE&token_type=bearer&expires_in=3600&state=STATE @@ -224 +304,0 @@ The Amazon Cognito authorization server redirects back to your app with access t -### Token grant with `openid` scope @@ -226 +306 @@ The Amazon Cognito authorization server redirects back to your app with access t -This is an example request that generates an implicit grant and returns JWTs directly to the user's session. +## Example: Token (implicit) grant with `openid` scope @@ -228 +308 @@ This is an example request that generates an implicit grant and returns JWTs dir -**Example – GET request** +This example flow generates an implicit grant and returns tokens to the user's browser. @@ -230 +310 @@ This is an example request that generates an implicit grant and returns JWTs dir -The following request is for an implicit grant from your authorization server. The access token from Amazon Cognito authorizes access to user attributes and self-service API operations. +The request is for an implicit grant from your authorization server. It requests scopes in the access token that authorize access to user attributes and self-service operations. @@ -242,3 +322 @@ The following request is for an implicit grant from your authorization server. T -###### **Example – response** - -The authorization server redirects back to your app with access token and ID token (because `openid` scope was included): +The authorization server redirects back to your application with access token and ID token (because `openid` scope was included):