Menu
Amazon Cognito
Developer Guide (Version Last Updated: 08/26/2017)

IAM Roles

In the process of creating an identity pool, you'll be 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 AWS credentials for the user. These temporary credentials are associated with a specific IAM role. The IAM role lets you define a set of permissions to access your AWS 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 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.

To modify IAM roles, thereby allowing or restricting access to other services, log in to the IAM Console. Then click 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 clicking the corresponding Manage Policy link. To learn more about using and defining policies, see Overview of IAM Policies. For Amazon Cognito to work, the IAM policy must at least enable access to the Amazon Cognito store for each identity, as in the following example:

Copy
{ "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}/*"] }] }

The following policy provides access to the entire Amazon Cognito Sync store:

Copy
{ "Version": "2012-10-17", "Statement":[{ "Effect":"Allow", "Action":"cognito-sync:*", "Resource":["arn:aws:cognito-sync:us-east-1:123456789012:identitypool/*"] }] }

Role Trust and Permissions

Amazon Cognito leverages 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.

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:

Copy
"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:

Copy
"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:

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

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

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

Access Policies

The permissions attached to a role are effective across all users that assume that role. If you want to partition your users' access, you can do so via policy variables. Be careful when including your users' identity IDs in your access policies, particularly for unauthenticated identities as these may change if the user chooses to login.

For additional security protection, Amazon Cognito applies a scope-down policy to credentials vended by GetCredentialForIdentity to prevent access to services other than these to your unauthenticated users:

  • CloudWatch

  • Amazon Cognito Identity

  • Amazon Cognito Sync

  • DynamoDB

  • Amazon Kinesis Firehose

  • GameLift

  • AWS IoT

  • Amazon Kinesis Streams

  • AWS KMS

  • AWS Lambda

  • Amazon Lex

  • Amazon Machine Learning

  • Amazon Mobile Analytics

  • Amazon Polly

  • Amazon Rekognition

  • Amazon S3

  • Amazon SimpleDB

  • Amazon SES

  • Amazon SNS

  • Amazon SQS

If you need access to something other than these services for your unauthenticated users, you must use the basic authentication flow. If you are getting NotAuthorizedException and you have enabled access to the service in your unauthenticated role policy, this is likely the reason.

S3 Prefix

You can give a user a specific prefix "folder" in an S3 bucket by mapping the prefix to the ${cognito-identity.amazonaws.com:sub} variable:

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

Fine-Grained Access to Amazon DynamoDB

You can use Amazon Cognito variables to provide fine-grained access control to Amazon DynamoDB resources. Just grant access to items in DynamoDB by identity ID:

Copy
{ "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}"] } } } ] }