AWS Identity and Access Management
User Guide

Creating a Role for SAML 2.0 Federation (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 has. 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 describe both paths. The roles created by both are similar, but the path for SSO creates a role whose trust policy includes a particular condition. That condition explicitly ensures that the SAML audience (aud attribute) is set to the AWS sign-in endpoint for SAML (


    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 matches the SAML federation endpoint for AWS.


      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:

      { "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": ""}} } }

      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

    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, choose Roles and then choose Create new role.

    3. Choose Role for identity provider access.

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

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

    6. 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 to include 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 (

    7. To add more attribute-related conditions to the trust policy, choose Add Conditions (optional), select the additional condition, specify a value, and then choose 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 a condition for a supported SAML attribute that's not displayed in the list, you can manually add that condition in the next step.

    8. Choose 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.

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

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

    11. For Role name, type a role name that helps you identify the purpose of this role. Role names must be unique within your AWS account. They are not distinguished by case. For example, you cannot create roles named both PRODROLE and prodrole. Because various entities might reference the role, you cannot edit the name of the role after it has been created.

    12. (Optional) For Role description, type a description for the new role.

    13. Review the role and then choose Create role.

    After you create the role, you complete the SAML trust by configuring your identity provider software with information about AWS and the roles 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.