AWS Security Token Service
Using Temporary Security Credentials (API Version 2011-06-15)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

About AWS STS SAML 2.0-based Federation

AWS supports identity federation using Security Assertion Markup Language (SAML) 2.0, an open standard used by many identity providers. This feature enables federated single sign-on (SSO), which lets users log into the AWS Management Console or call the AWS APIs without you having to create IAM users for everyone in your organization. Using SAML can simplify the process of configuring federation with AWS, because you can use the identity provider's service instead of writing custom identity proxy code.

AWS STS and IAM support these use cases:

  • Web-based single sign-on (WebSSO) to the AWS Management Console from your organization. Users can sign in to a portal in your organization, select an option to go to AWS, and be redirected to the console without having to provide additional sign-in information. For more information, see Giving AWS Console Access to Federated Users Using SAML.

  • Federated access to allow a user or application in your organization to call AWS APIs. You use a SAML assertion (as part of the authentication response) generated in your organization to get temporary security credentials. This scenario is similar to other federation scenarios supported by AWS STS and IAM, like those described in AWS APIs to Create Temporary Security Credentials and About AWS STS Web Identity Federation. However, SAML 2.0-based identity providers in your organization handle many of the details at run time for performing authentication and authorization checking.

Configuring SAML-Based Federation for API Access

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

  2. The IdP authenticates the user.

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

  4. The client app calls the 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. AWS STS returns temporary security credentials to the client app.

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

Process for Using 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 identity store 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 identity provider (IdP) that supports SAML 2.0, like Microsoft® Active Directory Federation Service (AD FS, part of Windows™ Server), Shibboleth, etc.

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

  2. Using your organization's IdP, you generate an XML metadata document that includes 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 new SAML provider, which is an entity in IAM. As part of this process, you upload the SAML metadata document that was produced by the IdP in your organization (see the previous step).

    For more information, see SAML Providers in the Using IAM guide.

  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 access (permission) policy establishes what users from your organization will be allowed to do in AWS.

    For more information, see Creating a Role for SAML-Based Federation in the Using IAM guide.

  5. In your organization's IdP, you create assertions and map the IAM role to users or groups in your organization who will be allowed to have the permissions specified in the role. 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 previous 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 Configure Assertions for the SAML Authentication Response.

  6. In the application that you're creating, you call the AWS STS AssumeRoleWithSAML API, passing it the ARN of the SAML provider in IAM, the ARN of the role to assume, and a 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.

Creating a Role to Allow AWS Access from Your Organization

The role or roles that you create in IAM define what federated users from your organization will be 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 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 in the Using IAM guide.

For the access (permissions) policy in the role, you specify permissions as you would for any role. For example, if users from your organization will be allowed to administer Amazon EC2 instances, you explicitly allow Amazon EC2 actions in the permissions policy, such as those in the Amazon EC2 Full Access policy template.

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 who have authenticated using an identity provider. 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 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 then.

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. The values returned by the following keys can be used to create unique user identifiers for resources like Amazon S3 folders.

  • saml:namequalifier. This key contains a hash value that represents the combination of the saml:doc and saml:iss values. It is used as a namespace qualifier; the combination of saml:namequalifier and saml:sub uniquely identifies a 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(saml:doc + saml:iss))

  • 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 between 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 Configure Assertions for the SAML Authentication Response.