# 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. 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. 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. 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.
```
_cbb88bf52c2510eabe00c1642d4643f41430fe25e3
```
**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.
```
Marketing
12345
```
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.
```
Project
CostCenter
```
## `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.
```
arn:aws:iam::account-number:role/role-name1,arn:aws:iam::account-number:saml-provider/provider-name
arn:aws:iam::account-number:role/role-name2,arn:aws:iam::account-number:saml-provider/provider-name
arn:aws:iam::account-number:role/role-name3,arn:aws:iam::account-number:saml-provider/provider-name
```
## `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.
```
user-id-name
```
## `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.
```
1800
```
## `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.
```
Diego
```
## 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).