Menu
AWS Identity and Access Management
User Guide

Creating a Role for SAML 2.0 Federation (AWS Management Console)

By using identity federation, you can provide access to AWS resources for users who sign in using a third-party identity provider (IdP). To configure identity federation, you configure the provider and then you create an IAM role that determines what permissions a federated user will have. For more information about federation and identity providers, see Identity Providers and Federation.

The role-creation wizard in the IAM console provides two paths. One path is for creating a role for single sign-on (SSO) to the AWS Management Console. The other path is for creating a role that can be assumed programmatically. The following procedures describes both paths. The roles created by both are similar, but the path for SSO creates a role whose trust policy includes a condition that explicitly ensures that the SAML audience (aud attribute) is set to the AWS sign-in endpoint for SAML (https://signin.aws.amazon.com/saml).

Topics

    Before you can create a role for SAML 2.0 federation, you must first complete the following prerequisite steps:

    To prepare to create a role for SAML 2.0 federation

    1. Before you create a role for SAML-based federation, you must create a SAML provider in IAM. For more information, see Creating SAML Identity Providers.

    2. Prepare the policies for the role that the SAML 2.0–authenticated users will assume. As with any role, a role for the SAML federation contains two policies. One is the trust policy that specifies who can assume the role (the trusted entity, or principal). The other policy (the access policy) specifies the actual AWS actions and resources that the federated user is allowed or denied access to (similar to a user or resource policy).

      For SAML 2.0 providers, the policy must include a Statement element similar to the following:

      The trust policy must grant an Allow effect for the sts:AssumeRoleWithSAML action. In this role, you use two values that ensure that the role can be assumed only by your application:

      • For the Principal element, use the string {"Federated":ARNofIdentityProvider}. Replace ARNofIdentityProvider with the ARN of the SAML identity provider that you created in Step 1.

      • For the Condition element, use a StringEquals condition to test that the saml:aud attribute from the SAML response an matches the SAML federation endpoint for AWS.

      Note

      Because the policy for the trusted entity uses policy variables that represent values in the SAML response, you must set the policy's Version element to 2012-10-17 or a later supported version.

      The following example shows a trust policy for a role designed for a SAML federated user:

      Copy to clipboard
      { "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "sts:AssumeRoleWithSAML", "Principal": {"Federated": "arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:saml-provider/PROVIDER-NAME"}, "Condition": {"StringEquals": {"SAML:aud": "https://signin.aws.amazon.com/saml"}} } }
      Replace the principal ARN with the actual ARN for the SAML provider that you created in IAM. It will have your own account ID and the actual provider name.

      After completing the prerequisite steps, you can create the role itself.

    To create a role for SAML-based federation using the IAM console

    1. Make sure you've created a SAML provider in IAM, as described in About SAML 2.0-based Federation.

    2. In the navigation pane of the console, click Roles and then click Create New Role.

    3. For Role Name, type a role name that can help you identify the purpose of this role. Role names must be unique within your AWS account. After you type the name, click Next Step at the bottom of the page.

      Because various entities might reference the role, you cannot edit the name of the role after it has been created.

      Important

      Role names must be unique within an account. They are not distinguished by case, for example, you cannot create roles named both "PRODROLE" and "prodrole".

    4. Click Role for Identity Provider Access.

    5. Select the type of role that you're creating: Grant Web Single Sign-On (SSO) access to SAML identity providers or Grant API access to SAML identity providers.

    6. In the SAML Provider list, select the provider that you're creating the role for.

    7. If you're creating a role for API access, select an attribute from the Attribute list. Then in the Value box, type a value that will be included in the role. This restricts access to the role to users from the identity provider whose SAML authentication response (assertion) includes the attributes you select. You must specify at least one attribute, which ensures that your role is scoped to a subset of users at your organization.

      If you're creating a role for SAML single sign-on, the SAML:aud attribute is automatically added and set to the URL of the AWS SAML endpoint (https://signin.aws.amazon.com/saml).

    8. To add more attribute-related conditions to the trust policy, click Add Conditions, select the additional condition, specify a value, and then click Add Condition.

      The list displays a selected set of the most commonly used SAML attributes. IAM supports additional attributes that you can use to create conditions. (For a list of the supported attributes, see Available Keys for SAML Federation in the topic IAM Policy Elements Reference.) If you need to create a condition for a supported SAML attribute that's not displayed in the list, you can manually add that condition in the next step.

    9. Click Next Step. The wizard displays the trust policy for the role in an editable box. The policy includes the condition or conditions based on what you entered.

    10. When you've reviewed the policy and finished making any changes, click Next Step again.

    11. By default, roles have no permissions. Select the managed policy that assigns the permissions that you want the federated users to have, and then click Next Step.

    12. Review the role and then click Create Role.

    After you create the role, you complete the SAML trust by configuring your identity provider software with information about AWS and the role(s) that you want your federated users to use. This is referred to as configuring relying party trust between your IdP and AWS. For more information, see Configuring your SAML 2.0 IdP with Relying Party Trust and Adding Claims.