Create an OpenID Connect (OIDC) identity provider in IAM

1. Determine your OIDC identity provider’s publicly available URL. The URL must begin with https://. Per the OIDC standard, path components are allowed but query parameters are not. Typically, the URL consists of only a hostname, like https://server.example.org or https://example.com. The URL should not contain a port number.

2. Add /.well-known/openid-configuration to the end of your OIDC identity provider's URL to see the provider's publicly available configuration document and metadata. You must have a discovery document in JSON format with the provider's configuration document and metadata that can be retrieved from the OpenID Connect provider discovery endpoint URL.

3. Confirm the following values are included in your provider’s configuration information. If your openid-configuration is missing any of these fields, you must update your discovery document. This process can vary based on your identity provider, so follow your IdP's documentation to complete this task.

   • issuer: The URL for your domain.

   • jwks_uri: The JSON Web Key Set (JWKS) endpoint where IAM gets your public keys. Your identity provider must include a JSON Web Key Set (JWKS) endpoint in the openid-configuration. This URI defines where to get your public keys that are used to verify the signed tokens from your identity provider.

   • claims_supported: Information about the user that helps you ensure OIDC authentication responses from your IdP contain the required attributes AWS uses in IAM policies to check permissions for federated users. For a list of IAM condition keys that can be used for claims, see Available keys for AWS OIDC federation.

     • aud: You must determine the audience claim value your IdP issues in JSON Web Tokens (JWTs). The audience (aud) claim is application specific and identifies the intended recipients of the token. When you register a mobile or web app with an OpenID Connect provider, they establish a client ID that identifies the application. The client ID is a unique identifier for your app that is passed in the aud claim for authentication. The aud claim must match the Audience value when creating your IAM OIDC identity provider.

     • iat: Claims must include a value for iat that represents the time that the ID token is issued.

     • iss: The URL of the identity provider. The URL must begin with https:// and should correspond to the Provider URL provided to IAM. Per the OIDC standard, path components are allowed but query parameters are not. Typically, the URL consists of only a hostname, like https://server.example.org or https://example.com. The URL should not contain a port number.

   • response_types_supported: id_token

   • subject_types_supported: public

   • id_token_signing_alg_values_supported: RS256, RS384, RS512, ES256, ES384, ES512

   Note

   You can include additional claims like my_custom_claim in the example below; however, AWS STS will ignore the claim.

   {
     "issuer": "https://example-domain.com",
     "jwks_uri": "https://example-domain.com/jwks/keys",
     "claims_supported": [
       "aud",
       "iat",
       "iss",
       "name",
       "sub",
       "my_custom_claim"
     ],
     "response_types_supported": [
       "id_token"
     ],
     "id_token_signing_alg_values_supported": [
       "RS256",
       "RS384",
       "RS512",
       "ES256",
       "ES384",
       "ES512"
     ],
     "subject_types_supported": [
       "public"
     ]
   }

To create an IAM OIDC identity provider (console)

1. Before you create an IAM OIDC identity provider, you must register your application with the IdP to receive a client ID. The client ID (also known as audience) is a unique identifier for your app that is issued to you when you register your app with the IdP. For more information about obtaining a client ID, see the documentation for your IdP.

   Note

   AWS secures communication with OIDC identity providers (IdPs) using our library of trusted root certificate authorities (CAs) to verify the JSON Web Key Set (JWKS) endpoint's TLS certificate. If your OIDC IdP relies on a certificate that is not signed by one of these trusted CAs, only then we secure communication using the thumbprints set in the IdP's configuration. AWS will fall back to thumbprint verification if we are unable to retrieve the TLS certificate or if TLS v1.3 is required.

2. Open the IAM console at https://console.aws.amazon.com/iam/.

3. In the navigation pane, choose Identity providers, and then choose Add provider.

4. For Configure provider, choose OpenID Connect.

5. For Provider URL, type the URL of the IdP. The URL must comply with these restrictions:

   • The URL is case-sensitive.

   • The URL must begin with https://.

   • The URL should not contain a port number.

   • Within your AWS account, each IAM OIDC identity provider must use a unique URL. If you try to submit a URL that has already been used for an OpenID Connect provider in the AWS account, you will get an error.

6. For Audience, type the client ID of the application that you registered with the IdP and received in Step 1, and that make requests to AWS. If you have additional client IDs (also known as audiences) for this IdP, you can add them later on the provider detail page.

   Note

   If your IdP JWT token includes the azp claim, enter this value as the Audience value.

   If your OIDC identity provider is setting both aud and azp claims in the token, AWS STS will use the value in the azp claim as the aud claim.

7. (Optional) For Add tags, you can add key–value pairs to help you identify and organize your IdPs. You can also use tags to control access to AWS resources. To learn more about tagging IAM OIDC identity providers, see Tag OpenID Connect (OIDC) identity providers. Choose Add tag. Enter values for each tag key-value pair.

8. Verify the information that you have provided. When you are done choose Add provider. IAM will attempt to retrieve and use the top intermediate CA thumbprint of the OIDC IdP server certificate to create the IAM OIDC identity provider.

   Note

   The OIDC identity provider's certificate chain must start with the domain or issuer URL, then the intermediate certificate, and end with the root certificate. If the certificate chain order is different or includes duplicate or additional certificates, then you receive a signature mismatch error and STS fails to validate the JSON Web Token (JWT). Correct the order of the certificates in the chain returned from the server to resolve the error. For more information about certificate chain standards, see certificate_list in RFC 5246 on the RFC Series website.

9. Assign an IAM role to your identity provider to give external user identities managed by your identity provider permissions to access AWS resources in your account. To learn more about creating roles for identity federation, see Create a role for a third-party identity provider (federation).

   Note

   OIDC IdPs used in a role trust policy must be in the same account as the role that trusts it.

To add or remove a thumbprint for an IAM OIDC identity provider (console)

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Identity providers. Then choose the name of the IAM identity provider that you want to update.

3. Choose the Endpoint verification tab, then in the Thumbprints section, choose Manage. To enter a new thumbprint value, choose Add thumbprint. To remove a thumbprint, choose Remove next to the thumbprint that you want to remove.

   Note

   An IAM OIDC identity provider must have at least one and can have a maximum of five thumbprints.

   When you are done, choose Save changes.

To add an audience for an IAM OIDC identity provider (console)

1. In the navigation pane, choose Identity providers, then choose the name of the IAM identity provider that you want to update.

2. In the Audiences section, choose Actions and select Add audience.

3. Type the client ID of the application that you registered with the IdP and received in Step 1, and that will make requests to AWS. Then choose Add audiences.

   Note

   An IAM OIDC identity provider must have at least one and can have a maximum of 100 audiences.

To remove an audience for an IAM OIDC identity provider (console)

1. In the navigation pane, choose Identity providers, then choose the name of the IAM identity provider that you want to update.

2. In the Audiences section, select the radio button next to the audience that you want to remove, then select Actions.

3. Choose Remove audience. A new window opens.

4. If you remove an audience, identities federating with the audience cannot assume roles associated with the audience. In the window, read the warning and confirm that you want to remove the audience by typing the word remove in the field.

5. Choose Remove to remove the audience.

To delete an IAM OIDC identity provider (console)

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the navigation pane, choose Identity providers.

3. Select the checkbox next to the IAM identity provider that you want to delete. A new window opens.

4. Confirm that you want to delete the provider by typing the word delete in the field. Then, choose Delete.

To create an IAM OIDC identity provider (AWS CLI)

1. (Optional) To get a list of all the IAM OIDC identity providers in your AWS account, run the following command:

   • aws iam list-open-id-connect-providers

2. To create a new IAM OIDC identity provider, run the following command:

   • aws iam create-open-id-connect-provider

To update the list of server certificate thumbprints for an existing IAM OIDC identity provider (AWS CLI)

• To update the list of server certificate thumbprints for an IAM OIDC identity provider, run the following command:

  • aws iam update-open-id-connect-provider-thumbprint

To tag an existing IAM OIDC identity provider (AWS CLI)

• To tag an existing IAM OIDC identity provider, run the following command:

  • aws iam tag-open-id-connect-provider

To list tags for an existing IAM OIDC identity provider (AWS CLI)

• To list tags for an existing IAM OIDC identity provider, run the following command:

  • aws iam list-open-id-connect-provider-tags

To remove tags on an IAM OIDC identity provider (AWS CLI)

• To remove tags on an existing IAM OIDC identity provider, run the following command:

  • aws iam untag-open-id-connect-provider

To add or remove a client ID from an existing IAM OIDC identity provider (AWS CLI)

1. (Optional) To get a list of all the IAM OIDC identity provider in your AWS account, run the following command:

   • aws iam list-open-id-connect-providers

2. (Optional) To get detailed information about an IAM OIDC identity provider, run the following command:

   • aws iam get-open-id-connect-provider

3. To add a new client ID to an existing IAM OIDC identity provider, run the following command:

   • aws iam add-client-id-to-open-id-connect-provider

4. To remove a client from an existing IAM OIDC identity provider, run the following command:

   • aws iam remove-client-id-from-open-id-connect-provider

To delete an IAM OIDC identity provider (AWS CLI)

1. (Optional) To get a list of all the IAM OIDC identity provider in your AWS account, run the following command:

   • aws iam list-open-id-connect-providers

2. (Optional) To get detailed information about an IAM OIDC identity provider, run the following command:

   • aws iam get-open-id-connect-provider

3. To delete an IAM OIDC identity provider, run the following command:

   • aws iam delete-open-id-connect-provider

To create an IAM OIDC identity provider (AWS API)

1. (Optional) To get a list of all the IAM OIDC identity provider in your AWS account, call the following operation:

   • ListOpenIDConnectProviders

2. To create a new IAM OIDC identity provider, call the following operation:

   • CreateOpenIDConnectProvider

To update the list of server certificate thumbprints for an existing IAM OIDC identity provider (AWS API)

• To update the list of server certificate thumbprints for an IAM OIDC identity provider, call the following operation:

  • UpdateOpenIDConnectProviderThumbprint

To tag an existing IAM OIDC identity provider (AWS API)

• To tag an existing IAM OIDC identity provider, call the following operation:

  • TagOpenIDConnectProvider

To list tags for an existing IAM OIDC identity provider (AWS API)

• To list tags for an existing IAM OIDC identity provider, call the following operation:

  • ListOpenIDConnectProviderTags

To remove tags on an existing IAM OIDC identity provider (AWS API)

• To remove tags on an existing IAM OIDC identity provider, call the following operation:

  • UntagOpenIDConnectProvider

To add or remove a client ID from an existing IAM OIDC identity provider (AWS API)

1. (Optional) To get a list of all the IAM OIDC identity provider in your AWS account, call the following operation:

   • ListOpenIDConnectProviders

2. (Optional) To get detailed information about an IAM OIDC identity provider, call the following operation:

   • GetOpenIDConnectProvider

3. To add a new client ID to an existing IAM OIDC identity provider, call the following operation:

   • AddClientIDToOpenIDConnectProvider

4. To remove a client ID from an existing IAM OIDC identity provider, call the following operation:

   • RemoveClientIDFromOpenIDConnectProvider

To delete an IAM OIDC identity provider (AWS API)

1. (Optional) To get a list of all the IAM OIDC identity provider in your AWS account, call the following operation:

   • ListOpenIDConnectProviders

2. (Optional) To get detailed information about an IAM OIDC identity provider, call the following operation:

   • GetOpenIDConnectProvider

3. To delete an IAM OIDC identity provider, call the following operation:

   • DeleteOpenIDConnectProvider