Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

SAML 2.0 federation

Amazon 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 Amazon Web Services Management Console or call Amazon 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 Amazon, 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 API access to Amazon

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 Amazon. Instead, the following process is used:

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 Amazon Web Services 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.

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

The roles that you create in IAM define what federated users from your organization are allowed to do in Amazon. 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:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Federated": "arn:aws-cn:iam::account-id: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"]}
    }
  }]
}

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. Amazon 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 Amazon in the unlikely event that the endpoint becomes unavailable. For a list of possible region-code values, see the Region column in Amazon Sign-In endpoints.

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

https://region-code.signin.amazonaws.cn/saml

If SAML encryption is required, the sign-in URL must include the unique identifier Amazon 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.amazonaws.cn/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 Amazon STS federation.

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 Amazon 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.

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.

{
  "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.