# Identity providers and federation into AWS


As a best practice, we recommend that you require human users to use federation with an identity provider to access AWS resources instead of creating individual IAM users in your AWS account. With an identity provider (IdP), you can manage your user identities outside of AWS and give these external user identities permissions to use AWS resources in your account. This is useful if your organization already has its own identity system, such as a corporate user directory. It is also useful if you are creating a mobile app or web application that requires access to AWS resources.

**Note**  
You can also manage human users in [IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/what-is.html) with an external SAML identity provider instead of using SAML federation in IAM. IAM Identity Center federation with an identity provider provides the capability for you to give people access to multiple AWS accounts in your organization and to multiple AWS applications. For information about specific situations where an IAM user is required, see [When to create an IAM user (instead of a role)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html#id_which-to-choose).

If you prefer to use a single AWS account without enabling IAM Identity Center, you can use IAM with an external IdP that provides identity information to AWS using either [OpenID Connect (OIDC)](http://openid.net/connect/) or [SAML 2.0 (Security Assertion Markup Language 2.0)](https://wiki.oasis-open.org/security). OIDC connects applications, like GitHub Actions, that do not run on AWS to AWS resources. Examples of well-known SAML identity providers are Shibboleth and Active Directory Federation Services.

When you use an identity provider, you don't have to create custom sign-in code or manage your own user identities. The IdP provides that for you. Your external users sign in through an IdP, and you can give those external identities permissions to use AWS resources in your account. Identity providers help keep your AWS account secure because you don't have to distribute or embed long-term security credentials, such as access keys, in your application.

Review the following table to help determine which IAM federation type is best for your use case; IAM, IAM Identity Center, or Amazon Cognito. The following summaries and table provide an overview of the methods that your users can employ to gain federated access to AWS resources.


| IAM federation type | Account type | Access management of.. | Supported identity source | 
| --- | --- | --- | --- | 
|  Federation with IAM Identity Center  |  Multiple accounts managed by AWS Organizations  |  Your workforce’s human users  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)  | 
|  Federation with IAM  |  Single, standalone account  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)  | 
|  Federation with Amazon Cognito identity pools  |  Any  |  The users of apps that require IAM authorization to access resources  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)  | 

## Federation with IAM Identity Center


For centralized access management of human users, we recommend that you use [IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) to manage access to your accounts and permissions within those accounts. Users in IAM Identity Center are granted short-term credentials to your AWS resources. You can use Active Directory, an external identity provider (IdP), or an IAM Identity Center directory as the identity source for users and groups to assign access to your AWS resources. 

IAM Identity Center supports identity federation with SAML (Security Assertion Markup Language) 2.0 to provide federated single sign-on access for users who are authorized to use applications within the AWS access portal. Users can then single sign-on into services that support SAML, including the AWS Management Console and third-party applications, such as Microsoft 365, SAP Concur, and Salesforce.

## Federation with IAM


While we strongly recommend managing human users in IAM Identity Center, you can enable federated principal access with IAM for human users in short-term, small scale deployments. IAM allows you to use separate SAML 2.0 and Open ID Connect (OIDC) IdPs and use federated principal attributes for access control. With IAM, you can pass user attributes, such as cost center, title, or locale, from your IdPs to AWS, and implement fine-grained access permissions based on these attributes.

A *workload* is a collection of resources and code that delivers business value, such as an application or backend process. Your workload can require an IAM identity to make requests to AWS services, applications, operational tools, and components. These identities include machines running in your AWS environments, such as Amazon EC2 instances or AWS Lambda functions.

You can also manage machine identities for external parties who need access. To give access to machine identities, you can use IAM roles. IAM roles have specific permissions and provide a way to access AWS by relying on temporary security credentials with a role session. Additionally, you might have machines outside of AWS that need access to your AWS environments. For machines that run outside of AWS you can use [IAM Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html). For more information about roles, see [IAM roles](id_roles.md). For details about how to use roles to delegate access across AWS accounts, see [IAM tutorial: Delegate access across AWS accounts using IAM roles](tutorial_cross-account-with-roles.md).

To link an IdP directly to IAM, you create an identity provider entity to establish a trust relationship between your AWS account and the IdP. IAM supports IdPs that are compatible with [OpenID Connect (OIDC)](http://openid.net/connect/) or [SAML 2.0 (Security Assertion Markup Language 2.0)](https://wiki.oasis-open.org/security). For more information about using one of these IdPs with AWS, see the following sections:
+ [OIDC federation](id_roles_providers_oidc.md)
+ [SAML 2.0 federation](id_roles_providers_saml.md)

## Federation with Amazon Cognito identity pools


Amazon Cognito is designed for developers who want to authenticate and authorize users in their mobile and web apps. Amazon Cognito user pools add sign-in and sign-up features to your app, and identity pools deliver IAM credentials that grant your users access to protected resources that you manage in AWS. Identity pools acquire credentials for temporary sessions through the [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) API operation.

Amazon Cognito works with external identity providers that support SAML and OpenID Connect, and with social identity providers like Facebook, Google, and Amazon. Your app can sign in a user with a user pool or an external IdP, then retrieve resources on their behalf with customized temporary sessions in an IAM role.

## Additional resources

+ For a demonstration on how to create a custom federation proxy that enables single sign-on (SSO) into the AWS Management Console using your organization's authentication system, see [Enable custom identity broker access to the AWS console](id_roles_providers_enable-console-custom-url.md).

# Common scenarios


**Note**  
We recommend that you require your human users to use temporary credentials when accessing AWS. Have you considered using AWS IAM Identity Center? You can use IAM Identity Center to centrally manage access to multiple AWS accounts and provide users with MFA-protected, single sign-on access to all their assigned accounts from one place. With IAM Identity Center, you can create and manage user identities in IAM Identity Center or easily connect to your existing SAML 2.0 compatible identity provider. For more information, see [What is IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) in the *AWS IAM Identity Center User Guide*.

You can use an external identity provider (IdP) to manage user identities outside of AWS and the external IdP. An external IdP can provide identity information to AWS using either OpenID Connect (OIDC) or Security Assertion Markup Language (SAML). OIDC is commonly used when an application that does not run on AWS needs access to AWS resources.

When you want to configure federation with an external IdP, you create an IAM *identity provider* to inform AWS about the external IdP and its configuration. This establishes trust between your AWS account and the external IdP. The following topics provide common scenarios to use IAM identity providers.

**Topics**
+ [

## Amazon Cognito for mobile apps
](#id_roles_providers_oidc_cognito)
+ [

## OIDC federation for mobile apps
](#id_roles_providers_oidc_manual)

## Amazon Cognito for mobile apps


The preferred way to use OIDC federation is to use [Amazon Cognito](https://aws.amazon.com/cognito/). For example, Adele the developer is building a game for a mobile device where user data such as scores and profiles is stored in Amazon S3 and Amazon DynamoDB. Adele could also store this data locally on the device and use Amazon Cognito to keep it synchronized across devices. She knows that for security and maintenance reasons, long-term AWS security credentials should not be distributed with the game. She also knows that the game might have a large number of users. For all of these reasons, she does not want to create new user identities in IAM for each player. Instead, she builds the game so that users can sign in using an identity that they've already established with a well-known external identity provider (IdP), such as **Login with Amazon**, **Facebook**, **Google**, or any **OpenID Connect** (OIDC)-compatible IdP. Her game can take advantage of the authentication mechanism from one of these providers to validate the user's identity. 

To enable the mobile app to access her AWS resources, Adele first registers for a developer ID with her chosen IdPs. She also configures the application with each of these providers. In her AWS account that contains the Amazon S3 bucket and DynamoDB table for the game, Adele uses Amazon Cognito to create IAM roles that precisely define permissions that the game needs. If she is using an OIDC IdP, she also creates an IAM OIDC identity provider entity to establish trust between an [Amazon Cognito identity pool](https://docs.aws.amazon.com/cognito/latest/developerguide/external-identity-providers.html) in her AWS account and the IdP.

In the app's code, Adele calls the sign-in interface for the IdP that she configured previously. The IdP handles all the details of letting the user sign in, and the app gets an OAuth access token or OIDC ID token from the provider. Adele's app can trade this authentication information for a set of temporary security credentials that consist of an AWS access key ID, a secret access key, and a session token. The app can then use these credentials to access web services offered by AWS. The app is limited to the permissions that are defined in the role that it assumes.

The following figure shows a simplified flow for how this might work, using Login with Amazon as the IdP. For Step 2, the app can also use Facebook, Google, or any OIDC-compatible IdP, but that's not shown here.

![\[Sample workflow using Amazon Cognito to federate users for a mobile application\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/mobile-app-web-identity-federation.diagram.png)


 

1. A customer starts your app on a mobile device. The app asks the user to sign in.

1. The app uses Login with Amazon resources to accept the user's credentials.

1. The app uses the Amazon Cognito API operations `GetId` and `GetCredentialsForIdentity` to exchange the Login with Amazon ID token for an Amazon Cognito token. Amazon Cognito, which has been configured to trust your Login with Amazon project, generates a token that it exchanges for temporary session credentials with AWS STS.

1. The app receives temporary security credentials from Amazon Cognito. Your app can also use the Basic (Classic) workflow in Amazon Cognito to retrieve tokens from AWS STS using `AssumeRoleWithWebIdentity`. For more information, see [Identity pools (federated identities) authentication flow](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html) in the Amazon Cognito Developer Guide.

1. The temporary security credentials can be used by the app to access any AWS resources required by the app to operate. The role associated with the temporary security credentials and the assigned policies determines what can be accessed.

Use the following process to configure your app to use Amazon Cognito to authenticate users and give your app access to AWS resources. For specific steps to accomplish this scenario, consult the documentation for Amazon Cognito.

1. (Optional) Sign up as a developer with Login with Amazon, Facebook, Google, or any other OpenID Connect (OIDC)–compatible IdP and configure one or more apps with the provider. This step is optional because Amazon Cognito also supports unauthenticated (guest) access for your users.

1. Go to [Amazon Cognito in the AWS Management Console](https://console.aws.amazon.com/cognito/home). Use the Amazon Cognito wizard to create an identity pool, which is a container that Amazon Cognito uses to keep end user identities organized for your apps. You can share identity pools between apps. When you set up an identity pool, Amazon Cognito creates one or two IAM roles (one for authenticated identities, and one for unauthenticated "guest" identities) that define permissions for Amazon Cognito users. 

1. Integrate [AWS](https://docs.amplify.aws)Amplify with your app, and import the files required to use Amazon Cognito.

1. Create an instance of the Amazon Cognito credentials provider, passing the identity pool ID, your AWS account number, and the Amazon Resource Name (ARN) of the roles that you associated with the identity pool. The Amazon Cognito wizard in the AWS Management Console provides sample code to help you get started.

1. When your app accesses an AWS resource, pass the credentials provider instance to the client object, which passes temporary security credentials to the client. The permissions for the credentials are based on the role or roles that you defined earlier.

For more information, see the following:
+ [Sign in (Android)](https://docs.amplify.aws/lib/auth/signin/q/platform/android/) in the AWS Amplify Framework Documentation. 
+ [Sign in (iOS)](https://docs.amplify.aws/lib/auth/signin/q/platform/ios/) in the AWS Amplify Framework Documentation.

## OIDC federation for mobile apps


For best results, use Amazon Cognito as your identity broker for almost all OIDC federation scenarios. Amazon Cognito is easy to use and provides additional capabilities like anonymous (unauthenticated) access, and synchronizing user data across devices and providers. However, if you have already created an app that uses OIDC federation by manually calling the `AssumeRoleWithWebIdentity` API, you can continue to use it and your apps will still work fine. 

The process for using OIDC federation ***without*** Amazon Cognito follows this general outline: 

1. Sign up as a developer with the external identity provider (IdP) and configure your app with the IdP, who gives you a unique ID for your app. (Different IdPs use different terminology for this process. This outline uses the term *configure* for the process of identifying your app with the IdP.) Each IdP gives you an app ID that's unique to that IdP, so if you configure the same app with multiple IdPs, your app will have multiple app IDs. You can configure multiple apps with each provider. 

   The following external links provide information about using some of the commonly used identity providers (IdPs): 
   + [Login with Amazon Developer Center](https://login.amazon.com/) 
   + [Add Facebook Login to Your App or Website](https://developers.facebook.com/docs/facebook-login/v2.1) on the Facebook developers site. 
   + [Using OAuth 2.0 for Login (OpenID Connect)](https://developers.google.com/accounts/docs/OAuth2Login) on the Google developers site.
**Important**  
If you use an OIDC identity provider from Google, Facebook, or Amazon Cognito, do not create a separate IAM identity provider in the AWS Management Console. AWS has these OIDC identity providers built-in and available for your use. Skip the following step and move directly to creating new roles using your identity provider.

1. If you use an IdP other than Google, Facebook or Amazon Cognito compatible with OIDC, then create an IAM identity provider entity for it.

1. In IAM, [create one or more roles](id_roles_create_for-idp.md). For each role, define who can assume the role (the trust policy) and what permissions the app's users have (the permissions policy). Typically, you create one role for each IdP that an app supports. For example, you might create a role assumed by an app if the user signs in through Login with Amazon, a second role for the same app if the user signs in through Facebook, and a third role for the app if the user signs in through Google. For the trust relationship, specify the IdP (like Amazon.com) as the `Principal` (the trusted entity), and include a `Condition` that matches the IdP assigned app ID. Examples of roles for different providers are described in [Create a role for a third-party identity provider](id_roles_create_for-idp.md). 

1. In your application, authenticate your users with the IdP. The specifics of how to do this vary both according to which IdP you use (Login with Amazon, Facebook, or Google) and on which platform your app runs. For example, an Android app's method of authentication can differ from that of an iOS app or a JavaScript-based web app.

   Typically, if the user is not already signed in, the IdP takes care of displaying a sign-in page. After the IdP authenticates the user, the IdP returns an authentication token with information about the user to your app. The information included depends on what the IdP exposes and what information the user is willing to share. You can use this information in your app.

1. In your app, make an *unsigned* call to the `AssumeRoleWithWebIdentity` action to request temporary security credentials. In the request, you pass the IdP's authentication token and specify the Amazon Resource Name (ARN) for the IAM role that you created for that IdP. AWS verifies that the token is trusted and valid and if so, returns temporary security credentials to your app that have the permissions for the role that you name in the request. The response also includes metadata about the user from the IdP, such as the unique user ID that the IdP associates with the user.

1. Using the temporary security credentials from the `AssumeRoleWithWebIdentity` response, your app makes signed requests to AWS API operations. The user ID information from the IdP can distinguish users in your app. For example, you can put objects into Amazon S3 folders that include the user ID as prefixes or suffixes. This lets you create access control policies that lock the folder so only the user with that ID can access it. For more information, see [AWS STS federated user principals](reference_policies_elements_principal.md#sts-session-principals).

1. Your app should cache the temporary security credentials so that you do not have to get new ones each time the app needs to make a request to AWS. By default, the credentials are good for one hour. When the credentials expire (or before then), you make another call to `AssumeRoleWithWebIdentity` to obtain a new set of temporary security credentials. Depending on the IdP and how they manage their tokens, you might have to refresh the IdP's token before you make a new call to `AssumeRoleWithWebIdentity`, since the IdP's tokens also usually expire after a fixed time. If you use the AWS SDK for iOS or the AWS SDK for Android, you can use the [AmazonSTSCredentialsProvider](https://aws.amazon.com/blogs/mobile/using-the-amazoncredentialsprovider-protocol-in-the-aws-sdk-for-ios) action, which manages the IAM temporary credentials, including refreshing them as required.

# 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. <a name="idpoidcstep1"></a>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. <a name="thumbstep2"></a>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).

# SAML 2.0 federation


AWS supports identity federation with [SAML 2.0 (Security Assertion Markup Language 2.0)](https://wiki.oasis-open.org/security), an open standard that many identity providers (IdPs) use. This feature enables federated single sign-on (SSO), so users can log into the AWS Management Console or call AWS API operations without you having to create an IAM user for everyone in your organization. By using SAML, you can simplify the process of configuring federation with AWS, because you can use the IdP's service instead of [writing custom identity proxy code](https://docs.aws.amazon.com/STS/latest/UsingSTS/CreatingFedTokens.html).

**Note**  
IAM SAML identity federation supports encrypted SAML responses from SAML-based federated identity providers (IdPs). IAM Identity Center and Amazon Cognito do not support encrypted SAML assertions from IAM SAML identity providers.  
You can indirectly add support for encrypted SAML assertions to Amazon Cognito identity pool federation with Amazon Cognito user pools. User pools have SAML federation that's independent of IAM SAML federation and supports [SAML signing and encryption](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-SAML-signing-encryption.html). Although this feature doesn't extend directly to identity pools, user pools can be IdPs to identity pools. To use SAML encryption with identity pools, add a SAML provider with encryption to a user pool that is an IdP to an identity pool.  
Your SAML provider must be able to encrypt SAML assertions with a key that your user pool provides. User pools won't accept assertions encrypted with a certificate that IAM has provided.

IAM federation supports these use cases: 
+ [**Federated access to allow a user or application in your organization to call AWS API operations**](#CreatingSAML-configuring). This use case is discussed in the following section. You use a SAML assertion (as part of the authentication response) that is generated in your organization to get temporary security credentials. This scenario is similar to other federation scenarios that IAM supports, like those described in [Request temporary security credentials](id_credentials_temp_request.md) and [OIDC federation](id_roles_providers_oidc.md). However, SAML 2.0–based IdPs in your organization handle many of the details at run time for performing authentication and authorization checking.
+ [**Web-based single sign-on (SSO) to the AWS Management Console from your organization**](id_roles_providers_enable-console-saml.md). Users can sign in to a portal in your organization hosted by a SAML 2.0–compatible IdP, select an option to go to AWS, and be redirected to the console without having to provide additional sign-in information. You can use a third-party SAML IdP to establish SSO access to the console or you can create a custom IdP to enable console access for your external users. For more information about building a custom IdP, see [Enable custom identity broker access to the AWS console](id_roles_providers_enable-console-custom-url.md).

**Topics**
+ [

## Using SAML-based federation for API access to AWS
](#CreatingSAML-configuring)
+ [

## Overview of configuring SAML 2.0-based federation
](#CreatingSAML-configuring-IdP)
+ [

## Overview of the role to allow SAML-federated access to your AWS resources
](#CreatingSAML-configuring-role)
+ [

## Uniquely identifying users in SAML-based federation
](#CreatingSAML-userid)
+ [

# Create a SAML identity provider in IAM
](id_roles_providers_create_saml.md)
+ [

# Configure your SAML 2.0 IdP with relying party trust and adding claims
](id_roles_providers_create_saml_relying-party.md)
+ [

# Integrate third-party SAML solution providers with AWS
](id_roles_providers_saml_3rd-party.md)
+ [

# Configure SAML assertions for the authentication response
](id_roles_providers_create_saml_assertions.md)
+ [

# Enabling SAML 2.0 federated principals to access the AWS Management Console
](id_roles_providers_enable-console-saml.md)
+ [

# View a SAML response in your browser
](troubleshoot_saml_view-saml-response.md)

## Using SAML-based federation for API access to AWS


Assume that you want to provide a way for employees to copy data from their computers to a backup folder. You build an application that users can run on their computers. On the back end, the application reads and writes objects in an Amazon S3 bucket. Users don't have direct access to AWS. Instead, the following process is used:

![\[Getting temporary security credentials based on a SAML assertion\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/saml-based-federation-diagram.png)


1. A user in your organization uses a client app to request authentication from your organization's IdP.

1. The IdP authenticates the user against your organization's identity store.

1. The IdP constructs a SAML assertion with information about the user and sends the assertion to the client app. When you enable SAML encryption for your IAM SAML IdP, this assertion is encrypted by your external IdP.

1. The client app calls the AWS STS [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API, passing the ARN of the SAML provider, the ARN of the role to assume, and the SAML assertion from IdP. If encryption is enabled, the assertion passed through the client app remains encrypted in transit.

1. (Optional) AWS STS uses the private key you uploaded from your external IdP to decrypt the encrypted SAML assertion.

1. The API response to the client app includes temporary security credentials.

1. The client app uses the temporary security credentials to call Amazon S3 API operations. 

## Overview of configuring SAML 2.0-based federation


Before you can use SAML 2.0-based federation as described in the preceding scenario and diagram, you must configure your organization's IdP and your AWS account to trust each other. The general process for configuring this trust is described in the following steps. Inside your organization, you must have an [IdP that supports SAML 2.0](id_roles_providers_saml_3rd-party.md), like Microsoft Active Directory Federation Service (AD FS, part of Windows Server), Shibboleth, or another compatible SAML 2.0 provider. 

**Note**  
To improve federation resiliency, we recommend that you configure your IdP and AWS federation to support multiple SAML sign-in endpoints. For details, see the AWS Security Blog article [How to use regional SAML endpoints for failover](https://aws.amazon.com/blogs//security/how-to-use-regional-saml-endpoints-for-failover).

**Configure your organization's IdP and AWS to trust each other**

1. Register AWS as a service provider (SP) with the IdP of your organization. Use the SAML metadata document from `https://region-code.signin.aws.amazon.com/static/saml-metadata.xml` 

   For a list of possible *region-code* values, see the **Region** column in [AWS Sign-In endpoints](https://docs.aws.amazon.com/general/latest/gr/signin-service.html).

   You can optionally use the SAML metadata document from `https://signin.aws.amazon.com/static/saml-metadata.xml` .

1. <a name="createxml"></a>Using your organization's IdP, you generate an equivalent SAML metadata XML file that can describe your IdP as an IAM identity provider in AWS. It must include the issuer name, a creation date, an expiration date, and keys that AWS can use to validate authentication responses (assertions) from your organization. 

   If you allow encrypted SAML assertions to be sent from your external IdP, you must generate a private key file using your organization's IdP, and upload this file to your IAM SAML configuration in .pem file format. AWS STS needs this private key to decrypt SAML responses that correspond to the public key uploaded to your IdP.
**Note**  
As defined by the [SAML V2.0 Metadata Interoperability Profile Version 1.0](https://docs.oasis-open.org/security/saml/Post2.0/sstc-metadata-iop-os.html), IAM does not evaluate or take action on the expiration of X.509 certificates in SAML metadata documents. If you are concerned about expired X.509 certificates, we recommend monitoring certificate expiration dates and rotating certificates according to your organization’s governance and security policies.

1. <a name="samlovrcreateentity"></a>In the IAM console, you create a SAML identity provider. As part of this process, you upload the SAML metadata document and private decryption key that was produced by the IdP in your organization in [Step 2](#createxml). For more information, see [Create a SAML identity provider in IAM](id_roles_providers_create_saml.md).

1. <a name="samlovrcreaterole"></a>In IAM, you create one or more IAM roles. In the role's trust policy, you set the SAML provider as the principal, which establishes a trust relationship between your organization and AWS. The role's permission policy establishes what users from your organization are allowed to do in AWS. For more information, see [Create a role for a third-party identity provider](id_roles_create_for-idp.md).
**Note**  
SAML IDPs used in a role trust policy must be in the same account that the role is in.

1. In your organization's IdP, you define assertions that map users or groups in your organization to the IAM roles. Note that different users and groups in your organization might map to different IAM roles. The exact steps for performing the mapping depend on what IdP you're using. In the [earlier scenario](#CreatingSAML-configuring) of an Amazon S3 folder for users, it's possible that all users will map to the same role that provides Amazon S3 permissions. For more information, see [Configure SAML assertions for the authentication response](id_roles_providers_create_saml_assertions.md).

   If your IdP enables SSO to the AWS console, then you can configure the maximum duration of the console sessions. For more information, see [Enabling SAML 2.0 federated principals to access the AWS Management Console](id_roles_providers_enable-console-saml.md).

1. In the application that you're creating, you call the AWS Security Token Service `AssumeRoleWithSAML` API, passing it the ARN of the SAML provider you created in [Step 3](#samlovrcreateentity), the ARN of the role to assume that you created in [Step 4](#samlovrcreaterole), and the SAML assertion about the current user that you get from your IdP. AWS makes sure that the request to assume the role comes from the IdP referenced in the SAML provider. 

   For more information, see [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) in the *AWS Security Token Service API Reference*. 

1. If the request is successful, the API returns a set of temporary security credentials, which your application can use to make signed requests to AWS. Your application has information about the current user and can access user-specific folders in Amazon S3, as described in the previous scenario. 

## Overview of the role to allow SAML-federated access to your AWS resources


The roles that you create in IAM define what SAML federated principals from your organization are allowed to do in AWS. When you create the trust policy for the role, you specify the SAML provider that you created earlier as the `Principal`. You can additionally scope the trust policy with a `Condition` to allow only users that match certain SAML attributes to access the role. For example, you can specify that only users whose SAML affiliation is `staff` (as asserted by https://openidp.feide.no) are allowed to access the role, as illustrated by the following sample policy:

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Federated": "arn:aws:iam::111122223333:saml-provider/ExampleOrgSSOProvider"},
    "Action": "sts:AssumeRoleWithSAML",
    "Condition": {
      "StringEquals": {
        "saml:aud": "https://us-east-1.signin.aws.amazon.com/saml",
        "saml:iss": "https://openidp.feide.no"
      },
      "ForAllValues:StringLike": {"saml:edupersonaffiliation": ["staff"]}
    }
  }]
}
```

------

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws-cn:iam::111122223333:saml-provider/ExampleOrgSSOProvider"
            },
            "Action": "sts:AssumeRoleWithSAML",
            "Condition": {
                "StringEquals": {
                    "saml:aud": "https://ap-east-1.signin.amazonaws.cn/saml",
                    "saml:iss": "https://openidp.feide.no"
                },
                "ForAllValues:StringLike": {
                    "saml:edupersonaffiliation": [
                        "staff"
                    ]
                }
            }
        }
    ]
}
```

------

**Note**  
SAML IDPs used in a role trust policy must be in the same account that the role is in.

The `saml:aud` context key in the policy specifies the URL your browser displays when signing into the console. This sign-in endpoint URL must match your identity provider's recipient attribute. You can include sign-in URLs within particular regions. AWS recommends using Regional endpoints instead of the global endpoint to improve federation resiliency. If you have only one endpoint configured, you won’t be able to federate into AWS in the unlikely event that the endpoint becomes unavailable. For a list of possible *region-code* values, see the **Region** column in [AWS Sign-In endpoints](https://docs.aws.amazon.com/general/latest/gr/signin-service.html).

The following example shows the sign-in URL format with the optional `region-code`.

`https://region-code.signin.aws.amazon.com/saml`

If SAML encryption is required, the sign-in URL must include the unique identifier AWS assigns to your SAML provider, which you can find on the Identity provider detail page. In the following example, the sign-in URL includes the IdP unique identifier, which requires /acs/ be appended to the sign-in path.

`https://region-code.signin.aws.amazon.com/saml/acs/IdP-ID`

For the permission policy in the role, you specify permissions as you would for any role. For example, if users from your organization are allowed to administer Amazon Elastic Compute Cloud instances, you must explicitly allow Amazon EC2 actions in the permissions policy, such as those in the **AmazonEC2FullAccess** managed policy. 

For more information about the SAML keys that you can check in a policy, see [Available keys for SAML-based AWS STS federation](reference_policies_iam-condition-keys.md#condition-keys-saml).

## Uniquely identifying users in SAML-based federation


When you create access policies in IAM, it's often useful to be able to specify permissions based on the identity of users. For example, for users who have been federated using SAML, an application might want to keep information in Amazon S3 using a structure like this: 

```
amzn-s3-demo-bucket/app1/user1
amzn-s3-demo-bucket/app1/user2
amzn-s3-demo-bucket/app1/user3
```

You can create the bucket (`amzn-s3-demo-bucket`) and folder (`app1`) through the Amazon S3 console or the AWS CLI, since those are static values. However, the user-specific folders (*user1*, *user2*, *user3*, etc.) have to be created at run time using code, since the value that identifies the user isn't known until the first time the user signs in through the federation process. 

To write policies that reference user-specific details as part of a resource name, the user identity has to be available in SAML keys that can be used in policy conditions. The following keys are available for SAML 2.0–based federation for use in IAM policies. You can use the values returned by the following keys to create unique user identifiers for resources like Amazon S3 folders. 
+ `saml:namequalifier`. A hash value based on the concatenation of the `Issuer` response value (`saml:iss`) and a string with the `AWS` account ID and the friendly name (the last part of the ARN) of the SAML provider in IAM. The concatenation of the account ID and friendly name of the SAML provider is available to IAM policies as the key `saml:doc`. The account ID and provider name must be separated by a '/' as in "123456789012/provider\$1name". For more information, see the `saml:doc` key at [Available keys for SAML-based AWS STS federation](reference_policies_iam-condition-keys.md#condition-keys-saml).

  The combination of `NameQualifier` and `Subject` can be used to uniquely identify a SAML federated principal. The following pseudocode shows how this value is calculated. In this pseudocode `+` indicates concatenation, `SHA1` represents a function that produces a message digest using SHA-1, and `Base64` represents a function that produces Base-64 encoded version of the hash output.

   `Base64 ( SHA1 ( "https://example.com/saml" + "123456789012" + "/MySAMLIdP" ) )` 

   For more information about the policy keys that are available for SAML-based federation, see [Available keys for SAML-based AWS STS federation](reference_policies_iam-condition-keys.md#condition-keys-saml).
+ `saml:sub` (string). This is the subject of the claim, which includes a value that uniquely identifies an individual user within an organization (for example, `_cbb88bf52c2510eabe00c1642d4643f41430fe25e3`). 
+ `saml:sub_type` (string). This key can be `persistent`, `transient`, or the full `Format` URI from the `Subject` and `NameID` elements used in your SAML assertion. A value of `persistent` indicates that the value in `saml:sub` is the same for a user across all sessions. If the value is `transient`, the user has a different `saml:sub` value for each session. For information about the `NameID` element's `Format` attribute, see [Configure SAML assertions for the authentication response](id_roles_providers_create_saml_assertions.md). 

The following example shows a permission policy that uses the preceding keys to grant permissions to a user-specific folder in Amazon S3. The policy assumes that the Amazon S3 objects are identified using a prefix that includes both `saml:namequalifier` and `saml:sub`. Notice that the `Condition` element includes a test to be sure that `saml:sub_type` is set to `persistent`. If it is set to `transient`, the `saml:sub` value for the user can be different for each session, and the combination of values should not be used to identify user-specific folders. 

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "s3:GetObject",
      "s3:PutObject",
      "s3:DeleteObject"
    ],
    "Resource": [
      "arn:aws:s3:::amzn-s3-demo-bucket-org-data/backup/${saml:namequalifier}/${saml:sub}",
      "arn:aws:s3:::amzn-s3-demo-bucket-org-data/backup/${saml:namequalifier}/${saml:sub}/*"
    ],
    "Condition": {"StringEquals": {"saml:sub_type": "persistent"}}
  }
}
```

------

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "s3:GetObject",
      "s3:PutObject",
      "s3:DeleteObject"
    ],
    "Resource": [
      "arn:aws-cn:s3:::amzn-s3-demo-bucket-org-data/backup/${saml:namequalifier}/${saml:sub}",
      "arn:aws-cn:s3:::amzn-s3-demo-bucket-org-data/backup/${saml:namequalifier}/${saml:sub}/*"
    ],
    "Condition": {"StringEquals": {"saml:sub_type": "persistent"}}
  }
}
```

------

For more information about mapping assertions from the IdP to policy keys, see [Configure SAML assertions for the authentication response](id_roles_providers_create_saml_assertions.md). 

# Create a SAML identity provider in IAM
Create SAML identity provider

An IAM SAML 2.0 identity provider is an entity in IAM that describes an external identity provider (IdP) service that supports the [SAML 2.0 (Security Assertion Markup Language 2.0)](https://wiki.oasis-open.org/security) standard. You use an IAM identity provider when you want to establish trust between a SAML-compatible IdP such as Shibboleth or Active Directory Federation Services and AWS, so that your users can access AWS resources. IAM SAML identity providers are used as principals in an IAM trust policy. 

For more information about this scenario, see [SAML 2.0 federation](id_roles_providers_saml.md).

You can create and manage an IAM identity provider in the AWS Management Console or with AWS CLI, Tools for Windows PowerShell, or AWS API calls. 

After you create a SAML 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 a SAML federated principal that is authenticated by your IdP. The role permits your 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 SAML federation, see [Create a role for a third-party identity provider](id_roles_create_for-idp.md). 

Finally, after you create the role, you complete the SAML trust by configuring your IdP with information about AWS and the roles that you want your SAML federated principals to use. This is referred to as configuring relying party trust between your IdP and AWS. To configure relying party trust, see [Configure your SAML 2.0 IdP with relying party trust and adding claims](id_roles_providers_create_saml_relying-party.md). 

**Topics**
+ [

## Prerequisites
](#idp-manage-identityprovider-prerequisites)
+ [

## Create and manage an IAM SAML identity provider (console)
](#idp-manage-identityprovider-console)
+ [

## Manage SAML encryption keys
](#id_federation_manage-saml-encryption)
+ [

## Create and manage an IAM SAML Identity Provider (AWS CLI)
](#idp-create-identityprovider-CLI)
+ [

## Create and manage an IAM SAML identity provider (AWS API)
](#idp-create-identityprovider-API)
+ [

## Next steps
](#id_roles_create-for-saml-next-steps)

## Prerequisites


Before you can create a SAML identity provider, you must have the following information from your IdP.
+ Get the SAML metadata document from your IdP. This document includes the issuer's name, expiration information, and keys that can be used to validate the SAML authentication response (assertions) that are received from the IdP. To generate the metadata document, use the identity management software provided by your external IdP.
**Important**  
This metadata file includes the issuer name, expiration information, and keys that can be used to validate the SAML authentication response (assertions) received from the IdP. The metadata file must be encoded in UTF-8 format without a byte order mark (BOM). To remove the BOM, you can encode the file as UTF-8 using a text editing tool, such as Notepad\$1\$1.  
The X.509 certificate included as part of the SAML metadata document must use a key size of at least 1024 bits. Also, the X.509 certificate must also be free of any repeated extensions. You can use extensions, but the extensions can only appear once in the certificate. If the X.509 certificate does not meet either condition, IdP creation fails and returns an "Unable to parse metadata" error.  
As defined by the [SAML V2.0 Metadata Interoperability Profile Version 1.0](https://docs.oasis-open.org/security/saml/Post2.0/sstc-metadata-iop-os.html), IAM does not evaluate or take action on the expiration of X.509 certificates in SAML metadata documents. If you are concerned about expired X.509 certificates, we recommend monitoring certificate expiration dates and rotating certificates according to your organization’s governance and security policies.
+ When you choose to enable SAML encryption, you must generate a private key file using your IdP, and upload this file to your IAM SAML configuration in .pem file format. AWS STS needs this private key to decrypt SAML responses that correspond to the public key uploaded to your IdP. The following algorithms are supported:
  + Encryption algorithms
    + AES-128
    + AES-256
    + RSA-OAEP
  + Key transport algorithms
    + AES-CBC
    + AES-GCM

  See your identity provider's documentation for steps to generate a private key.
**Note**  
IAM Identity Center and Amazon Cognito do not support encrypted SAML assertions from IAM SAML identity providers. You can indirectly add support for encrypted SAML assertions to Amazon Cognito identity pool federation with Amazon Cognito user pools. User pools have SAML federation that's independent of IAM SAML federation and supports [SAML signing and encryption](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-SAML-signing-encryption.html). Although this feature doesn't extend directly to identity pools, user pools can be IdPs to identity pools. To use SAML encryption with identity pools, add a SAML provider with encryption to a user pool that is an IdP to an identity pool.  
Your SAML provider must be able to encrypt SAML assertions with a key that your user pool provides. User pools won't accept assertions encrypted with a certificate that IAM has provided.

For instructions on how to configure many of the available IdPs to work with AWS, including how to generate the required SAML metadata document, see [Integrate third-party SAML solution providers with AWS](id_roles_providers_saml_3rd-party.md).

For help with SAML federation, see [Troubleshooting SAML federation](troubleshoot_saml.md).

## Create and manage an IAM SAML identity provider (console)


You can use the AWS Management Console to create, update, and delete IAM SAML identity providers. For help with SAML federation, see [Troubleshooting SAML federation](troubleshoot_saml.md).

**To create an IAM SAML identity provider (console)**

1. Sign in to the AWS Management Console and 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 **SAML**. 

1. Type a name for the identity provider.

1. For **Metadata document**, choose **Choose file**, specify the SAML metadata document that you downloaded in [Prerequisites](#idp-manage-identityprovider-prerequisites).
**Note**  
The `validUntil` or `cacheDuration` attribute in your SAML metadata document defines the **Valid until** date for the identity provider. If your SAML metadata document does not include a validity period attribute, the **Valid until** date will not match your X.509 certificate expiration date.  
IAM does not evaluate or take action on the expiration of X.509 certificates in SAML metadata documents. If you are concerned about expired X.509 certificates, we recommend monitoring certificate expiration dates and rotating certificates according to your organization’s governance and security policies.

1. (Optional) For **SAML encryption**, choose **Choose file** and select the private key file that you created in [Prerequisites](#idp-manage-identityprovider-prerequisites). Choose **Require encryption** to accept only encrypted requests from your IdP.

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 SAML identity providers, see [Tag IAM SAML identity providers](id_tags_saml.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**. 

1. Assign an IAM role to your identity provider. This role gives 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**  
SAML IDPs used in a role trust policy must be in the same account that the role is in.

**To delete a SAML provider (console)**

1. Sign in to the AWS Management Console and 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 radio button next to the identity provider that you want to delete.

1. Choose **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**.

## Manage SAML encryption keys


You can configure IAM SAML providers to receive encrypted assertions in the SAML response from your external IdP. Users can assume a role in AWS with encrypted SAML assertions by calling `[sts:AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)`.

SAML encryption ensures that assertions are secure when passed through intermediaries or third parties. In addition, this feature helps you meet FedRAMP or any internal compliance policy requirements that mandate SAML assertions to be encrypted.

To configure an IAM SAML identity provider, see [Create a SAML identity provider in IAM](#id_roles_providers_create_saml). For help with SAML federation, see [Troubleshooting SAML federation](troubleshoot_saml.md).

### Rotate SAML encryption key


IAM uses the private key you uploaded to the IAM SAML provider to decrypt encrypted SAML assertions from your IdP. You can save up to two private key files for each identity provider, allowing you to rotate private keys as necessary. When two files are saved, each request will first attempt to decrypt with the newest **Added on** date, then IAM attempts to decrypt the request with the oldest **Added on** date.

1. Sign in to the AWS Management Console and 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 select your provider from the list. 

1. Choose the **SAML encryption** tab and choose **Add new key**.

1. Select **Choose file** and upload the private key you downloaded from your IdP as a .pem file.Then, choose **Add key**.

1. In the **Private keys for SAML decryption** section, select the expired private key file and choose **Remove**. We recommend you remove the expired private key after adding a new private key to ensure the first attempt to decrypt your assertion is successful.

## Create and manage an IAM SAML Identity Provider (AWS CLI)


You can use the AWS CLI to create, update, and delete SAML providers. For help with SAML federation, see [Troubleshooting SAML federation](troubleshoot_saml.md).

**To create an IAM identity provider and upload a metadata document (AWS CLI)**
+ Run this command: [https://docs.aws.amazon.com/cli/latest/reference/iam/create-saml-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/create-saml-provider.html) 

**To update an IAM SAML identity provider (AWS CLI)**

You can update the metadata file, SAML encryption settings, and rotate private key decryption files for your IAM SAML provider. To rotate private keys, add your new private key and then remove the old key in a separate request. For more information about rotating private keys, see [Manage SAML encryption keys](#id_federation_manage-saml-encryption).
+ Run this command:[https://docs.aws.amazon.com/cli/latest/reference/iam/update-saml-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/update-saml-provider.html) 

**To tag an existing IAM identity provider (AWS CLI)**
+ Run this command:[https://docs.aws.amazon.com/cli/latest/reference/iam/tag-saml-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-saml-provider.html) 

**To list tags for existing IAM identity provider (AWS CLI)**
+ Run this command:[https://docs.aws.amazon.com/cli/latest/reference/iam/list-saml-provider-tags.html](https://docs.aws.amazon.com/cli/latest/reference/iam/list-saml-provider-tags.html) 

**To remove tags on an existing IAM identity provider (AWS CLI)**
+ Run this command:[https://docs.aws.amazon.com/cli/latest/reference/iam/untag-saml-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/untag-saml-provider.html) 

**To delete an IAM SAML identity provider (AWS CLI)**

1. (Optional) To list information for all providers, such as the ARN, creation date, and expiration, run the following command:
   + [https://docs.aws.amazon.com/cli/latest/reference/iam/list-saml-providers.html](https://docs.aws.amazon.com/cli/latest/reference/iam/list-saml-providers.html)

1. (Optional) To get information about a specific provider, such as the ARN, creation date, expiration date, encryption settings, and private key information, run the following command:
   + [https://docs.aws.amazon.com/cli/latest/reference/iam/get-saml-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/get-saml-provider.html)

1. To delete an IAM identity provider, run the following command:
   + [https://docs.aws.amazon.com/cli/latest/reference/iam/delete-saml-provider.html](https://docs.aws.amazon.com/cli/latest/reference/iam/delete-saml-provider.html)

## Create and manage an IAM SAML identity provider (AWS API)


You can use the AWS API to create, update, and delete SAML providers. For help with SAML federation, see [Troubleshooting SAML federation](troubleshoot_saml.md).

**To create an IAM identity provider and upload a metadata document (AWS API)**
+ Call this operation: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateSAMLProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateSAMLProvider.html)

**To update an IAM SAML identity provider (AWS API)**

You can update the metadata file, SAML encryption settings, and rotate private key decryption files for your IAM SAML provider. To rotate private keys, add your new private key and then remove the old key in a separate request. For more information about rotating private keys, see [Manage SAML encryption keys](#id_federation_manage-saml-encryption).
+ Call this operation: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateSAMLProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateSAMLProvider.html)

**To tag an existing IAM identity provider (AWS API)**
+ Call this operation: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagSAMLProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagSAMLProvider.html)

**To list tags for an existing IAM identity provider (AWS API)**
+ Call this operation: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListSAMLProviderTags.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListSAMLProviderTags.html)

**To remove tags on an existing IAM identity provider (AWS API)**
+ Call this operation: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagSAMLProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagSAMLProvider.html)

**To delete an IAM identity provider (AWS API)**

1. (Optional) To list information for all IdPs, such as the ARN, creation date, and expiration, call the following operation:
   + [https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListSAMLProviders.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListSAMLProviders.html)

1. (Optional) To get information about a specific provider, such as the ARN, creation date, expiration date, encryption settings, and private key information, call the following operation:
   + [https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetSAMLProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetSAMLProvider.html)

1. To delete an IdP, call the following operation:
   + [https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteSAMLProvider.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteSAMLProvider.html)

## Next steps


After you create a SAML identity provider, set up the relying party trust with your IdP. You can also use claims from your IdP's authentication response in policies to control access to a role.
+ You must tell the IdP about AWS as a service provider. This is called adding relying party trust between your IdP and AWS. The exact process for adding relying party trust depends on what IdP you're using. For details, see [Configure your SAML 2.0 IdP with relying party trust and adding claims](id_roles_providers_create_saml_relying-party.md).
+ When the IdP sends the response containing the claims to AWS, many of the incoming claims map to AWS context keys. You can use these context keys in IAM policies using the Condition element to control access to a role. For details, see [Configure SAML assertions for the authentication response](id_roles_providers_create_saml_assertions.md)

# Configure your SAML 2.0 IdP with relying party trust and adding claims
Configure relying party trust and claims

When you create an IAM identity provider and role for SAML access, you are telling AWS about the external identity provider (IdP) and what its users are allowed to do. Your next step is to then tell the IdP about AWS as a service provider. This is called adding *relying party trust* between your IdP and AWS. The exact process for adding relying party trust depends on what IdP you're using. For details, see the documentation for your identity management software. 

Many IdPs allow you to specify a URL from which the IdP can read an XML document that contains relying party information and certificates. For AWS, use the sign-in endpoint URL. The following example shows the URL format with the optional `region-code`.

`https://region-code.signin.aws.amazon.com/static/saml-metadata.xml`

If SAML encryption is required, the URL must include the unique identifier AWS assigns to your SAML provider, which you can find on the Identity provider detail page. The following example shows a regional sign-in URL that includes a unique identifier.

`https://region-code.signin.aws.amazon.com/static/saml/IdP-ID/saml-metadata.xml`

For a list of possible *region-code* values, see the **Region** column in [AWS Sign-In endpoints](https://docs.aws.amazon.com/general/latest/gr/signin-service.html). For the AWS value, you can also use the non-Regional endpoint `https://signin.aws.amazon.com/saml`.

If you can't specify a URL directly, then download the XML document from the preceding URL and import it into your IdP software. 

You also need to create appropriate claim rules in your IdP that specify AWS as a relying party. When the IdP sends a SAML response to the AWS endpoint, it includes a SAML *assertion* that contains one or more *claims*. A claim is information about the user and its groups. A claim rule maps that information into SAML attributes. This lets you make sure that SAML authentication responses from your IdP contain the necessary attributes that AWS uses in IAM policies to check permissions for SAML federated principals. For more information, see the following topics:
+  [Overview of the role to allow SAML-federated access to your AWS resources](id_roles_providers_saml.md#CreatingSAML-configuring-role). This topic discusses using SAML-specific keys in IAM policies and how to use them to restrict permissions for SAML federated principals.
+ [Configure SAML assertions for the authentication response](id_roles_providers_create_saml_assertions.md). This topic discusses how to configure SAML claims that include information about the user. The claims are bundled into a SAML assertion and included in the SAML response that is sent to AWS. You must ensure that the information needed by AWS policies is included in the SAML assertion in a form that AWS can recognize and use.
+  [Integrate third-party SAML solution providers with AWS](id_roles_providers_saml_3rd-party.md). This topic provides links to documentation provided by third-party organizations about how to integrate identity solutions with AWS. 

**Note**  
To improve federation resiliency, we recommend that you configure your IdP and AWS federation to support multiple SAML sign-in endpoints. For details, see the AWS Security Blog article [How to use regional SAML endpoints for failover](https://aws.amazon.com/blogs//security/how-to-use-regional-saml-endpoints-for-failover).

# Integrate third-party SAML solution providers with AWS


**Note**  
We recommend that you require your human users to use temporary credentials when accessing AWS. Have you considered using AWS IAM Identity Center? You can use IAM Identity Center to centrally manage access to multiple AWS accounts and provide users with MFA-protected, single sign-on access to all their assigned accounts from one place. With IAM Identity Center, you can create and manage user identities in IAM Identity Center or easily connect to your existing SAML 2.0 compatible identity provider. For more information, see [What is IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) in the *AWS IAM Identity Center User Guide*.

The following links help you configure third-party SAML 2.0 identity provider (IdP) solutions to work with AWS federation. Check with your identity provider to determine whether they support SAML token encryption. For SAML encryption requirements, see [Manage SAML encryption keys](id_roles_providers_create_saml.md#id_federation_manage-saml-encryption).

**Tip**  
AWS Support engineers can assist customers who have business and enterprise support plans with some integration tasks that involve third-party software. For a current list of supported platforms and applications, see [What third-party software is supported?](https://aws.amazon.com/premiumsupport/faqs/#what3rdParty) in the *AWS Support FAQs*.


****  

| Solution | More information | 
| --- | --- | 
| Auth0 |  [Integrate with Amazon Web Services](https://auth0.com/docs/integrations/aws) – This page on the Auth0 documentation website has links to resources that describe how to set up single sign-on (SSO) with the AWS Management Console and includes a JavaScript example. You can configure Auth0 to pass [session tags](id_session-tags.md). For more information, see [Auth0 Announces Partnership with AWS for IAM Session Tags](https://auth0.com/blog/auth0-partners-with-aws-for-iam-session-tags/). | 
| Microsoft Entra |  [Tutorial: Microsoft Entra SSO integration with AWS Single-Account Access](https://learn.microsoft.com/en-us/azure/active-directory/saas-apps/amazon-web-service-tutorial) – This tutorial on the Microsoft website describes how to set up Microsoft Entra (formerly known as Azure AD) as an identity provider (IdP) using SAML federation. | 
| Centrify | [Configure Centrify and Use SAML for SSO to AWS](https://docs.centrify.com/Content/Applications/AppsWeb/AmazonSAML.htm) – This page on the Centrify website explains how to configure Centrify to use SAML for SSO to AWS. | 
| CyberArk | Configure [CyberArk](https://docs.cyberark.com/Product-Doc/OnlineHelp/Idaptive/Latest/en/Content/Applications/AppsWeb/AmazonSAML.htm) to provide Amazon Web Services (AWS) access to users logging in through SAML single sign-on (SSO) from the CyberArk User Portal. | 
| ForgeRock | The [ForgeRock Identity Platform](https://backstage.forgerock.com/docs/am/6.5/saml2-guide/#saml2-create-hosted-idp) integrates with AWS. You can configure ForgeRock to pass [session tags](id_session-tags.md). For more information, see [Attribute Based Access Control for Amazon Web Services](https://www.forgerock.com/blog/attribute-based-access-control-amazon-web-services). | 
| Google Workspace | [Amazon Web Services cloud application](https://support.google.com/a/answer/6194963) – This article on the Google Workspace Admin Help site describes how to configure Google Workspace as a SAML 2.0 IdP with AWS as the service provider. | 
| IBM | You can configure IBM to pass [session tags](id_session-tags.md). For more information, see [IBM Cloud Identity IDaaS one of first to support AWS session tags](https://community.ibm.com/community/user/security/blogs/adam-case/2019/11/25/ibm-cloud-identity-idaas-one-of-first-to-support-aws-session-tags). | 
| JumpCloud |  [Granting Access via IAM Roles for Single Sign On (SSO) with Amazon AWS](https://support.jumpcloud.com/support/s/article/Granting-Access-via-IAM-Roles-for-Single-Sign-On-SSO-with-Amazon-AWS) – This article on the JumpCloud website describes how to set up and enable SSO based on IAM roles for AWS. | 
| Matrix42 | [MyWorkspace Getting Started Guide](https://myworkspace.matrix42.com/documents/MyWorkspace-Getting-Started-with-AWS.pdf) – This guide describes how to integrate AWS identity services with Matrix42 MyWorkspace. | 
| Microsoft Active Directory Federation Services (AD FS) |  [Field Notes: Integrating Active Directory Federation Service with AWS IAM Identity Center](https://aws.amazon.com/blogs/architecture/field-notes-integrating-active-directory-federation-service-with-aws-single-sign-on/) – This post on the AWS Architecture Blog explains the authentication flow between AD FS and AWS IAM Identity Center (IAM Identity Center). IAM Identity Center supports identity federation with SAML 2.0, allowing integration with AD FS solutions. Users can sign in to the IAM Identity Center portal with their corporate credentials reducing the admin overhead of maintaining separate credentials on IAM Identity Center. You can also configure AD FS to pass [session tags](id_session-tags.md). For more information, see [Use attribute-based access control with AD FS to simplify IAM permissions management](https://aws.amazon.com/blogs/security/attribute-based-access-control-ad-fs-simplify-iam-permissions-management/).  | 
| miniOrange | [SSO for AWS](http://miniorange.com/amazon-web-services-%28aws%29-single-sign-on-%28sso%29) – This page on the miniOrange website describes how to establish secure access to AWS for enterprises and full control over access of AWS applications.  | 
| Okta |  [ Integrating the Amazon Web Services Command Line Interface Using Okta](https://support.okta.com/help/Documentation/Knowledge_Article/Integrating-the-Amazon-Web-Services-Command-Line-Interface-Using-Okta) – From this page on the Okta support site you can learn how to configure Okta for use with AWS. You can configure Okta to pass [session tags](id_session-tags.md). For more information, see [Okta and AWS Partner to Simplify Access Via Session Tags](https://www.okta.com/blog/2019/11/okta-and-aws-partner-to-simplify-access-via-session-tags/). | 
| Okta | [AWS Account Federation](https://help.okta.com/oie/en-us/Content/Topics/DeploymentGuides/AWS/aws-deployment.htm) – This section on the Okta website describes how to set up and enable IAM Identity Center for AWS. | 
| OneLogin | From the [OneLogin Knowledgebase](https://onelogin.service-now.com/support), search for SAML AWS for a list of articles that explain how to set up IAM Identity Center functionality between OneLogin and AWS for a single-role and multi-role scenarios. You can configure OneLogin to pass [session tags](id_session-tags.md). For more information, see [OneLogin and Session Tags: Attribute-Based Access Control for AWS Resources](https://www.onelogin.com/blog/aws-session-tags-integration). | 
| Ping Identity |  [PingFederate AWS Connector](https://support.pingidentity.com/s/marketplace-integration-details?recordId=a7i1W0000004HBwQAM) – View details about the PingFederate AWS Connector, a quick connection template to easily set up a single sign-on (SSO) and provisioning connection. Read documentation and download the latest PingFederate AWS Connector for integrations with AWS. You can configure Ping Identity to pass [session tags](id_session-tags.md). For more information, see [Announcing Ping Identity Support for Attribute-Based Access Control in AWS](https://support.pingidentity.com/s/document-item?bundleId=integrations&topicId=pon1571779451105.html).  | 
| RadiantLogic | [Radiant Logic Technology Partners](http://www.radiantlogic.com/about/partners/technology-partners/) – Radiant Logic's RadiantOne Federated Identity Service integrates with AWS to provide an identity hub for SAML-based SSO.  | 
| RSA | [Amazon Web Services - RSA Ready Implementation Guide](https://community.rsa.com/s/article/Amazon-Web-Services-RSA-Ready-Implementation-Guide) provides guidance for integrating AWS and RSA. For more information on SAML configuration, see [Amazon Web Services - SAML My Page SSO Configuration - RSA Ready Implementation Guide](https://community.rsa.com/s/article/Amazon-Web-Services-SAML-My-Page-SSO-Configuration-RSA-Ready-Implementation-Guide). | 
| Salesforce.com |  [How to configure SSO from Salesforce to AWS](https://developer.salesforce.com/page/Configuring-SAML-SSO-to-AWS) – This how-to article on the Salesforce.com developer site describes how to set up an identity provider (IdP) in Salesforce and configure AWS as a service provider.  | 
| SecureAuth |  [AWS - SecureAuth SAML SSO](https://docs.secureauth.com/2104/en/amazon-web-services--aws---idp-initiated--integration-guide.html) – This article on the SecureAuth website describes how to set up SAML integration with AWS for a SecureAuth appliance.  | 
| Shibboleth |  [How to Use Shibboleth for SSO to the AWS Management Console](https://aws.amazon.com/blogs/security/how-to-use-shibboleth-for-single-sign-on-to-the-aws-management-console) – This entry on the AWS Security Blog provides a step-by-step tutorial on how to set up Shibboleth and configure it as an identity provider for AWS. You can configure Shibboleth to pass [session tags](id_session-tags.md). | 

For more details, see the [IAM Partners](https://aws.amazon.com/iam/partners/) page on the AWS website. 

# Configure SAML assertions for the authentication response


After you have verified a user's identity in your organization, the external identity provider (IdP) sends an authentication response to the AWS sign-in endpoint URL. This response is a POST request that includes a SAML token that adheres to the [HTTP POST Binding for SAML 2.0](http://docs.oasis-open.org/security/saml/v2.0/saml-bindings-2.0-os.pdf) standard and that contains the following elements, or *claims*. You configure these claims in your SAML-compatible IdP. Refer to the documentation for your IdP for instructions on how to enter these claims.

When the IdP sends the response containing the claims to AWS, many of the incoming claims map to AWS context keys. These context keys can be checked in IAM policies using the `Condition` element. A listing of the available mappings follows in the section [Mapping SAML attributes to AWS trust policy context keys](#saml-attribute-mapping).

## `Subject` and `NameID`


The response must include exactly one `SubjectConfirmation` element with a `SubjectConfirmationData` element that includes both the `NotOnOrAfter` attribute and a `Recipient` attribute. The Recipient attribute must include a value that matches the AWS sign-in endpoint URL. Your IdP may use the the term `ACS`, `Recipient`, or `Target` to refer to this attribute.

If SAML encryption is required, the sign-in URL must include the unique identifier AWS assigns to your SAML provider, which you can find on the Identity provider detail page. The following example shows the sign-in URL format with the optional `region-code`.

`https://region-code.signin.aws.amazon.com/saml`

In the following example, the sign-in URL includes a unique identifier, which requires /acs/ be appended to the sign-in path.

`https://region-code.signin.aws.amazon.com/saml/acs/IdP-ID`

For a list of possible *region-code* values, see the **Region** column in [AWS Sign-In endpoints](https://docs.aws.amazon.com/general/latest/gr/signin-service.html). For the AWS value, you can also use the global sign-in endpoint `https://signin.aws.amazon.com/saml`.

`NameID` elements can have the value persistent, transient, or consist of the full Format URI as provided by the IdP solution. A value of persistent indicates that the value in `NameID` is the same for a user between sessions. If the value is transient, the user has a different `NameID` value for each session. Single sign-on interactions support the following types of identifiers:
+ `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`
+ `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`
+ `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
+ `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`
+ `urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName`
+ `urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName`
+ `urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos`
+ `urn:oasis:names:tc:SAML:2.0:nameid-format:entity`

The following excerpt shows an example. Substitute your own values for the marked ones.

```
<Subject>
  <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">_cbb88bf52c2510eabe00c1642d4643f41430fe25e3</NameID>
  <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
    <SubjectConfirmationData NotOnOrAfter="2013-11-05T02:06:42.876Z" Recipient="https://region-code.signin.aws.amazon.com/saml/SAMLSP4SHN3UIS2D558H46"/>
  </SubjectConfirmation>
</Subject>
```

**Important**  
The `saml:aud` context key comes from the SAML *recipient* attribute because it is the SAML equivalent to the OIDC audience field, for example, `accounts.google.com:aud`.

## `PrincipalTag` SAML attribute


(Optional) You can use an `Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/PrincipalTag:{TagKey}`. This element allows you to pass attributes as session tags in the SAML assertion. For more information about session tags, see [Pass session tags in AWS STS](id_session-tags.md).

To pass attributes as session tags, include the `AttributeValue` element that specifies the value of the tag. For example, to pass the tag key-value pairs `Project` = `Marketing` and `CostCenter` = `12345`, use the following attribute. Include a separate `Attribute` element for each tag.

```
<Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:Project">
  <AttributeValue>Marketing</AttributeValue>
</Attribute>
<Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:CostCenter">
  <AttributeValue>12345</AttributeValue>
</Attribute>
```

To set the tags above as transitive, include another `Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/TransitiveTagKeys`. This is an optional multivalued attribute that sets your session tags as transitive. Transitive tags persist when you use the SAML session to assume another role in AWS. This is known as [role chaining](id_roles.md#iam-term-role-chaining). For example, to set both the `Principal` and `CostCenter` tags as transitive, use the following attribute to specify the keys.

```
<Attribute Name="https://aws.amazon.com/SAML/Attributes/TransitiveTagKeys">
  <AttributeValue>Project</AttributeValue>
  <AttributeValue>CostCenter</AttributeValue>
</Attribute>
```

## `Role` SAML attribute


You can use an `Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/Role`. This element contains one or more `AttributeValue` elements that list the IAM identity provider and role to which the user is mapped by your IdP. The IAM role and IAM identity provider are specified as a comma-delimited pair of ARNs in the same format as the `RoleArn` and `PrincipalArn` parameters that are passed to [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html). This element must contain at least one role-provider pair (`AttributeValue` element), and can contain multiple pairs. If the element contains multiple pairs, then the user is asked to choose which role to assume when they use WebSSO to sign in to the AWS Management Console.

**Important**  
The value of the `Name` attribute in the `Attribute` tag is case-sensitive. It must be set to `https://aws.amazon.com/SAML/Attributes/Role` exactly.

```
<Attribute Name="https://aws.amazon.com/SAML/Attributes/Role">
  <AttributeValue>arn:aws:iam::account-number:role/role-name1,arn:aws:iam::account-number:saml-provider/provider-name</AttributeValue>
  <AttributeValue>arn:aws:iam::account-number:role/role-name2,arn:aws:iam::account-number:saml-provider/provider-name</AttributeValue>
  <AttributeValue>arn:aws:iam::account-number:role/role-name3,arn:aws:iam::account-number:saml-provider/provider-name</AttributeValue>
</Attribute>
```

## `RoleSessionName` SAML attribute


You can use an `Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/RoleSessionName`. This element contains one `AttributeValue` element that provides an identifier for the temporary credentials that are issued when the role is assumed. You can use this to associate the temporary credentials with the user who is using your application. This element is used to display user information in the AWS Management Console. The value in the `AttributeValue` element must be between 2 and 64 characters long, can contain only alphanumeric characters, underscores, and the following characters: **. , \$1 = @ -** (hyphen). It cannot contain spaces. The value is typically a user ID (`john`) or an email address (`johndoe@example.com`). It should not be a value that includes a space, like a user's display name (`John Doe`).

**Important**  
The value of the `Name` attribute in the `Attribute` tag is case-sensitive. It must be set to `https://aws.amazon.com/SAML/Attributes/RoleSessionName` exactly.

```
<Attribute Name="https://aws.amazon.com/SAML/Attributes/RoleSessionName">
  <AttributeValue>user-id-name</AttributeValue>
</Attribute>
```

## `SessionDuration` SAML attribute


(Optional) You can use an `Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/SessionDuration"`. This element contains one `AttributeValue` element that specifies how long the user can access the AWS Management Console before having to request new temporary credentials. The value is an integer representing the number of seconds for the session. The value can range from 900 seconds (15 minutes) to 43200 seconds (12 hours). If this attribute is not present, then the credential last for one hour (the default value of the `DurationSeconds` parameter of the `AssumeRoleWithSAML` API).

To use this attribute, you must configure the SAML provider to provide single sign-on access to the AWS Management Console through the console sign-in web endpoint at `https://region-code.signin.aws.amazon.com/saml`. For a list of possible *region-code* values, see the **Region** column in [AWS Sign-In endpoints](https://docs.aws.amazon.com/general/latest/gr/signin-service.html). You can optionally use the following URL: `https://signin.aws.amazon.com/static/saml`. Note that this attribute extends sessions only to the AWS Management Console. It cannot extend the lifetime of other credentials. However, if it is present in an `AssumeRoleWithSAML` API call, it can be used to *shorten* the duration of the session. The default lifetime of the credentials returned by the call is 60 minutes. 

Note, too, that if a `SessionNotOnOrAfter` attribute is also defined, then the ***lesser*** value of the two attributes, `SessionDuration` or `SessionNotOnOrAfter`, establishes the maximum duration of the console session.

When you enable console sessions with an extended duration the risk of compromise of the credentials rises. To help you mitigate this risk, you can immediately disable the active console sessions for any role by choosing **Revoke Sessions** on the **Role Summary** page in the IAM console. For more information, see [Revoke IAM role temporary security credentials](id_roles_use_revoke-sessions.md). 

**Important**  
The value of the `Name` attribute in the `Attribute` tag is case-sensitive. It must be set to `https://aws.amazon.com/SAML/Attributes/SessionDuration` exactly.

```
<Attribute Name="https://aws.amazon.com/SAML/Attributes/SessionDuration">
  <AttributeValue>1800</AttributeValue>
</Attribute>
```

## `SourceIdentity` SAML attribute


(Optional) You can use an `Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/SourceIdentity`. This element contains one `AttributeValue` element that provides an identifier for the person or application that is using an IAM role. The value for source identity persists when you use the SAML session to assume another role in AWS known as [role chaining](id_roles.md#iam-term-role-chaining). The value for source identity is present in the request for every action taken during the role session. The value that is set cannot be changed during the role session. Administrators can then use AWS CloudTrail logs to monitor and audit the source identity information to determine who performed actions with shared roles.

The value in the `AttributeValue` element must be between 2 and 64 characters long, can contain only alphanumeric characters, underscores, and the following characters: **. , \$1 = @ -** (hyphen). It cannot contain spaces. The value is typically an attribute that is associated with the user such as a user id (`john`) or an email address (`johndoe@example.com`). It should not be a value that includes a space, like a user's display name (`John Doe`). For more information about using source identity, see [Monitor and control actions taken with assumed roles](id_credentials_temp_control-access_monitor.md).

**Important**  
If your SAML assertion is configured to use the [`SourceIdentity`](#saml_sourceidentity) attribute, then your role trust policy must also include the `sts:SetSourceIdentity` action, otherwise the assume role operation will fail. For more information about using source identity, see [Monitor and control actions taken with assumed roles](id_credentials_temp_control-access_monitor.md).

To pass a source identity attribute, include the `AttributeValue` element that specifies the value of the source identity. For example, to pass the source identity `Diego` use the following attribute.

```
<Attribute Name="https://aws.amazon.com/SAML/Attributes/SourceIdentity">
  <AttributeValue>Diego</AttributeValue>
```

## Mapping SAML attributes to AWS trust policy context keys


The tables in this section list commonly used SAML attributes and how they map to trust policy condition context keys in AWS. You can use these keys to control access to a role. To do that, compare the keys to the values that are included in the assertions that accompany a SAML access request.

**Important**  
These keys are available only in IAM trust policies (policies that determine who can assume a role) and are not applicable to permissions policies.

In the eduPerson and eduOrg attributes table, values are typed either as strings or as lists of strings. For string values, you can test these values in IAM trust policies using `StringEquals` or `StringLike` conditions. For values that contain a list of strings, you can use the `ForAnyValue` and `ForAllValues` [policy set operators](reference_policies_condition-single-vs-multi-valued-context-keys.md#reference_policies_condition-multi-valued-context-keys) to test the values in trust policies.

**Note**  
You should include only one claim per AWS context key. If you include more than one, only one claim will be mapped. 

The following table shows eduPerson and eduOrg attributes.


| eduPerson or eduOrg attribute (`Name` key) | Maps to this AWS context key (`FriendlyName` key) | Type | 
| --- | --- | --- | 
|   `urn:oid:1.3.6.1.4.1.5923.1.1.1.1`   |   `eduPersonAffiliation`   |  List of strings  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.1.1.2`   |   `eduPersonNickname`   |  List of strings  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.1.1.3`   |   `eduPersonOrgDN`   |  String  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.1.1.4`   |   `eduPersonOrgUnitDN`   |  List of strings  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.1.1.5`   |   `eduPersonPrimaryAffiliation`   |  String  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.1.1.6`   |   `eduPersonPrincipalName`   |  String  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.1.1.7`   |   `eduPersonEntitlement`   |  List of strings  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.1.1.8`   |   `eduPersonPrimaryOrgUnitDN`   |  String  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.1.1.9`   |   `eduPersonScopedAffiliation`   |  List of strings  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.1.1.10`   |   `eduPersonTargetedID`   |  List of strings  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.1.1.11`   |   `eduPersonAssurance`   |  List of strings  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.2.1.2`   |   `eduOrgHomePageURI`   |  List of strings  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.2.1.3`   |   `eduOrgIdentityAuthNPolicyURI`   |  List of strings  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.2.1.4`   |   `eduOrgLegalName`   |  List of strings  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.2.1.5`   |   `eduOrgSuperiorURI`   |  List of strings  | 
|   `urn:oid:1.3.6.1.4.1.5923.1.2.1.6`   |   `eduOrgWhitePagesURI`   |  List of strings  | 
|   `urn:oid:2.5.4.3`   |   `cn`   |  List of strings  | 

The following table shows Active Directory attributes.


| AD attribute | Maps to this AWS context key | Type | 
| --- | --- | --- | 
|  `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`  |  `name`  |  String  | 
|  `http://schemas.xmlsoap.org/claims/CommonName`  |  `commonName`  |  String  | 
|  `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`  |  `givenName`  |  String  | 
|  `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`  |  `surname`  |  String  | 
|  `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`  |  `mail`  |  String  | 
|  `http://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid`  |  `uid`  |  String  | 

The following table shows X.500 attributes.


| X.500 attribute | Maps to this AWS context key | Type | 
| --- | --- | --- | 
|  `2.5.4.3`  |  `commonName`  |  String  | 
|  `2.5.4.4`  |  `surname`  |  String  | 
|  `2.4.5.42`  |  `givenName`  |  String  | 
|  `2.5.4.45`  |  `x500UniqueIdentifier`  |  String  | 
|  `0.9.2342.19200300100.1.1`  |  `uid`  |  String  | 
|  `0.9.2342.19200300100.1.3`  |  `mail`  |  String  | 
|  `0.9.2342.19200300.100.1.45`  |  `organizationStatus`  |  String  | 

# Enabling SAML 2.0 federated principals to access the AWS Management Console
Enable SAML federated principals access to AWS console

You can use a role to configure your SAML 2.0-compliant identity provider (IdP) and AWS to permit SAML federated principals to access the AWS Management Console. The role grants the user permissions to carry out tasks in the console. If you want to give SAML federated principals other ways to access AWS, see one of these topics:
+ AWS CLI: [Switch to an IAM role (AWS CLI)](id_roles_use_switch-role-cli.md)
+ Tools for Windows PowerShell: [Switch to an IAM role (Tools for Windows PowerShell)](id_roles_use_switch-role-twp.md)
+ AWS API: [Switch to an IAM role (AWS API)](id_roles_use_switch-role-api.md)

## Overview


The following diagram illustrates the flow for SAML-enabled single sign-on. 

**Note**  
This specific use of SAML differs from the more general one illustrated at [SAML 2.0 federation](id_roles_providers_saml.md) because this workflow opens the AWS Management Console on behalf of the user. This requires the use of the AWS sign-in endpoint instead of directly calling the `AssumeRoleWithSAML` API. The endpoint calls the API for the user and returns a URL that automatically redirects the user's browser to the AWS Management Console.

![\[Single sign-on (SSO) to the AWS Management Console using SAML\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/saml-based-sso-to-console.diagram.png)


The diagram illustrates the following steps:

1. The user browses to your organization's portal and selects the option to go to the AWS Management Console. In your organization, the portal is typically a function of your IdP that handles the exchange of trust between your organization and AWS. For example, in Active Directory Federation Services, the portal URL is: `https://ADFSServiceName/adfs/ls/IdpInitiatedSignOn.aspx` 

1. The portal verifies the user's identity in your organization.

1. The portal generates a SAML authentication response that includes assertions that identify the user and include attributes about the user. You can also configure your IdP to include a SAML assertion attribute called `SessionDuration` that specifies how long the console session is valid. You can also configure the IdP to pass attributes as [session tags](id_session-tags.md). The portal sends this response to the client browser.

1. The client browser is redirected to the AWS single sign-on endpoint and posts the SAML assertion. 

1. The endpoint requests temporary security credentials on behalf of the user and creates a console sign-in URL that uses those credentials. 

1. AWS sends the sign-in URL back to the client as a redirect.

1. The client browser is redirected to the AWS Management Console. If the SAML authentication response includes attributes that map to multiple IAM roles, the user is first prompted to select the role for accessing the console. 

From the user's perspective, the process happens transparently: The user starts at your organization's internal portal and ends up at the AWS Management Console, without ever having to supply any AWS credentials.

Consult the following sections for an overview of how to configure this behavior along with links to detailed steps.

## Configure your network as a SAML provider for AWS


Inside your organization's network, you configure your identity store (such as Windows Active Directory) to work with a SAML-based IdP like Windows Active Directory Federation Services, Shibboleth, etc. Using your IdP, you generate a metadata document that describes your organization as an IdP and includes authentication keys. You also configure your organization's portal to route user requests for the AWS Management Console to the AWS SAML endpoint for authentication using SAML assertions. How you configure your IdP to produce the metadata.xml file depends on your IdP. Refer to your IdP's documentation for instructions, or see [Integrate third-party SAML solution providers with AWS](id_roles_providers_saml_3rd-party.md) for links to the web documentation for many of the SAML providers supported.

## Create a SAML provider in IAM


Next, you sign in to the AWS Management Console and go to the IAM console. There you create a new SAML provider, which is an entity in IAM that holds information about your organization's IdP. As part of this process, you upload the metadata document produced by the IdP software in your organization in the previous section. For details, see [Create a SAML identity provider in IAM](id_roles_providers_create_saml.md). 

## Configure permissions in AWS for SAML federated principals


The next step is to create an IAM role that establishes a trust relationship between IAM and your organization's IdP. This role must identify your IdP as a principal (trusted entity) for purposes of federation. The role also defines what users authenticated by your organization's IdP are allowed to do in AWS. You can use the IAM console to create this role. When you create the trust policy that indicates who can assume the role, you specify the SAML provider that you created earlier in IAM. You also specify one or more SAML attributes that a user must match to be allowed to assume the role. For example, you can specify that only users whose SAML `[eduPersonOrgDN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_edupersonorgdn)` value is `ExampleOrg` are allowed to sign in. The role wizard automatically adds a condition to test the `saml:aud` attribute to make sure that the role is assumed only for sign-in to the AWS Management Console.

If SAML encryption is required, the sign-in URL must include the unique identifier AWS assigns to your SAML provider, which you can find on the Identity provider detail page. The trust policy for the role might look like this:

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::111122223333:saml-provider/ExampleOrgSSOProvider"
            },
            "Action": "sts:AssumeRoleWithSAML",
            "Condition": {
                "StringEquals": {
                    "saml:edupersonorgdn": "ExampleOrg",
                    "saml:aud": "https://region-code.signin.aws.amazon.com/saml/acs/SAMLSP4SHN3UIS2D558H46"
                }
            }
        }
    ]
}
```

------

**Note**  
SAML IDPs used in a role trust policy must be in the same account that the role is in.

We recommend using regional endpoints for the `saml:aud` attribute at `https://region-code.signin.aws.amazon.com/static/saml-metadata.xml`. For a list of possible *region-code* values, see the **Region** column in [AWS Sign-In endpoints](https://docs.aws.amazon.com/general/latest/gr/signin-service.html).

For the [permission policy](access_policies.md) in the role, you specify permissions as you would for any role, user, or group. For example, if users from your organization are allowed to administer Amazon EC2 instances, you explicitly allow Amazon EC2 actions in the permission policy. You can do this by assigning a [managed policy](access_policies_manage-attach-detach.md), such as the **Amazon EC2 Full Access** managed policy. 

For details about creating a role for a SAML IdP, see [Create a role for SAML 2.0 federation (console)](id_roles_create_for-idp_saml.md). 

## Finish configuration and create SAML assertions


Notify your SAML IdP that AWS is your service provider by installing the `saml-metadata.xml` file found at `https://region-code.signin.aws.amazon.com/static/saml-metadata.xml` or `https://signin.aws.amazon.com/static/saml-metadata.xml`. If SAMl encryption is required, the file is found at `https://region-code.signin.aws.amazon.com/static/saml/SAMLSP4SHN3UIS2D558H46/saml-metadata.xml`.

For a list of possible *region-code* values, see the **Region** column in [AWS Sign-In endpoints](https://docs.aws.amazon.com/general/latest/gr/signin-service.html). 

How you install that file depends on your IdP. Some providers give you the option to type the URL, whereupon the IdP gets and installs the file for you. Others require you to download the file from the URL and then provide it as a local file. Refer to your IdP documentation for details, or see [Integrate third-party SAML solution providers with AWS](id_roles_providers_saml_3rd-party.md) for links to the web documentation for many of the supported SAML providers.

You also configure the information that you want the IdP to pass as SAML attributes to AWS as part of the authentication response. Most of this information appears in AWS as condition context keys that you can evaluate in your policies. These condition keys ensure that only authorized users in the right contexts are granted permissions to access your AWS resources. You can specify time windows that restrict when the console may be used. You can also specify the maximum time (up to 12 hours) that users can access the console before having to refresh their credentials. For details, see [Configure SAML assertions for the authentication response](id_roles_providers_create_saml_assertions.md).

# View a SAML response in your browser
View SAML response in browser

The following procedures describe how to view the SAML response from your service provider from in your browser when troubleshooting a SAML 2.0–related issue. 

For all browsers, go to the page where you can reproduce the issue. Then follow the steps for the appropriate browser:

**Topics**
+ [

## Google Chrome
](#chrome)
+ [

## Mozilla Firefox
](#firefox)
+ [

## Apple Safari
](#safari)
+ [

## What to do with the Base64-encoded SAML response
](#whatnext)

## Google Chrome


**To view a SAML response in Chrome**

These steps were tested using version 106.0.5249.103 (Official Build) (arm64) of Google Chrome. If you use another version, you might need to adapt the steps accordingly.

1. Press **F12** to start the **Developer Tools** console.

1. Select the **Network** tab, and then select **Preserve log** in the upper left of the **Developer Tools** window.

1. Reproduce the issue.

1. (Optional) If the **Method** column is not visible in the **Developer Tools** **Network** log pane, right-click on any column label and choose **Method** to add the column.

1. Look for a **SAML Post** in the **Developer Tools** **Network** log pane. Select that row, and then view the **Payload** tab at the top. Look for the **SAMLResponse** element that contains the encoded request. The associated value is the Base64-encoded response.

## Mozilla Firefox


**To view a SAML response in Firefox**

This procedure was tested on version 105.0.3 (64-bit) of Mozilla Firefox. If you use another version, you might need to adapt the steps accordingly.

1. Press **F12** to start the **Web Developer Tools** console.

1. Select the **Network** tab. 

1. In the upper right of the **Web Developer Tools **window, choose options (the small gear icon). Select **Persist logs**. 

1. Reproduce the issue.

1. (Optional) If the **Method** column is not visible in the **Web Developer Tools** **Network** log pane, right-click on any column label and choose **Method** to add the column.

1. Look for a **POST** **SAML** in the table. Select that row, and then view the **Request** tab and find the **SAMLResponse** element. The associated value is the Base64-encoded response.

## Apple Safari


**To view a SAML response in Safari**

These steps were tested using version 16.0 (17614.1.25.9.10, 17614) of Apple Safari. If you use another version, you might need to adapt the steps accordingly.

1. Enable Web Inspector in Safari. Open the **Preferences** window, select the **Advanced** tab, and then select **Show Develop menu in the menu bar**.

1. Now you can open Web Inspector. Choose **Develop** in the menu bar, then select **Show Web Inspector**.

1. Select the **Network** tab.

1. In the upper left of the **Web Inspector** window, choose options (the small circle icon containing three horizontal lines). Select **Preserve Log**.

1. (Optional) If the **Method** column is not visible in the **Web Inspector** **Network** log pane, right-click on any column label and choose **Method** to add the column.

1. Reproduce the issue.

1. Look for a **POST** **SAML** in the table. Select that row, and then view the Headers tab.

1. Look for the **SAMLResponse** element that contains the encoded request. Scroll down to find `Request Data` with the name `SAMLResponse`. The associated value is the Base64-encoded response.

## What to do with the Base64-encoded SAML response


Once you find the Base64-encoded SAML response element in your browser, copy it and use your favorite Base-64 decoding tool to extract the XML tagged response.

**Security tip**  
Because the SAML response data that you are viewing might contain sensitive security data, we recommend that you do not use an *online* base64 decoder. Instead use a tool installed on your local computer that does not send your SAML data over the network.

**Built-in option for Windows systems (PowerShell):**

```
PS C:\> [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String("base64encodedtext"))
```

**Built-in option for MacOS and Linux systems:**

```
$ echo "base64encodedtext" | base64 --decode
```

**Review the values in the decoded file**  
Review the values in the decoded SAML response file. 
+ Verify that the value for the saml:NameID attribute matches the username for the authenticated user.
+ Review the value for https://aws.amazon.com/SAML/Attributes/Role. The ARN and SAML provider are case sensitive, and the [ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) must match the resource in your account.
+ Review the value for https://aws.amazon.com/SAML/Attributes/RoleSessionName. The value must match the value in the [claim rule](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_relying-party.html).
+ If you configure the attribute value for an email address or an account name, then make sure that the values are correct. The values must correspond to the email address or account name of the authenticated user.

**Check for errors and confirm the configuration**  
Check whether the values contain errors, and confirm that the following configurations are correct.
+ The claim rules meet the required elements and all ARNs are correct. For more information, see [Configure your SAML 2.0 IdP with relying party trust and adding claims](id_roles_providers_create_saml_relying-party.md).
+ You uploaded the latest metadata file from your IdP into AWS in your SAML provider. For more information, see [Enabling SAML 2.0 federated principals to access the AWS Management Console](id_roles_providers_enable-console-saml.md).
+ You correctly configured the IAM role's trust policy. For more information, see [Methods to assume a role](id_roles_manage-assume.md).