AWS cognito documentation change
Summary
Updated OIDC IdP configuration documentation with clarified setup steps, added provider examples, security best practices for HTTPS, callback URLs, and attribute mapping.
Security assessment
The changes emphasize security best practices like enforcing HTTPS for endpoints, correct callback URL configuration, and proper HTTP methods. These updates help prevent misconfigurations that could lead to security issues but do not address a specific known vulnerability.
Diff
diff --git a/cognito/latest/developerguide/cognito-user-pools-oidc-idp.md b/cognito/latest/developerguide/cognito-user-pools-oidc-idp.md index 599a4b624..f6fb26af1 100644 --- a/cognito/latest/developerguide/cognito-user-pools-oidc-idp.md +++ b/cognito/latest/developerguide/cognito-user-pools-oidc-idp.md @@ -9 +9 @@ PrerequisitesRegister with an OIDC IdPAdd an OIDC IdP to your user poolTest your -Users can sign in to your application using their existing accounts from OpenID Connect (OIDC) identity providers (IdPs). With OIDC providers, users of independent single sign-on systems can provide existing credentials while your application receives OIDC tokens in the shared format of user pools. A user pool is an OIDC IdP that can also serve as an intermediate relying party between multiple external OIDC IdPs and your application. +Users can sign in to your application using their existing accounts from OpenID Connect (OIDC) identity providers (IdPs). With OIDC providers, users of independent single sign-on systems can provide existing credentials while your application receives OIDC tokens in the shared format of user pools. To configure an OIDC IdP, set up your IdP to handle your user pool as the RP and configure your application to handle your user pool as the IdP. Amazon Cognito serves as an intermediate step between multiple OIDC IdPs and your applications. Your user pool applies attribute-mapping rules to the claims in the ID and access tokens that your provider passes directly to your user pool. Amazon Cognito then issues new tokens based on the mapped user attributes and any additional adjustments you've made to the authentication flow with [Lambda triggers](./cognito-user-pools-working-with-lambda-triggers.html#lambda-triggers-for-federated-users). @@ -15 +15,3 @@ Like with other third-party identity providers, you must register your applicati - + + +See [OIDC user pool IdP authentication flow](./cognito-user-pools-oidc-flow.html) for more details about this authentication flow. @@ -27 +29 @@ You can add an OIDC IdP to your user pool in the AWS Management Console, through - * Step 1: Register with an OIDC IdP + * Register an application with an OIDC IdP @@ -29 +31 @@ You can add an OIDC IdP to your user pool in the AWS Management Console, through - * Step 2: Add an OIDC IdP to your user pool + * Add an OIDC IdP to your user pool @@ -31 +33 @@ You can add an OIDC IdP to your user pool in the AWS Management Console, through - * Step 3: Test your OIDC IdP configuration + * Test your OIDC IdP configuration @@ -61 +63 @@ Before you begin, you need the following: -## Step 1: Register with an OIDC IdP +## Register an application with an OIDC IdP @@ -63 +65 @@ Before you begin, you need the following: -Before you create an OIDC IdP with Amazon Cognito, you must register your application with the OIDC IdP to receive a client ID and client secret. +Before you add an OIDC IdP to your user pool configuration and assign it to app clients, you set up an OIDC client application in your IdP. Your user pool is the relying-party application that will manage authentication with your IdP. @@ -72,2 +74,3 @@ Salesforce | [Salesforce as an OpenID Connect Identity Provider](https://help.s -PingOne for Enterprise | [Adding or updating an OIDC application](https://docs.pingidentity.com/pingoneforenterprise/pingone_for_enterprise/p14e_add_update_oidc_application.html) | `https://sso.connect.pingidentity.com/sso/as/authorization.oauth2` -Okta | [Install an Okta identity provider](https://help.okta.com/en/prev/Content/Topics/Apps/Apps_App_Integration_Wizard.htm#OIDCWizard) | `https://`Your Okta subdomain`.okta.com.well-known/openid-configuration` +OneLogin | [Connect an OIDC enabled app](https://developers.onelogin.com/openid-connect/connect-to-onelogin) | `https://`your-domain.onelogin.com`/oidc/2/.well-known/openid-configuration` +JumpCloud | [SSO with OIDC](https://jumpcloud.com/support/sso-with-oidc) | `https://oauth.id.jumpcloud.com/.well-known/openid-configuration` +Okta | [Install an Okta identity provider](https://help.okta.com/en/prev/Content/Topics/Apps/Apps_App_Integration_Wizard.htm#OIDCWizard) | `https://`Your Okta subdomain`.okta.com/.well-known/openid-configuration` @@ -80,5 +83 @@ Microsoft Entra ID | [OpenID Connect on the Microsoft identity platform](https: - 3. Register your callback URL with your Amazon Cognito user pool. This is the URL of the page where Amazon Cognito redirects your user after a successful authentication. - - https://www.example.com - - 4. Select your [scopes](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes). The scope **openid** is required. The **email** scope is needed to grant access to the **email** and **email_verified** [claims](https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims). + 3. Select the [scopes](./cognito-user-pools-define-resource-servers.html#cognito-user-pools-define-resource-servers-about-scopes) that you want your user directory to share with your user pool. The scope **openid** is required for OIDC IdPs to offer any user information. The `email` scope is needed to grant access to the `email` and `email_verified` [claims](https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims). Additional scopes in the OIDC specification are `profile` for all user attributes and `phone` for `phone_number` and `phone_number_verified`. @@ -86 +85 @@ Microsoft Entra ID | [OpenID Connect on the Microsoft identity platform](https: - 5. The OIDC IdP provides you with a client ID and a client secret. You'll use them when you set up an OIDC IdP in your user pool. + 4. The OIDC IdP provides you with a client ID and a client secret. Note these values and add them to the configuration of the OIDC IdP that you add to your user pool later. @@ -136 +135 @@ In Salesforce, the client ID is called a **Consumer Key** , and the client secre -## Step 2: Add an OIDC IdP to your user pool +## Add an OIDC IdP to your user pool @@ -138 +137 @@ In Salesforce, the client ID is called a **Consumer Key** , and the client secre -In this section, you configure your user pool to process OIDC-based authentication requests from an OIDC IdP. +After you set up your IdP, you can configure your user pool to handle authentication requests with an OIDC IdP. @@ -140 +139 @@ In this section, you configure your user pool to process OIDC-based authenticati -### To add an OIDC IdP (Amazon Cognito console) +Amazon Cognito console @@ -142 +141,2 @@ In this section, you configure your user pool to process OIDC-based authenticati -###### Add an OIDC IdP + +###### Add an OIDC IdP in the console @@ -154 +154 @@ In this section, you configure your user pool to process OIDC-based authenticati - 6. Enter a unique name into **Provider name**. + 6. Enter a unique **Provider name**. @@ -156 +156 @@ In this section, you configure your user pool to process OIDC-based authenticati - 7. Enter the client ID you received from your provider into **Client ID**. + 7. Enter the IdP **Client ID**. This is the ID of the application client you build in your OIDC IdP. The client ID that you provide must be an OIDC provider that you've configured with a callback url of `https://`[your user pool domain]`/oauth2/idpresponse`. @@ -158 +158 @@ In this section, you configure your user pool to process OIDC-based authenticati - 8. Enter the client secret you received from your provider into **Client secret**. + 8. Enter the IdP **Client secret**. This must be the client secret for the same application client from the previous step. @@ -162,3 +162 @@ In this section, you configure your user pool to process OIDC-based authenticati -Your user will be asked to consent to providing these attributes to your application. - - 10. Choose an **Attribute request method** to provide Amazon Cognito with the HTTP method (either GET or POST) that it must use to fetch the details of the user from the **userInfo** endpoint operated by your provider. +Your IdP might prompt users to consent to providing these attributes to your application when they sign in. @@ -166 +164 @@ Your user will be asked to consent to providing these attributes to your applica - 11. Choose a **Setup method** to retrieve OpenID Connect endpoints either by **Auto fill through issuer URL** or **Manual input**. Use **Auto fill through issuer URL** when your provider has a public `.well-known/openid-configuration` endpoint where Amazon Cognito can retrieve the URLs of the `authorization`, `token`, `userInfo`, and `jwks_uri` endpoints. + 10. Choose an **Attribute request method**. IdPs might require that requests to their `userInfo` endpoints are formatted as either `GET` or `POST`. The Amazon Cognito `userInfo` endpoint requires `HTTP GET` requests, for example. @@ -168 +166 @@ Your user will be asked to consent to providing these attributes to your applica - 12. Enter the issuer URL or `authorization`, `token`, `userInfo`, and `jwks_uri` endpoint URLs from your IdP. + 11. Choose a **Setup method** for the way that you want your user pool to determine the path to key OIDC-federation endpoints at your IdP. Typically, IdPs host a `/well-known/openid-configuration` endpoint at an issuer base URL. If this is the case for your provider, the **Auto fill through issuer URL** option promtps you for that base URL, attempts to access the `/well-known/openid-configuration` path from there, and reads the endpoints listed there. You might have non-typical endpoint paths or wish to pass requests to one or more endpoints through an alternate proxy. In this case, select **Manual input** and specify paths for the `authorization`, `token`, `userInfo`, and `jwks_uri` endpoints. @@ -178,9 +176 @@ If you choose auto fill, the discovery document must use HTTPS for the following - 13. The OIDC claim **sub** is mapped to the user pool attribute **Username** by default. You can map other OIDC [claims](https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims) to user pool attributes. Enter the OIDC claim, and choose the corresponding user pool attribute from the drop-down list. For example, the claim **email** is often mapped to the user pool attribute **Email**. - - 14. Map attributes from your IdP to your user pool. For more information, see [Specifying Identity Provider Attribute Mappings for Your User Pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-specifying-attribute-mapping.html). - - 15. Choose **Create**. - - 16. From the **App clients** menu, select an app client from the list and select **Edit**. To add the new OIDC identity provider to the app client, navigate to the **Login pages** tab and select **Edit** on **Managed login pages configuration**. - - 17. Choose **Save changes**. + 12. Configure your attribute-mapping rules under **Map attributes between your OpenID Connect provider and your user pool**. **User pool attribute** is the _destination_ attribute in the Amazon Cognito user profile and **OpenID Connect attribute** is the _source_ attribute that you want Amazon Cognito to find in an ID-token claim or `userInfo` response. Amazon Cognito automatically maps the OIDC claim **sub** to `username` in the destination user profile. @@ -187,0 +178 @@ If you choose auto fill, the discovery document must use HTTPS for the following +For more information, see [Mapping IdP attributes to profiles and tokens](./cognito-user-pools-specifying-attribute-mapping.html). @@ -188,0 +180 @@ If you choose auto fill, the discovery document must use HTTPS for the following + 13. Choose **Add identity provider**. @@ -189,0 +182 @@ If you choose auto fill, the discovery document must use HTTPS for the following + 14. From the **App clients** menu, select an app client from the list. Navigate to the **Login pages** tab and under **Managed login pages configuration** , select **Edit**. Locate **Identity providers** and add your new OIDC IdP. @@ -191 +184 @@ If you choose auto fill, the discovery document must use HTTPS for the following -### To add an OIDC IdP (AWS CLI) + 15. Choose **Save changes**. @@ -193 +185,0 @@ If you choose auto fill, the discovery document must use HTTPS for the following - * See the parameter descriptions for the [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html) API method. @@ -196,5 +187,0 @@ If you choose auto fill, the discovery document must use HTTPS for the following - aws cognito-idp create-identity-provider - --user-pool-id string - --provider-name string - --provider-type OIDC - --provider-details map @@ -201,0 +189 @@ If you choose auto fill, the discovery document must use HTTPS for the following +API/CLI @@ -203,4 +190,0 @@ If you choose auto fill, the discovery document must use HTTPS for the following - --attribute-mapping string - --idp-identifiers (list) - --cli-input-json string - --generate-cli-skeleton string @@ -207,0 +192 @@ If you choose auto fill, the discovery document must use HTTPS for the following +See the OIDC configuration in example two at [CreateIdentityProvider](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateIdentityProvider.html#API_CreateIdentityProvider_Example_2). You can modify this syntax and use it as the request body of `CreateIdentityProvider`, `UpdateIdentityProvider`, or the `--cli-input-json` input file for [create-identity-provider](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/create-identity-provider.html). @@ -208,0 +194 @@ If you choose auto fill, the discovery document must use HTTPS for the following +## Test your OIDC IdP configuration @@ -210,18 +196 @@ If you choose auto fill, the discovery document must use HTTPS for the following -Use this map of provider details: - - - - { - "client_id": "string", - "client_secret": "string", - "authorize_scopes": "string", - "attributes_request_method": "string", - "oidc_issuer": "string", - - "authorize_url": "string", - "token_url": "string", - "attributes_url": "string", - "jwks_uri": "string" - } - - +In your application, you must invoke a browser in the user's client so that they can sign in with their OIDC provider. Test sign-in with your provider after you have completed the setup procedures in the preceding sections. The following example URL loads the sign-in page for your user pool with a prefix domain. @@ -229,0 +199 @@ Use this map of provider details: + https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com @@ -232 +202 @@ Use this map of provider details: -## Step 3: Test your OIDC IdP configuration +This link is the page that Amazon Cognito directs you to when you go to the **App clients** menu, select an app client, navigate to the **Login pages** tab, and select **View login page**. For more information about user pool domains, see [Configuring a user pool domain](./cognito-user-pools-assign-domain.html). For more information about app clients, including client IDs and callback URLs, see [Application-specific settings with app clients](./user-pool-settings-client-apps.html). @@ -234 +204 @@ Use this map of provider details: -You can create the authorization URL by using the elements from the previous two sections, and using them to test your OIDC IdP configuration. +The following example link sets up silent redirect to the `MyOIDCIdP` provider from the [Authorize endpoint](./authorization-endpoint.html) with an `identity_provider` query parameter. This URL bypasses interactive user pool sign-in with managed login and goes directly to the IdP sign-in page. @@ -237 +207 @@ You can create the authorization URL by using the elements from the previous two - https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com + https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?identity_provider=MyOIDCIdP&response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com @@ -239 +208,0 @@ You can create the authorization URL by using the elements from the previous two -You can find your domain on the user pool **Domain name** console page. The client_id is on the **General settings** page. Use your callback URL for the **redirect_uri** parameter. This is the URL of the page where your user will be redirected after a successful authentication.