# OIDC federation
OIDC federation
Imagine that you are creating an application that accesses AWS resources, such as GitHub Actions that uses workflows to access Amazon S3 and DynamoDB.
When you use these workflows, you make requests to AWS services that must be signed with an AWS access key. However, we **strongly** recommend that you do **not** store AWS credentials long-term in applications outside AWS. Instead, configure your applications to request temporary AWS security credentials dynamically when needed using *OIDC federation*. The supplied temporary credentials map to an AWS role that only has permissions needed to perform the tasks required by the application.
With OIDC federation, you don't need to create custom sign-in code or manage your own user identities. Instead, you can use OIDC in applications, such as GitHub Actions or any other [OpenID Connect (OIDC)](http://openid.net/connect/)-compatible IdP, to authenticate with AWS. They receive an authentication token, known as a JSON Web Token (JWT), and then exchange that token for temporary security credentials in AWS that map to an IAM role with permissions to use specific resources in your AWS account. Using an IdP helps you keep your AWS account secure because you don't have to embed and distribute long-term security credentials with your application.
OIDC federation supports both machine-to-machine authentication (such as CI/CD pipelines, automated scripts, and serverless applications) and human user authentication. For human user authentication scenarios where you need to manage user sign-up, sign-in, and user profiles, consider using [Amazon Cognito](https://aws.amazon.com/cognito/) as an identity broker. For details about using Amazon Cognito with OIDC, see [Amazon Cognito for mobile apps](id_federation_common_scenarios.md#id_roles_providers_oidc_cognito).
**Note**
JSON Web Tokens (JWTs) issued by OpenID Connect (OIDC) identity providers contain an expiration time in the `exp` claim that specifies when the token expires. IAM provides a five-minute window beyond the expiration time specified in the JWT to account for clock skew, as allowed by the [OpenID Connect (OIDC) Core 1.0 standard](https://openid.net/specs/openid-connect-core-1_0.html). This means OIDC JWTs received by IAM after the expiration time but within this five-minute window are accepted for further evaluation and processing.
**Topics**
+ [
## Additional resources for OIDC federation
](#id_roles_providers_oidc_resources)
+ [
# Create an OpenID Connect (OIDC) identity provider in IAM
](id_roles_providers_create_oidc.md)
+ [
# Obtain the thumbprint for an OpenID Connect identity provider
](id_roles_providers_create_oidc_verify-thumbprint.md)
+ [
# Identity-provider controls for shared OIDC providers
](id_roles_providers_oidc_secure-by-default.md)
## Additional resources for OIDC federation
The following resources can help you learn more about OIDC federation:
+ Use OpenID Connect within your GitHub workflows by [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)
+ [Amazon Cognito Identity](https://docs.amplify.aws/lib/auth/advanced/q/platform/android/) in the *Amplify Libraries for Android Guide* and [Amazon Cognito Identity](https://docs.amplify.aws/lib/auth/advanced/q/platform/ios/) in the *Amplify Libraries for Swift Guide*.
+ [How to use external ID when granting access to your AWS resources](https://aws.amazon.com/blogs/security/how-to-use-external-id-when-granting-access-to-your-aws-resources/) on the *AWS Security Blog* provides guidance on securely configuring cross-account access and external identity federation.
# Create an OpenID Connect (OIDC) identity provider in IAM
Create OIDC identity provider
*IAM OIDC identity providers* are entities in IAM that describe an external identity provider (IdP) service that supports the [OpenID Connect](http://openid.net/connect/) (OIDC) standard, such as Google or Salesforce. You use an IAM OIDC identity provider when you want to establish trust between an OIDC-compatible IdP and your AWS account. This is useful when creating a mobile app or web application that requires access to AWS resources, but you don't want to create custom sign-in code or manage your own user identities. For more information about this scenario, see [OIDC federation](id_roles_providers_oidc.md).
You can create and manage an IAM OIDC identity provider using the AWS Management Console, the AWS Command Line Interface, the Tools for Windows PowerShell, or the IAM API.
After you create an IAM OIDC identity provider, you must create one or more IAM roles. A role is an identity in AWS that doesn't have its own credentials (as a user does). But in this context, a role is dynamically assigned to an OIDC federated principal that is authenticated by your organization's IdP. The role permits your organization's IdP to request temporary security credentials for access to AWS. The policies assigned to the role determine what users are allowed to do in AWS. To create a role for a third-party identity provider, see [Create a role for a third-party identity provider](id_roles_create_for-idp.md).
**Important**
When you configure identity-based policies for actions that support `oidc-provider` resources, IAM evaluates the full OIDC identity provider URL, including any specified paths. If your OIDC identity provider URL has a path, you must include that path in the `oidc-provider` ARN as a `Resource` element value. You also have the option to append a forward slash and wildcard (`/*`) to the URL domain or use wildcard characters (`*` and `?`) at any point in the URL path. If the OIDC identity provider URL in the request doesn't match the value set in the policy's `Resource` element, the request fails.
To troubleshoot common issues with IAM OIDC federation, see [Resolve errors related to OIDC](https://repost.aws/knowledge-center/iam-oidc-idp-federation) on AWS re:Post.
**Topics**
+ [
## Prerequisites: Validate configuration of your identity provider
](#manage-oidc-provider-prerequisites)
+ [
## Creating and managing an OIDC provider (console)
](#manage-oidc-provider-console)
+ [
## Creating and managing an IAM OIDC identity provider (AWS CLI)
](#manage-oidc-provider-cli)
+ [
## Creating and managing an OIDC Identity Provider (AWS API)
](#manage-oidc-provider-api)
## Prerequisites: Validate configuration of your identity provider
Prerequisites
Before you can create an IAM OIDC identity provider, you must have the following information from your IdP. For more information about obtaining OIDC provider configuration Information, see the documentation for your IdP.
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.
1. 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](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig).
1. 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\$1uri: 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.
**Note**
The JSON Web Key Set (JWKS) must contain at least one key and can have a maximum of 100 RSA keys and 100 EC keys. If your OIDC identity provider's JWKS contains more than 100 RSA keys or 100 EC keys, an `InvalidIdentityToken` exception will be returned when using the [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) API operation with a JWT signed by a key type that exceeds the 100-key limit. For example, if a JWT is signed with the RSA algorithm and there are more than 100 RSA keys in your provider's JWKS, an `InvalidIdentityToken` exception will be returned.
+ claims\$1supported: 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 OIDC federated principals. For a list of IAM condition keys that can be used for claims, see [Available keys for AWS OIDC federation](reference_policies_iam-condition-keys.md#condition-keys-wif).
+ 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\$1types\$1supported: id\$1token
+ subject\$1types\$1supported: public
+ id\$1token\$1signing\$1alg\$1values\$1supported: 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"
]
}
```
## Creating and managing an OIDC provider (console)
Follow these instructions to create and manage an IAM OIDC identity provider in the AWS Management Console.
**Important**
If you are using an OIDC identity provider from either Google, Facebook, or Amazon Cognito, do not create a separate IAM identity provider using this procedure. These OIDC identity providers are already built-in to AWS and are available for your use. Instead, follow the steps to create new roles for your identity provider, see [Create a role for OpenID Connect federation (console)](id_roles_create_for-idp_oidc.md).
**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.
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Identity providers**, and then choose **Add provider**.
1. For **Configure provider**, choose **OpenID Connect**.
1. 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.
1. For **Audience**, type the client ID of the application that you registered with the IdP and received in [Step 1](#idpoidcstep1), 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.
1. (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](id_tags_oidc.md). Choose **Add tag**. Enter values for each tag key-value pair.
1. 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\$1list in RFC 5246](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.2) on the RFC Series website.
1. 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](id_roles_create_for-idp.md).
**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)**
**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.
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Identity providers**. Then choose the name of the IAM identity provider that you want to update.
1. 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.
1. In the **Audiences** section, choose **Actions** and select **Add audience**.
1. Type the client ID of the application that you registered with the IdP and received in [Step 1](#idpoidcstep1), 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.
1. In the **Audiences** section, select the radio button next to the audience that you want to remove, then select **Actions**.
1. Choose **Remove audience**. A new window opens.
1. 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.
1. 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/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Identity providers**.
1. Select the checkbox next to the IAM identity provider that you want to delete. A new window opens.
1. Confirm that you want to delete the provider by typing the word `delete` in the field. Then, choose **Delete**.
## Creating and managing an IAM OIDC identity provider (AWS CLI)
You can use the following AWS CLI commands to create and manage IAM OIDC identity providers.
**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:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/list-open-id-connect-providers.html](https://docs.aws.amazon.com/cli/latest/reference/iam/list-open-id-connect-providers.html)
1. To create a new IAM OIDC identity provider, run the following command:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/create-open-id-connect-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/create-open-id-connect-provider.html)
**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:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/update-open-id-connect-provider-thumbprint.html](https://docs.aws.amazon.com/cli/latest/reference/iam/update-open-id-connect-provider-thumbprint.html)
**To tag an existing IAM OIDC identity provider (AWS CLI)**
+ To tag an existing IAM OIDC identity provider, run the following command:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/tag-open-id-connect-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-open-id-connect-provider.html)
**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:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/list-open-id-connect-provider-tags.html](https://docs.aws.amazon.com/cli/latest/reference/iam/list-open-id-connect-provider-tags.html)
**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:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/untag-open-id-connect-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/untag-open-id-connect-provider.html)
**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:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/list-open-id-connect-providers.html](https://docs.aws.amazon.com/cli/latest/reference/iam/list-open-id-connect-providers.html)
1. (Optional) To get detailed information about an IAM OIDC identity provider, run the following command:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/get-open-id-connect-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/get-open-id-connect-provider.html)
1. To add a new client ID to an existing IAM OIDC identity provider, run the following command:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/add-client-id-to-open-id-connect-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/add-client-id-to-open-id-connect-provider.html)
1. To remove a client from an existing IAM OIDC identity provider, run the following command:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/remove-client-id-from-open-id-connect-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/remove-client-id-from-open-id-connect-provider.html)
**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:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/list-open-id-connect-providers.html](https://docs.aws.amazon.com/cli/latest/reference/iam/list-open-id-connect-providers.html)
1. (Optional) To get detailed information about an IAM OIDC identity provider, run the following command:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/get-open-id-connect-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/get-open-id-connect-provider.html)
1. To delete an IAM OIDC identity provider, run the following command:
+ [https://docs.aws.amazon.com/cli/latest/reference/iam/delete-open-id-connect-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/delete-open-id-connect-provider.html)
## Creating and managing an OIDC Identity Provider (AWS API)
You can use the following IAM API commands to create and manage OIDC providers.
**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:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListOpenIDConnectProviders.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListOpenIDConnectProviders.html)
1. To create a new IAM OIDC identity provider, call the following operation:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateOpenIDConnectProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateOpenIDConnectProvider.html)
**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:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateOpenIDConnectProviderThumbprint.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateOpenIDConnectProviderThumbprint.html)
**To tag an existing IAM OIDC identity provider (AWS API)**
+ To tag an existing IAM OIDC identity provider, call the following operation:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagOpenIDConnectProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagOpenIDConnectProvider.html)
**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:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListOpenIDConnectProviderTags.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListOpenIDConnectProviderTags.html)
**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:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagOpenIDConnectProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagOpenIDConnectProvider.html)
**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:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListOpenIDConnectProviders.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListOpenIDConnectProviders.html)
1. (Optional) To get detailed information about an IAM OIDC identity provider, call the following operation:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetOpenIDConnectProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetOpenIDConnectProvider.html)
1. To add a new client ID to an existing IAM OIDC identity provider, call the following operation:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_AddClientIDToOpenIDConnectProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_AddClientIDToOpenIDConnectProvider.html)
1. To remove a client ID from an existing IAM OIDC identity provider, call the following operation:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_RemoveClientIDFromOpenIDConnectProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_RemoveClientIDFromOpenIDConnectProvider.html)
**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:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListOpenIDConnectProviders.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListOpenIDConnectProviders.html)
1. (Optional) To get detailed information about an IAM OIDC identity provider, call the following operation:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetOpenIDConnectProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetOpenIDConnectProvider.html)
1. To delete an IAM OIDC identity provider, call the following operation:
+ [https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteOpenIDConnectProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteOpenIDConnectProvider.html)
# Obtain the thumbprint for an OpenID Connect identity provider
Obtain the thumbprint for an OIDC provider
When you [create an OpenID Connect (OIDC) identity provider](id_roles_providers_create_oidc.md) in IAM, IAM requires the thumbprint for the top intermediate certificate authority (CA) that signed the certificate used by the external identity provider (IdP). The thumbprint is a signature for the CA's certificate that was used to issue the certificate for the OIDC-compatible IdP. When you create an IAM OIDC identity provider, you are trusting identities authenticated by that IdP to have access to your AWS account. By using the CA's certificate thumbprint, you trust any certificate issued by that CA with the same DNS name as the one registered. This eliminates the need to update trusts in each account when you renew the IdP's signing certificate.
**Important**
In most cases, the federation server uses two different certificates:
The first establishes an HTTPS connection between AWS and your IdP. This should be issued by a well-known public root CA, such as AWS Certificate Manager. This enables the client to check the reliability and status of the certificate.
The second is used to encrypt tokens, and should be signed by a private or public *root* CA.
You can create an IAM OIDC identity provider with [the AWS Command Line Interface, the Tools for Windows PowerShell, or the IAM API](id_roles_providers_create_oidc.md#manage-oidc-provider-cli). When you use these methods, you have the option to manually provide a thumbprint. If you choose not to include a thumbprint, IAM will retrieve the top intermediate CA thumbprint of the OIDC IdP server certificate. If you choose to include a thumbprint, you must obtain the thumbprint manually and supply it to AWS.
When you create an OIDC identity provider with [the IAM console](id_roles_providers_create_oidc.md), IAM attempts to retrieve the top intermediate CA thumbprint of the OIDC IdP server certificate for you.
We recommend that you also obtain the thumbprint for your OIDC IdP manually and verify that IAM retrieved the correct thumbprint. For more information about obtaining certificate thumbprints, see the following sections.
**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.
## Obtain certificate thumbprint
You use a web browser and the OpenSSL command line tool to obtain the certificate thumbprint for an OIDC provider. However, you do not need to manually obtain the certificate thumbprint to create an IAM OIDC identity provider. You can use the following procedure to obtain the certificate thumbprint of your OIDC provider.
**To obtain the thumbprint for an OIDC IdP**
1. Before you can obtain the thumbprint for an OIDC IdP, you need to obtain the OpenSSL command line tool. You use this tool to download the OIDC IdP certificate chain and produce a thumbprint of the final certificate in the certificate chain. If you need to install and configure OpenSSL, follow the instructions at [Install OpenSSL](#oidc-install-openssl) and [Configure OpenSSL](#oidc-configure-openssl).
1. Start with the OIDC IdP URL (for example, `https://server.example.com`), and then add `/.well-known/openid-configuration` to form the URL for the IdP's configuration document, such as the following:
**https://*server.example.com*/.well-known/openid-configuration**
Open this URL in a web browser, replacing *server.example.com* with your IdP server name.
1. In the displayed document, use your web browser **Find** feature to locate the text `"jwks_uri"`. Immediately following the text `"jwks_uri"`, there is a colon (:) followed by a URL. Copy the fully qualified domain name of the URL. Do not include `https://` or any path that comes after the top-level domain.
```
{
"issuer": "https://accounts.example.com",
"authorization_endpoint": "https://accounts.example.com/o/oauth2/v2/auth",
"device_authorization_endpoint": "https://oauth2.exampleapis.com/device/code",
"token_endpoint": "https://oauth2.exampleapis.com/token",
"userinfo_endpoint": "https://openidconnect.exampleapis.com/v1/userinfo",
"revocation_endpoint": "https://oauth2.exampleapis.com/revoke",
"jwks_uri": "https://www.exampleapis.com/oauth2/v3/certs",
...
```
1. Use the OpenSSL command line tool to run the following command. Replace *keys.example.com* with the domain name you obtained in [Step 3](#thumbstep2).
```
openssl s_client -servername keys.example.com -showcerts -connect keys.example.com:443
```
1. In your command window, scroll up until you see a certificate similar to the following example. If you see more than one certificate, find the last certificate displayed (at the end of the command output). This contains the certificate of the top intermediate CA in the certificate authority chain.
```
-----BEGIN CERTIFICATE-----
MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6
b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd
BgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wHhcNMTEwNDI1MjA0NTIxWhcN
MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYD
VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25z
b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFt
YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ
21uUSfwfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T
rDHudUZg3qX4waLG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE
Ibb3OhjZnzcvQAaRHhdlQWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4
nUhVVxYUntneD9+h8Mg9q6q+auNKyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb
FFBjvSfpJIlJ00zbhNYS5f6GuoEDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTb
NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE=
-----END CERTIFICATE-----
```
Copy the certificate (including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines) and paste it into a text file. Then save the file with the file name **certificate.crt**.
**Note**
The OIDC identity provider's certificate chain must start with the domain or issuer URL, include any intermediate certificates (if present), and end with the root certificate. If the certificate chain order is different or includes duplicate or additional certificates, you will 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\$1list in RFC 5246](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.2) on the RFC Series website.
1. Use the OpenSSL command line tool to run the following command.
```
openssl x509 -in certificate.crt -fingerprint -sha1 -noout
```
Your command window displays the certificate thumbprint, which looks similar to the following example:
```
SHA1 Fingerprint=99:0F:41:93:97:2F:2B:EC:F1:2D:DE:DA:52:37:F9:C9:52:F2:0D:9E
```
Remove the colon characters (:) from this string to produce the final thumbprint, like this:
```
990F4193972F2BECF12DDEDA5237F9C952F20D9E
```
1. If you are creating the IAM OIDC identity provider with the AWS CLI, Tools for Windows PowerShell, or the IAM API, providing a thumbprint is optional. If you choose not to include a thumbprint during creation, IAM will retrieve the top intermediate CA thumbprint of the OIDC IdP server certificate. After the IAM OIDC identity provider is created, you can compare this thumbprint to the thumbprint retrieved by IAM.
If you are creating the IAM OIDC identity provider in the IAM console, the console attempts to retrieve the top intermediate CA thumbprint of the OIDC IdP server certificate for you. You can compare this thumbprint to the thumbprint retrieved by IAM. After the IAM OIDC identity provider is created, you can view the thumbprint for the IAM OIDC identity provider in the **Endpoint verification** tab on the OIDC provider **Summary** console page.
**Important**
If the thumbprint you obtained does not match the one you see in the IAM OIDC identity provider thumbprint details, you should not use the OIDC provider. Instead, you should delete the created OIDC provider and then try again to create the OIDC provider after some time has passed. Verify that the thumbprints match before you use the provider. If the thumbprints still do not match after a second attempt, use the [IAM Forum](https://forums.aws.amazon.com/forum.jspa?forumID=76) to contact AWS.
## Install OpenSSL
If you don't already have OpenSSL installed, follow the instructions in this section.
**To install OpenSSL on Linux or Unix**
1. Go to [OpenSSL: Source, Tarballs](https://openssl.org/source/) (https://openssl.org/source/).
1. Download the latest source and build the package.
**To install OpenSSL on Windows**
1. Go to [OpenSSL: Binary Distributions](https://wiki.openssl.org/index.php/Binaries) (https://wiki.openssl.org/index.php/Binaries) for a list of sites from which you can install the Windows version.
1. Follow the instructions on your selected site to start the installation.
1. If you are asked to install the **Microsoft Visual C\$1\$1 2008 Redistributables ** and it is not already installed on your system, choose the download link appropriate for your environment. Follow the instructions provided by the **Microsoft Visual C\$1\$1 2008 Redistributable Setup Wizard**.
**Note**
If you are not sure whether the Microsoft Visual C\$1\$1 2008 Redistributables is already installed on your system, you can try installing OpenSSL first. The OpenSSL installer displays an alert if the Microsoft Visual C\$1\$1 2008 Redistributables is not yet installed. Make sure that you install the architecture (32-bit or 64-bit) that matches the version of OpenSSL that you install.
1. After you have installed the Microsoft Visual C\$1\$1 2008 Redistributables, select the appropriate version of the OpenSSL binaries for your environment and save the file locally. Start the **OpenSSL Setup Wizard**.
1. Follow the instructions described in the **OpenSSL Setup Wizard**.
## Configure OpenSSL
Before you use OpenSSL commands, you must configure the operating system so that it has information about the location where OpenSSL is installed.
**To configure OpenSSL on Linux or Unix**
1. At the command line, set the `OpenSSL_HOME` variable to the location of the OpenSSL installation:
```
$ export OpenSSL_HOME=path_to_your_OpenSSL_installation
```
1. Set the path to include the OpenSSL installation:
```
$ export PATH=$PATH:$OpenSSL_HOME/bin
```
**Note**
Any changes you make to environment variables with the `export` command are valid only for the current session. You can make persistent changes to the environment variables by setting them in your shell configuration file. For more information, see the documentation for your operating system.
**To configure OpenSSL on Windows**
1. Open a **Command Prompt** window.
1. Set the `OpenSSL_HOME` variable to the location of the OpenSSL installation:
```
C:\> set OpenSSL_HOME=path_to_your_OpenSSL_installation
```
1. Set the `OpenSSL_CONF` variable to the location of the configuration file in your OpenSSL installation:
```
C:\> set OpenSSL_CONF=path_to_your_OpenSSL_installation\bin\openssl.cfg
```
1. Set the path to include the OpenSSL installation:
```
C:\> set Path=%Path%;%OpenSSL_HOME%\bin
```
**Note**
Any changes you make to Windows environment variables in a **Command Prompt** window are valid only for the current command line session. You can make persistent changes to the environment variables by setting them as system properties. The exact procedures depend on what version of Windows you're using. (For example, in Windows 7, open **Control Panel**, **System and Security**, **System**. Then choose **Advanced system settings**, **Advanced** tab, **Environment Variables**.) For more information, see the Windows documentation.
# Identity-provider controls for shared OIDC providers
Identity-provider controls for shared OIDC providers
For recognized shared OpenID Connect (OIDC) identity providers (IdPs), IAM requires explicit evaluation of specific claims in role trust policies. These required claims, called *identity-provider controls*, are evaluated by IAM during role creation and trust policy updates. If the role trust policy does not evaluate the controls required by the shared OIDC IdP, the role creation or update would fail. This ensures that only authorized identities from the intended organization can assume roles and access AWS resources. This security control is crucial when OIDC providers are shared across multiple AWS customers.
Identity-provider controls will not be evaluated by IAM for existing OIDC role trust policies. For any modifications to the role trust policy for existing OIDC roles, IAM will require that identity-provider controls be included in the role trust policy.
## OIDC provider types
IAM categorizes OIDC identity providers into two distinct types: **private** and **shared**. A private OIDC IdP can be owned and managed by a single organization or can be a tenant of a SaaS provider, with its OIDC Issuer URL serving as a unique identifier specific to that organization. In contrast, a shared OIDC IdP is utilized across multiple organizations, where the OIDC Issuer URL might be identical for all organizations using that shared identity provider.
The table below outlines the key differences between private and shared OIDC providers:
| Characteristic | Private OIDC Provider | Shared OIDC Provider |
| --- | --- | --- |
| Issuer | Unique to the organization | Shared across multiple organizations |
| Tenancy Information | Communicated through unique Issuer | Communicated through claims in JWT |
| Trust Policy Requirements | No specific claim evaluation required | Evaluation of specific claims required |
## Shared OIDC identity providers with identity-provider controls
When you create or modify an OIDC provider in IAM, the system automatically identifies and evaluates required claims for recognized shared OIDC providers. If identity-provider controls are not configured in the role trust policy, the role creation or update will fail with a MalformedPolicyDocument error.
The following table lists the shared OIDC providers that require identity-provider controls in role trust policies and additional information to help you configure identity-provider controls.
| OIDC IdP | OIDC URL | Tenancy Claim | Required Claims |
| --- | --- | --- | --- |
| [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/iam-roles.html) | `cognito-identity.amazonaws.com` | aud | `cognito-identity.amazonaws.com:aud` |
| [Azure Sentinel](https://learn.microsoft.com/en-us/azure/defender-for-cloud/sentinel-connected-aws) | https://sts.windows.net/33e01921-4d64-4f8c-a055-5bdaffd5e33d | sts:RoleSessionName | sts:RoleSessionName |
| [Buildkite](https://buildkite.com/docs/pipelines/security/oidc/aws) | https://agent.buildkite.com | sub | agent.buildkite.com:sub |
| [Codefresh SaaS](https://codefresh.io/docs/docs/integrations/oidc-pipelines/) | https://oidc.codefresh.io | sub | oidc.codefresh.io:sub |
| [DVC Studio](https://dvc.org/doc/studio/user-guide/openid-connect) | https://studio.datachain.ai/api | sub | studio.datachain.ai/api:sub |
| [GitHub actions](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) | https://token.actions.githubusercontent.com | sub | token.actions.githubusercontent.com:sub |
| [GitHub audit log streaming](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise) | https://oidc-configuration.audit-log.githubusercontent.com | sub | oidc-configuration.audit-log.githubusercontent.com:sub |
| [GitHub vstoken](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) | https://vstoken.actions.githubusercontent.com | sub | vstoken.actions.githubusercontent.com:sub |
| [GitLab](https://docs.gitlab.com/ci/cloud_services/aws/) | https://gitlab.com | sub | gitlab.com:sub |
| [IBM Turbonomic SaaS\$1](https://www.ibm.com/docs/en/tarm/8.16.x?topic=turbonomic-setting-up-aws-iam-role-saas-deployments) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc_secure-by-default.html) | sub | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc_secure-by-default.html) |
| [Pulumi Cloud](https://www.pulumi.com/docs/pulumi-cloud/deployments/oidc/aws/) | https://api.pulumi.com/oidc | aud | api.pulumi.com/oidc:aud |
| [sandboxes.cloud](https://docs.sandboxes.cloud/docs/cloud-resources-setup) | https://sandboxes.cloud | aud | sandboxes.cloud:aud |
| [Scalr](https://docs.scalr.io/docs/aws) | https://scalr.io | sub | scalr.io:sub |
| [Shisho Cloud](https://shisho.dev/docs/g/getting-started/integrate-apps/aws/) | https://tokens.cloud.shisho.dev | sub | tokens.cloud.shisho.dev:sub |
| [Terraform Cloud](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/dynamic-provider-credentials/aws-configuration) | https://app.terraform.io | sub | app.terraform.io:sub |
| [Upbound](https://docs.upbound.io/providers/provider-aws/authentication/) | https://proidc.upbound.io | sub | proidc.upbound.io:sub |
| [Vercel global endpoint](https://vercel.com/docs/oidc/reference) | https://oidc.vercel.com | aud | oidc.vercel.com:aud |
\$1 IBM Turbonomic periodically updates their OIDC Issuer URL with new versions of the platform. We will add additional Turbonomic OIDC issuers in scope as a shared provider as needed.
For any new OIDC IdPs that IAM identifies as shared, the required identity-provider controls for role trust policies will be documented and enforced in a similar manner.
## Additional resources
Additional resources:
+ For more information about creating an IAM role for OIDC federation, see [Create a role for OpenID Connect federation (console)](id_roles_create_for-idp_oidc.md).
+ For a list of IAM condition keys that can be used for claims, see [Available keys for AWS OIDC federation](reference_policies_iam-condition-keys.md#condition-keys-wif).