AWS Identity and Access Management
User Guide

About SAML 2.0-based Federation

AWS supports identity federation with SAML 2.0 (Security Assertion Markup Language 2.0), 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 the AWS APIs 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.

IAM federation supports these use cases:

Using SAML-Based Federation for Access to AWS

Imagine that in your organization, you want to provide a way for users 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 S3 bucket. Users don't have direct access to AWS. Instead, the application communicates with an identity provider (IdP) to authenticate the user. The IdP gets the user information from your organization's identity store (such as an LDAP directory) and then generates a SAML assertion that includes authentication and authorization information about that user. The application then uses that assertion to make a call to the AssumeRoleWithSAML API to get temporary security credentials. The app can then use those credentials to access a folder in the S3 bucket that's specific to the user.

The following diagram illustrates the flow.

Getting temporary security credentials based on a SAML assertion
  1. A user in your organization uses a client app to request authentication from your organization's IdP.

  2. The IdP authenticates the user.

  3. The IdP constructs and sends a SAML assertion to the client app.

  4. The client app calls the AWS STS AssumeRoleWithSAML API, passing the ARN of the SAML provider, the ARN of the role to assume, and the SAML assertion that was provided by the IdP in the previous step.

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

  6. The client app uses the temporary security credentials to call Amazon S3 APIs.

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, like Microsoft Active Directory Federation Service (AD FS, part of Windows Server), Shibboleth, or another compatible SAML 2.0 provider.

  1. You begin by registering AWS with your IdP. In your organization's IdP you register AWS as a service provider (SP) by using the SAML metadata document that you get from the following URL:

  2. Using your organization's IdP, you generate an equivalent metadata XML file that can describe your IdP as an identity provider to 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.

  3. In the IAM console, you create a SAML identity provider entity. As part of this process, you upload the SAML metadata document that was produced by the IdP in your organization in step 2. For more information, see Creating SAML Identity Providers.

  4. 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 Creating a Role for a Third-Party Identity Provider (Federation).

  5. 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 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 Configuring SAML Assertions for the Authentication Response.


    The AWS implementation of SAML 2.0 federation does not support encrypted SAML assertions between the identity provider and AWS. However, the traffic between the identity provider and AWS is transmitted over an encrypted (TLS) channel.

  6. 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, the ARN of the role to assume that you created in step 4, 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 in the AWS Security Token Service API Reference.

  7. 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 role or roles that you create in IAM define what federated users 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 are allowed to access the role, as illustrated by the following sample policy:

  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"AWS": "arn:aws:sts::ACCOUNT-ID-WITHOUT-HYPHENS:saml-provider/ExampleOrgSSOProvider"},
    "Action": "sts:AssumeRoleWithSAML",
    "Condition": {
      "StringEquals": {
        "saml:aud": "",
        "saml:iss": ""
      "ForAllValues:StringLike": {"saml:edupersonaffiliation": ["staff"]}

For more information about the SAML keys that you can check in a policy, see Available Keys for SAML-Based Federation.

For the access 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.

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:


You can create the bucket (myBucket) 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_name". For more information, see the saml:doc key at Available Keys for SAML-Based Federation.

    The combination of NameQualifier and Subject can be used to uniquely identify a federated user. 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 ( "" + "123456789012" + "/MySAMLIdP" ) )

    For more information about the policy keys that are available for SAML-based federation, see Available Keys for SAML-Based Federation.

  • 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 or transient. 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.

The following example shows an access 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 identity user-specific folders.

  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
    "Resource": [
    "Condition": {"StringEquals": {"saml:sub_type": "persistent"}}

For more information about mapping assertions from the IdP to policy keys, see Configuring SAML Assertions for the Authentication Response.