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

IAM roles

While creating an identity pool, you're prompted to update the IAM roles that your users assume. IAM roles work like this: When a user logs in to your app, Amazon Cognito generates temporary Amazon credentials for the user. These temporary credentials are associated with a specific IAM role. With the IAM role, you can define a set of permissions to access your Amazon resources.

You can specify default IAM roles for authenticated and unauthenticated users. In addition, you can define rules to choose the role for each user based on claims in the user's ID token. For more information, see Using role-based access control.

By default, the Amazon Cognito console creates IAM roles that provide access to Amazon Mobile Analytics and to Amazon Cognito Sync. Alternatively, you can choose to use existing IAM roles.

Modify IAM roles to allow or restrict access to other services. To do so, log in to the IAM Console. Then select Roles, and select a role. The policies attached to the selected role are listed in the Permissions tab. You can customize an access policy by selecting the corresponding Manage Policy link. To learn more about using and defining policies, see Overview of IAM Policies.

Set up a trust policy

Amazon Cognito uses IAM roles to generate temporary credentials for your application's users. Access to permissions is controlled by a role's trust relationships. Learn more about Role trust and permissions.

The token presented to Amazon STS is generated by an identity pool, which translates a user pool, social, or OIDC provider token, or a SAML assertion, to its own token. The identity pool token contains an aud claim that is the identity pool ID.

The following example role trust policy allows the federated service principal cognito-identity.amazonaws.com to call the Amazon STS API AssumeRoleWithWebIdentity. The request will only succeed if the identity pool token in the API request has the following claims.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "cognito-identity.cn-north-1.amazonaws.com.cn"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "cognito-identity.amazonaws.com.cn:aud": "us-west-2:abcdefg-1234-5678-910a-0e8443553f95"
                },
                "ForAnyValue:StringLike": {
                    "cognito-identity.amazonaws.com.cn:amr": "authenticated"
                }
            }
        }
    ]
}

Trust policies for IAM roles in Basic (Classic) authentication

You must apply at least one condition that limits trust policies for roles that you use with identity pools. When you create or update role trust policies for identity pools, IAM returns an error if you try to save your changes without at least one condition key that limits source identities. Amazon STS doesn't permit cross-account AssumeRoleWithWebIdentity operations from identity pools to IAM roles that lack a condition of this type.

This topic includes several conditions that limit source identities for identity pools. For a full list, see Available keys for Amazon web identity federation.

In basic, or classic, authentication with an identity pool, you can assume any IAM role with Amazon STS if it has the right trust policy. IAM roles for Amazon Cognito identity pools trust the service principal cognito-identity.amazonaws.com to assume the role. This configuration is not sufficient to secure your IAM roles against unintended access to resources. Roles of this type must apply an additional condition to the role trust policy. You can't create or modify roles for identity pools without at least one of the following conditions.

Enhanced-flow authentication requires that the IAM role be in the same Amazon Web Services account as the identity pool, but this isn't the case in basic authentication.

Additional considerations apply to Amazon Cognito identity pools that assume cross-account IAM roles. The trust policies of those roles must accept the cognito-identity.amazonaws.com service principal and must contain the specific cognito-identity.amazonaws.com:aud condition. To prevent unintended access to your Amazon resources, the aud condition key restricts the role to users from the identity pools in the condition value.

The token that an identity pool issues for an identity contains information about the originating Amazon Web Services account of the identity pool. When you present an identity pool token in an AssumeRoleWithWebIdentity API request, Amazon STS checks to see if the originating identity pool is in the same Amazon Web Services account as the IAM role. If Amazon STS determines that the request is cross-account, it checks to see if the role trust policy has an aud condition. The assume-role call fails if no such conditions are present in the role trust policy. If the request is not cross-account, Amazon STS doesn’t enforce this restriction. As a best practice, always apply a condition of this type to the trust policies of your identity pool roles.

Additional trust policy conditions

Reuse roles across identity pools

To reuse a role across multiple identity pools, because they share a common permission set, you can include multiple identity pools, like this:

"StringEquals": {
    "cognito-identity.amazonaws.com:aud": [
        "us-east-1:12345678-abcd-abcd-abcd-123456790ab",
        "us-east-1:98765432-dcba-dcba-dcba-123456790ab"
    ]
}

Limit access to specific identities

To create a policy limited to a specific set of app users, check the value of cognito-identity.amazonaws.com:sub:

"StringEquals": {
    "cognito-identity.amazonaws.com:aud": "us-east-1:12345678-abcd-abcd-abcd-123456790ab",
    "cognito-identity.amazonaws.com:sub": [
        "us-east-1:12345678-1234-1234-1234-123456790ab",
        "us-east-1:98765432-1234-1234-1243-123456790ab"
    ]
}

Limit access to specific providers

To create a policy limited to users who have logged in with a specific provider (perhaps your own login provider), check the value of cognito-identity.amazonaws.com:amr:

"ForAnyValue:StringLike": {
    "cognito-identity.amazonaws.com:amr": "login.myprovider.myapp"
}

For example, an app that trusts only Facebook would have the following amr clause:

"ForAnyValue:StringLike": {
    "cognito-identity.amazonaws.com:amr": "graph.facebook.com"
}

Access policies

The permissions that you attach to a role apply to all users who assume that role. To partition your users' access, use policy conditions and variables. For more information, see IAM policy elements: Variables and tags. You can use the sub condition to restrict actions to Amazon Cognito identity IDs in your access policies. Use this option with caution, particularly for unauthenticated identities, which lack a consistent user ID. For more information about the IAM policy variables for web federation with Amazon Cognito, see IAM and Amazon STS condition context keys in the Amazon Identity and Access Management User Guide.

For additional security protection, Amazon Cognito applies a scope-down policy to credentials that you assign your unauthenticated users in the enhanced flow, using GetCredentialsForIdentity. The scope-down policy adds an Inline session policy and an Amazon managed session policy to the IAM policies that you apply to your unauthenticated role. Because you must grant access in both the IAM policies for your role and the session policies, the scope-down policy limits users' access to services other than those in the list that follows.

Amazon Cognito also prevents authenticated and unauthenticated users from making API requests to Amazon Cognito identity pools and Amazon Cognito Sync. Other Amazon Web Services services might place restrictions on service access from web identities.

In a successful request with the enhanced flow, Amazon Cognito makes an AssumeRoleWithWebIdentity API request in the background. Among the parameters in this request, Amazon Cognito includes the following.

Services that unauthenticated users can access

When you use the enhanced flow, the scope-down policies that Amazon Cognito applies to your user's session prevent them from using any services other than those listed in the following table. For a subset of services, only specific actions are allowed.

¹ For the Amazon Web Services services in the following table, the inline policy grants a subset of actions. The table displays the available actions in each.

To grant access to Amazon Web Services services beyond this list, activate the basic (classic) authentication flow in your identity pool. If your users see NotAuthorizedException errors from Amazon Web Services services that are allowed by the policies assigned to the IAM role for unauthenticated users, evaluate whether you can remove that service from your use case. If you can't, switch to the basic flow.

The inline session policy for guest users

Amazon Cognito first applies an inline policy in the request for IAM credentials. The inline session policy restricts your user's effective permissions from including access to any Amazon Web Services services outside those in the following list. You must also grant permissions to these Amazon Web Services services in the policies that you apply to the user's IAM role. A user's effective permissions for an assumed-role session are the intersection of the policies assigned to their role, and their session policy. For more information, see Session policies in the Amazon Identity and Access Management User Guide.

Amazon Cognito adds the following inline policy to sessions for your users in Amazon Web Services Regions that are enabled by default. For an overview of the net effect of the inline policy and other session policies, see Services that unauthenticated users can access.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudwatch:*",
                "logs:*",
                "dynamodb:*",
                "kinesis:*",
                "mobileanalytics:*",
                "s3:*",
                "ses:*",
                "sns:*",
                "sqs:*",
                "lambda:*",
                "machinelearning:*",
                "execute-api:*",
                "iot:*",
                "gamelift:*",
                "scs:*",
                "cognito-identity:*",
                "cognito-idp:*",
                "lex:*",
                "polly:*",
                "comprehend:*",
                "translate:*",
                "transcribe:*",
                "rekognition:*",
                "mobiletargeting:*",
                "firehose:*",
                "appsync:*",
                "personalize:*",
                "sagemaker:InvokeEndpoint",
                "cognito-sync:*",
                "sumerian:View*",
                "codewhisperer:*",
                "textract:DetectDocumentText",
                "textract:AnalyzeDocument",
                "sdb:*"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

For all other Regions, the inline scope-down policy includes everything listed in the default Regions except for the following Action statements.

                "cognito-sync:*",
                "sumerian:View*",
                "codewhisperer:*",
                "textract:DetectDocumentText",
                "textract:AnalyzeDocument",
                "sdb:*"

The Amazon managed session policy for guests

Amazon Cognito also applies an Amazon managed policy as a session policy to the enhanced-flow sessions of unauthenticated guests. This policy limits the scope of unauthenticated users' permissions with the policy AmazonCognitoUnAuthedIdentitiesSessionPolicy.

You must also grant this permission in the policies that you attach to your unauthenticated IAM role. A user's effective permissions for an assumed-role session are the intersection of the IAM policies assigned to their role, and their session policies. For more information, see Session policies in the Amazon Identity and Access Management User Guide.

For an overview of the net effect of this Amazon managed policy and other session policies, see Services that unauthenticated users can access.

The AmazonCognitoUnAuthedIdentitiesSessionPolicy managed policy has the following permissions.

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": [
            "rum:PutRumEvents",
            "polly:*",
            "comprehend:*",
            "translate:*",
            "transcribe:*",
            "rekognition:*",
            "mobiletargeting:*",
            "firehose:*",
            "personalize:*",
            "sagemaker:InvokeEndpoint",
            "geo:GetMap*",
            "geo:SearchPlaceIndex*",
            "geo:GetPlace",
            "geo:CalculateRoute*",
            "geo:*Geofence",
            "geo:*Geofences",
            "geo:*DevicePosition*",
            "kms:Encrypt",
            "kms:Decrypt",
            "kms:ReEncryptTo",
            "kms:ReEncryptFrom",
            "kms:GenerateDataKey",
            "kms:GenerateDataKeyPair",
            "kms:GenerateDataKeyPairWithoutPlaintext",
            "kms:GenerateDataKeyWithoutPlaintext"
        ],
        "Resource": "*"
    }]
}

Access policy examples

In this section, you can find example Amazon Cognito access policies that grant your users the minimum permissions necessary to do specific operation. You can further limit the permissions for a given identity ID by using policy variables where possible. For example, using ${cognito-identity.amazonaws.com:sub}. For more information, see Understanding Amazon Cognito Authentication Part 3: Roles and Policies on the Amazon Mobile Blog.

Grant an identity read access to a single object in Amazon S3

The following access policy grants read permissions to an identity to retrieve a single object from a given S3 bucket.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "s3:GetObject"
      ],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::amzn-s3-demo-bucket/assets/my_picture.jpg"]
    }
  ]
}

Grant an identity both read and write access to identity specific paths in Amazon S3

The following access policy grants read and write permissions to access a specific prefix "folder" in an S3 bucket by mapping the prefix to the ${cognito-identity.amazonaws.com:sub} variable.

With this policy, an identity such as us-east-1:12345678-1234-1234-1234-123456790ab inserted via ${cognito-identity.amazonaws.com:sub} can get, put, and list objects into arn:aws:s3:::amzn-s3-demo-bucket/us-east-1:12345678-1234-1234-1234-123456790ab. However, the identity would not be granted access to other objects in arn:aws:s3:::amzn-s3-demo-bucket.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": ["s3:ListBucket"],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::amzn-s3-demo-bucket"],
      "Condition": {"StringLike": {"s3:prefix": ["${cognito-identity.amazonaws.com:sub}/*"]}}
    },
    {
      "Action": [
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::amzn-s3-demo-bucket/${cognito-identity.amazonaws.com:sub}/*"]
    }
  ]
}

A similar access model is achieved with Amazon S3 Access Grants.

Assign identities fine-grained access to Amazon DynamoDB

The following access policy provides fine-grained access control to DynamoDB resources using Amazon Cognito environment variables. These variables grant access to items in DynamoDB by identity ID. For more information, see Using IAM Policy Conditions for Fine-Grained Access Control in the Amazon DynamoDB Developer Guide.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem",
        "dynamodb:BatchGetItem",
        "dynamodb:Query",
        "dynamodb:PutItem",
        "dynamodb:UpdateItem",
        "dynamodb:DeleteItem",
        "dynamodb:BatchWriteItem"
      ],
      "Resource": [
        "arn:aws:dynamodb:us-west-2:123456789012:table/MyTable"
      ],
      "Condition": {
        "ForAllValues:StringEquals": {
          "dynamodb:LeadingKeys":  ["${cognito-identity.amazonaws.com:sub}"]
        }
      }
    }
  ]
}

Grant an identity permission to invoke a Lambda function

The following access policy grants an identity permission to invoke a Lambda function.

{
    "Version": "2012-10-17",
    "Statement": [
         { 
             "Effect": "Allow",
             "Action": "lambda:InvokeFunction",
             "Resource": [
                 "arn:aws:lambda:us-west-2:123456789012:function:MyFunction"
             ]
         }
     ]
 }

Grant an identity permission to publish records to Kinesis Data Streams

The following access policy allows an identity to use the PutRecord operation with any of the Kinesis Data Streams. It can be applied to users that need to add data records to all streams in an account. For more information, see Controlling Access to Amazon Kinesis Data Streams Resources Using IAM in the Amazon Kinesis Data Streams Developer Guide.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "kinesis:PutRecord",
            "Resource": [
                "arn:aws:kinesis:us-east-1:111122223333:stream/stream1"
            ]
        }
    ]
}

Grant an identity access to their data in the Amazon Cognito Sync store

The following access policy grants an identity permissions to access only their own data in the Amazon Cognito Sync store.

{
  "Version": "2012-10-17",
  "Statement":[{
      "Effect":"Allow",
      "Action":"cognito-sync:*",
      "Resource":["arn:aws:cognito-sync:us-east-1:123456789012:identitypool/${cognito-identity.amazonaws.com:aud}/identity/${cognito-identity.amazonaws.com:sub}/*"]
      }]
  }

Role trust and permissions

The way these roles differ is in their trust relationships. The following is an example trust policy for an unauthenticated role:

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

This policy grants federated users from cognito-identity.amazonaws.com (the issuer of the OpenID Connect token) permission 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 operation has the value unauthenticated.

When Amazon Cognito creates a token, it sets the amr of the token as either unauthenticated or authenticated. If amr is authenticated, the token includes any providers used during authentication. This means that you can create a role that trusts only users that logged in via Facebook by changing the amr condition as shown:

"ForAnyValue:StringLike": {
  "cognito-identity.amazonaws.com:amr": "graph.facebook.com"
}

Be careful when changing your trust relationships on your roles, or when trying to use roles across identity pools. If you don't configure your role correctly to trust your identity pool, an exception from STS results, like the following:

AccessDenied -- Not authorized to perform sts:AssumeRoleWithWebIdentity

If you see this message, check that your identity pool and authentication type have an appropriate role.