Creating a role for a third-party Identity Provider (federation) - Amazon Identity and Access Management
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).

Creating a role for a third-party Identity Provider (federation)

You can use identity providers instead of creating IAM users in your Amazon Web Services account. With an identity provider (IdP), you can manage your user identities outside of Amazon and give these external user identities permissions to access Amazon resources in your account. For more information about federation and identity providers, see Identity providers and federation.

Creating a role for federated users (console)

The procedures for creating a role for federated users depend on your choice of third party providers:

Creating a role for federated access (Amazon CLI)

The steps to create a role for the supported identity providers (OIDC or SAML) from the Amazon CLI are identical. The difference is in the contents of the trust policy that you create in the prerequisite steps. Begin by following the steps in the Prerequisites section for the type of provider you are using:

Creating a role from the Amazon CLI involves multiple steps. When you use the console to create a role, many of the steps are done for you, but with the Amazon CLI you must explicitly perform each step yourself. You must create the role and then assign a permissions policy to the role. Optionally, you can also set the permissions boundary for your role.

To create a role for identity federation (Amazon CLI)
  1. Create a role: aws iam create-role

  2. Attach a permissions policy to the role: aws iam attach-role-policy

    or

    Create an inline permissions policy for the role: aws iam put-role-policy

  3. (Optional) Add custom attributes to the role by attaching tags: aws iam tag-role

    For more information, see Managing tags on IAM roles (Amazon CLI or Amazon API).

  4. (Optional) Set the permissions boundary for the role: aws iam put-role-permissions-boundary

    A permissions boundary controls the maximum permissions that a role can have. Permissions boundaries are an advanced Amazon feature.

The following example shows the first two, and most common, steps for creating an identity provider role in a simple environment. This example allows any user in the 123456789012 account to assume the role and view the example_bucket Amazon S3 bucket. This example also assumes that you are running the Amazon CLI on a computer running Windows, and have already configured the Amazon CLI with your credentials. For more information, see Configuring the Amazon Command Line Interface.

The following example trust policy is designed for a mobile app if the user signs in using Amazon Cognito. In this example, us-east:12345678-ffff-ffff-ffff-123456 represents the identity pool ID assigned by Amazon Cognito.

{ "Version": "2012-10-17", "Statement": { "Sid": "RoleForCognito", "Effect": "Allow", "Principal": {"Federated": "cognito-identity.amazonaws.com"}, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": {"StringEquals": {"cognito-identity.amazonaws.com:aud": "us-east:12345678-ffff-ffff-ffff-123456"}} } }

The following permissions policy allows anyone who assumes the role to perform only the ListBucket action on the example_bucket Amazon S3 bucket.

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws-cn:s3:::example_bucket" } }

To create this Test-Cognito-Role role, you must first save the previous trust policy with the name trustpolicyforcognitofederation.json and the previous permissions policy with the name permspolicyforcognitofederation.json to the policies folder in your local C: drive. You can then use the following commands to create the role and attach the inline policy.

# Create the role and attach the trust policy that enables users in an account to assume the role. $ aws iam create-role --role-name Test-Cognito-Role --assume-role-policy-document file://C:\policies\trustpolicyforcognitofederation.json # Attach the permissions policy to the role to specify what it is allowed to do. aws iam put-role-policy --role-name Test-Cognito-Role --policy-name Perms-Policy-For-CognitoFederation --policy-document file://C:\policies\permspolicyforcognitofederation.json

Creating a role for federated access (Amazon API)

The steps to create a role for the supported identity providers (OIDC or SAML) from the Amazon CLI are identical. The difference is in the contents of the trust policy that you create in the prerequisite steps. Begin by following the steps in the Prerequisites section for the type of provider you are using:

To create a role for identity federation (Amazon API)
  1. Create a role: CreateRole

  2. Attach a permissions policy to the role:AttachRolePolicy

    or

    Create an inline permissions policy for the role: PutRolePolicy

  3. (Optional) Add custom attributes to the user by attaching tags: TagRole

    For more information, see Managing tags on IAM users (Amazon CLI or Amazon API).

  4. (Optional) Set the permissions boundary for the role: PutRolePermissionsBoundary

    A permissions boundary controls the maximum permissions that a role can have. Permissions boundaries are an advanced Amazon feature.