Using role-based access control

Amazon Cognito identity pools assign your authenticated users a set of temporary, limited-privilege credentials to access your AWS resources. The permissions for each user are controlled through IAM roles that you create. You can define rules to choose the role for each user based on claims in the user's ID token. You can define a default role for authenticated users. You can also define a separate IAM role with limited permissions for guest users who are not authenticated.

Creating roles for role mapping

It is important to add the appropriate trust policy for each role so that it can only be assumed by Amazon Cognito for authenticated users in your identity pool. Here is an example of such a trust policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "Federated": "cognito-identity.amazonaws.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "cognito-identity.amazonaws.com:aud": "us-east-1:12345678-corner-cafe-123456790ab"
        },
        "ForAnyValue:StringLike": {
          "cognito-identity.amazonaws.com:amr": "authenticated"
        }
      }
    }
  ]
}

This policy allows federated users from cognito-identity.amazonaws.com (the issuer of the OpenID Connect token) to assume this role. Additionally, the policy restricts the aud of the token, in this case the identity pool ID, to match the identity pool. Finally, the policy specifies that one of the array members of the multi-value amr claim of the token issued by the Amazon Cognito GetOpenIdToken API action has the value authenticated.

Granting pass-role permission

To allow a user to set roles with permissions in excess of the user's existing permissions on an identity pool, grant them iam:PassRole permission to pass the role to the set-identity-pool-roles API. For example, if the user cannot write to Amazon S3, but the IAM role that the user sets on the identity pool grants write permission to Amazon S3, the user can only set this role if iam:PassRole permission is granted for the role. The following example policy shows how to allow iam:PassRole permission.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1",
            "Effect": "Allow",
            "Action": [
                "iam:PassRole"
            ],
            "Resource": [
                "arn:aws:iam::123456789012:role/myS3WriteAccessRole"
            ]
        }
    ]
}

In this policy example, the iam:PassRole permission is granted for the myS3WriteAccessRole role. The role is specified using the role's Amazon Resource Name (ARN). You must also attach this policy to your user. For more information, see Working with Managed Policies.

Using tokens to assign roles to users

For users who log in through Amazon Cognito user pools, roles can be passed in the ID token that was assigned by the user pool. The roles appear in the following claims in the ID token:

The claims are set as follows:

When using tokens to assign roles, if there are multiple roles that can be assigned to the user, Amazon Cognito identity pools (federated identities) chooses the role as follows:

Using rule-based mapping to assign roles to users

Rules allow you to map claims from an identity provider token to IAM roles.

Each rule specifies a token claim (such as a user attribute in the ID token from an Amazon Cognito user pool), match type, a value, and an IAM role. The match type can be Equals, NotEqual, StartsWith, or Contains. If a user has a matching value for the claim, the user can assume that role when the user gets credentials. For example, you can create a rule that assigns a specific IAM role for users with a custom:dept custom attribute value of Sales.

Rules are evaluated in order, and the IAM role for the first matching rule is used, unless CustomRoleArn is specified to override the order. For more information about user attributes in Amazon Cognito user pools, see Working with user attributes.

You can set multiple rules for an authentication provider in the identity pool (federated identities) console. Rules are applied in order. You can drag the rules to change their order. The first matching rule takes precedence. If the match type is NotEqual and the claim doesn't exist, the rule is not evaluated. If no rules match, the Role resolution setting is applied to either Use default authenticated role or Deny request.

In the API and CLI, you can specify the role to be assigned when no rules match in the AmbiguousRoleResolution field of the RoleMapping type, which is specified in the RoleMappings parameter of the SetIdentityPoolRoles API.

To add rule-based mapping to an identity provider in the Amazon Cognito console, add or update an IdP and select Choose role with rules under Role selection. From there, you can add rules that map provider claims to IAM roles.

You can set up rule-based mapping for identity providers in the AWS CLI or API with the RulesConfiguration field of the RoleMapping type. You can specify this field in the RoleMappings parameter of the SetIdentityPoolRoles API.

For example, the following AWS CLI command adds a rule that assigns the role arn:aws:iam::123456789012:role/Sacramento_team_S3_admin to users in your Sacramento location who were authenticated by OIDC IdP arn:aws:iam::123456789012:oidc-provider/myOIDCIdP:

aws cognito-identity set-identity-pool-roles --region us-east-1 --cli-input-json file://role-mapping.json

Contents of role-mapping.json:

{
    "IdentityPoolId": "us-east-1:12345678-corner-cafe-123456790ab",
    "Roles": {
        "authenticated": "arn:aws:iam::123456789012:role/myS3WriteAccessRole",
        "unauthenticated": "arn:aws:iam::123456789012:role/myS3ReadAccessRole"
    },
    "RoleMappings": {
        "arn:aws:iam::123456789012:oidc-provider/myOIDCIdP": {
            "Type": "Rules",
            "AmbiguousRoleResolution": "AuthenticatedRole",
            "RulesConfiguration": {
                "Rules": [
                    {
                        "Claim": "locale",
                        "MatchType": "Equals",
                        "Value": "Sacramento",
                        "RoleARN": "arn:aws:iam::123456789012:role/Sacramento_team_S3_admin"
                    }
                ]
            }
        }
    }
}

For each user pool or other authentication provider that you configure for an identity pool, you can create up to 25 rules. This limit is not adjustable. For more information, see Quotas in Amazon Cognito.

Token claims to use in rule-based mapping

Amazon Cognito

An Amazon Cognito ID token is represented as a JSON Web Token (JWT). The token contains claims about the identity of the authenticated user, such as name, family_name, and phone_number. For more information about standard claims, see the OpenID Connect specification. Apart from standard claims, the following are the additional claims specific to Amazon Cognito:

Amazon

The following claims, along with possible values for those claims, can be used with Login with Amazon:

Facebook

The following claims, along with possible values for those claims, can be used with Facebook:

Google

A Google token contains standard claims from the OpenID Connect specification. All of the claims in the OpenID token are available for rule-based mapping. See Google's OpenID Connect site to learn about the claims available from the Google token.

Apple

An Apple token contains standard claims from the OpenID Connect specification. See Authenticating Users with Sign in with Apple in Apple’s documentation to learn more about the claim available from the Apple token. Apple's token doesn’t always contain email.

OpenID

All of the claims in the Open Id token are available for rule-based mapping. For more information about standard claims, see the OpenID Connect specification. Refer to your OpenID provider documentation to learn about any additional claims that are available.

SAML

Claims are parsed from the received SAML assertion. All the claims that are available in the SAML assertion can be used in rule-based mapping.

Best practices for role-based access control