What a Cognito Identity Pool Hands Out - Which Role It Picks, Who Calls STS, and What a Guest Gets

First Published:
Last Updated:

An Amazon Cognito identity pool provides temporary AWS credentials to users of an application. These credentials are associated with a specific IAM role. The role selected is determined by the identity pool's configuration, the user's token, and the flow chosen by the application.

This article outlines what a Cognito identity pool hands out, as of November 10, 2026. The breakdown focuses on five key aspects: which role is selected, who selects the role and who calls AWS STS in each of the two flows, enhanced and basic, what is required in the role's trust policy, how the guest credentials are restricted, and how long each credential and token lasts.

This article distinguishes between what the official documentation states, what is not explicitly mentioned in the documentation, and any discrepancies between different documentation sources. This article does not reflect testing in a live environment. The process of creating an identity pool and using the SDK is beyond the scope of this article and is left to the official documentation.

Related articles on this site:

Table of Contents

  1. 1. Scope and Assumptions
  2. 2. How to Read the Tables
  3. 3. What an Identity Pool Hands Out
  4. 4. The Two Flows
  5. 5. How the Role Is Chosen
  6. 6. What the Role's Trust Policy Must Say
  7. 7. What a Guest Gets
  8. 8. Attributes for Access Control
  9. 9. How Long Each Credential and Token Lasts
  10. 10. Where the Sources Disagree and What They Do Not Say
  11. 11. Failure Modes
  12. 12. Frequently Asked Questions About Cognito Identity Pools
  13. 13. Summary
  14. 14. References

1. Scope and Assumptions

This chapter first defines the intended audience, the scope of this article, the relevant source materials, and the terminology used. The following ten points are the key conclusions.

  • An identity pool provides three items: an identity ID, an OpenID token issued by the identity pool, and temporary AWS credentials (Chapter 3).
  • In the enhanced flow, the identity pool configuration selects a role, and Amazon Cognito calls AWS STS on behalf of the application. In the basic flow, the application selects a role and directly calls AWS STS (Chapter 4).
  • For identity pools configured with role mapping, the basic flow cannot be used. As a best practice, the documentation says not to activate the basic flow by default in a new identity pool. However, the documentation does not explicitly state that the basic flow is disabled by default (Section 4.5).
  • When selecting a role based on token claims, the documentation outlines a three-step process: CustomRoleArn, the cognito:preferred_role claim, and the AmbiguousRoleResolution setting. The system evaluates the rules from top to bottom, using the role associated with the first matching rule. There can be up to 25 rules per authentication provider, and this limit cannot be changed (Chapter 5).
  • Users of developer identities receive credentials for the identity pool's default authenticated role (Section 5.6).
  • The role's trust policy must include an aud condition that limits the identity pool. This condition is required for both the enhanced and basic flows; IAM rejects trust policies without this condition at the time of saving (Section 6.1).
  • Amazon Cognito applies a scope-down policy only to the credentials provided to guest users in the enhanced flow. The documentation does not mention any scope-down applied to credentials for authenticated users (Chapter 7).
  • Both authenticated and guest users are unable to call the identity pool and Amazon Cognito Sync APIs (Section 7.4).
  • According to the documentation, credentials from the enhanced flow are valid for one hour. The DurationSeconds parameter in AssumeRoleWithWebIdentity determines the duration of credentials from the basic flow. Tokens obtained via GetOpenIdToken are valid for 10 minutes (Chapter 9).
  • There are at least six places where the sources disagree. This article does not decide that either side is wrong (Section 10.1).

1.1 Intended Audience

This article is intended for the following audience:

  • Individuals responsible for designing roles within an identity pool, particularly those designing systems that directly call AWS services from browsers or mobile applications.
  • Individuals responsible for determining whether to grant guest access and, if so, to what extent.
  • Individuals responsible for reviewing existing identity pool configurations and deciding whether to retain the basic flow.
  • IAM specialists responsible for writing role trust policies.

This article assumes that readers are considering the following points, and checks each point against the statements in the sources:

  • For identity pool credentials, all users are subject to scope-down restrictions.
  • The aud condition in the trust policy is only required when using the basic flow.
  • The basic flow is disabled by default.
  • If a CustomRoleArn is provided, the application can select any role.
  • In the trust policy, the cognito-identity.amazonaws.com:sub value corresponds to the sub value in the user's IdP token.
  • The validity period for enhanced identity pool credentials is determined by the maximum session duration of the role.

1.2 What This Article Covers and What It Does Not

This article covers what an identity pool hands out, the two flows, every step of role selection, the conditions of role trust policies, guest scope-down and the restrictions that apply to all users, validity periods, key points regarding attribute-based access control, and discrepancies between sources.

This article does not cover:


This article focuses on describing the process of selecting roles and scoping down guest access, limiting the discussion to configuration boundaries and behavior. It does not describe procedures for expanding permissions or removing trust policy conditions.

1.3 Date of Review and Materials Reviewed

This article reviewed the following materials on November 10, 2026 (Japan Standard Time). Throughout the text, the English name at the start of each line is used.

  • authentication flow page: The Identity pools authentication flow page in the Amazon Cognito Developer Guide.
  • role-based access control page: The Using role-based access control page in the Amazon Cognito Developer Guide.
  • IAM roles page: The IAM roles page in the Amazon Cognito Developer Guide.
  • developer-authenticated identities page: The Developer-authenticated identities page in the Amazon Cognito Developer Guide.
  • attributes for access control page: The Using attributes for access control page in the Amazon Cognito Developer Guide.
  • console overview page: The Identity pools console overview page in the Amazon Cognito Developer Guide.
  • Cognito Identity API Reference: Pages of the Amazon Cognito Federated Identities API Reference. This article read the following pages: GetId, GetCredentialsForIdentity, GetOpenIdToken, GetOpenIdTokenForDeveloperIdentity, SetIdentityPoolRoles, CreateIdentityPool, RoleMapping, MappingRule, Credentials.
  • STS API Reference: The AssumeRoleWithWebIdentity page of the AWS STS API Reference.
  • IAM condition keys page: The IAM and AWS STS condition context keys page in the IAM User Guide.
  • IAM federation page: The Common scenarios page in the IAM User Guide.
  • Cognito Sync page: The Amazon Cognito Sync availability change page in the Amazon Cognito Developer Guide.
  • What's New posts: Two announcements, listed in Section 10.3.

This article read every source in its original text, retrieved with curl.

1.4 Terms, and Different Things with the Same Spelling

This article uses the following terms consistently:

  • Identity pool: An Amazon Cognito identity pool. Documentation also refers to these as federated identities. This article does not cover user pools.
  • Identity ID: An identifier created by the identity pool for each user. It is in the format REGION:GUID.
  • Temporary credentials: Credentials issued by AWS STS and used for SigV4 signing. This consists of an access key ID, a secret access key, and a session token.
  • Enhanced flow: What the documentation refers to as the enhanced (simplified) authentication flow.
  • Basic flow: What the documentation refers to as the basic (classic) authentication flow.
  • Guest: What the documentation refers to as an unauthenticated user. This article uses "guest" and "unauthenticated" interchangeably.
  • Role mapping: The method of selecting roles, configured per authentication provider in the RoleMappings parameter of SetIdentityPoolRoles.

This article contains terms that share the same spelling but have different meanings:

  • sub: The "sub" value in the token issued by the identity pool, and cognito-identity.amazonaws.com:sub in the trust policy, both refer to the identity ID. This is a different value from the "sub" value in the user's IdP token (see Section 6.2).
  • Token: This article distinguishes between tokens issued by user pools or external IdPs, and OpenID tokens issued by the identity pool.
  • Basic: The "basic" term in the basic flow is unrelated to HTTP Basic authentication. It is also distinct from the "basic permissions" used in the console overview page to describe new roles.
  • Identity: The "identity" term in the context of an identity pool is distinct from an IAM identity, which refers to IAM users or roles.
  • Short-term key: AWS documentation refers to "short-term API keys," which are API keys sent as bearer tokens. These are separate from the temporary credentials discussed in this article.

2. How to Read the Tables

This chapter defines the terminology used in the tables in this article, specifically the terms for the state of the sources, and how this article writes verification dates and dates.

2.1 Terms for the State of the Sources

This article uses six terms to describe the state of the documentation. These terms, including their English spellings, will also be used in the tables.

  • Stated: The documentation contains a statement regarding the matter.
  • Stated as not supported: The documentation explicitly states that the matter is not supported or cannot be used.
  • Documentation does not list: While a list or table exists, the specific item is not included. This does not necessarily indicate that the matter is unsupported or unavailable.
  • No statement found: Despite searching using different search terms and examining different categories of documentation (as described in Section 1.3), no relevant statement could be found. This does not necessarily indicate that the matter is absent or does not occur.
  • Sources disagree: The documentation from two different sources provides conflicting statements regarding the same matter. This includes cases where the statements directly contradict each other, as well as cases where the scope, strength, or subject matter differs, and the text alone does not settle which one applies. This article presents both statements and their sources without designating either as incorrect.
  • Inference: This represents an inference made by this article, and is not a statement found in any of the documentation. This article says in the same sentence that it is an inference.

This article distinguishes between "Stated as not supported" and "No statement found." The former refers to a statement in the documentation, while the latter indicates that this article was unable to find a relevant statement.

2.2 How This Article Writes Verification Dates and Dates

The "Verification Date" column in the table in this article refers to the date on which the values in that row were verified against the relevant documentation. Dates are recorded in Japan Standard Time. The values in the table may change after the verification date. In particular, the list of services available to guests and the contents of the scope-down policy change.

The dates for "What's New" posts correspond to the publication dates listed on each individual post page.

3. What an Identity Pool Hands Out

This chapter outlines the three things an identity pool provides to users, and how the APIs that request them are authorized.

3.1 Identity ID

The identity pool creates an identity ID for each user. The GetId API returns the identity ID. The authentication flow page states that in identity pools that allow guest access, users can request a new identity ID from GetId at any time. Applications store the identity ID and use it for subsequent requests.

For authenticated users, GetId validates the IdP token and either returns an identity ID associated with that login or creates a new one. It is also possible to associate multiple logins with a single identity, and sometimes two identities may be merged into one. The authentication flow page notes that the identity ID returned by GetOpenIdToken may differ from the one provided by the application.

3.2 OpenID Token

The identity pool issues its own OpenID Connect token. The GetOpenIdToken and GetOpenIdTokenForDeveloperIdentity APIs return this token. The IAM roles page describes how the identity pool replaces the IdP's token with its own token and passes it to AWS STS, noting that the token's aud claim identifies the identity pool.

The identity pool token contains an aud claim that is the identity pool ID.

The amr claim of this token indicates whether the user is authenticated or unauthenticated. When authenticated, the claim also includes the name of the provider used for authentication (see Section 6.2).

The authentication flow page states that before passing the token to AWS STS using the basic flow, the application should validate the token. The key used for signing the token is documented in the identity pool's jwks_uri document. The documentation further specifies that the cache-control header in that document currently has a max-age of 30 days.

3.3 Temporary Credentials

The final output of the identity pool is temporary AWS credentials. The Credentials data type in the Cognito Identity API Reference consists of the following four items:

ItemDescriptionVerification Date
AccessKeyIdThe Access Key portion of the credentials.2026-11-10
SecretKeyThe Secret Access Key portion of the credentials2026-11-10
SessionTokenThe Session Token portion of the credentials2026-11-10
ExpirationThe date at which these credentials will expire.2026-11-10

These credentials belong to a session for an IAM role. Applications use these credentials to sign requests to AWS APIs using SigV4. Chapter 5 discusses which role is being used.

3.4 The API That Hands Out Credentials Is Not Authorized by IAM

Some of the APIs in the identity pool are authorized via IAM, while others are not.

  • GetId and GetOpenIdToken are considered public APIs according to the Cognito Identity API Reference, and do not require credentials.
  • For GetCredentialsForIdentity, Amazon Cognito does not evaluate IAM policies. The documentation states:

Amazon Cognito doesn't evaluate AWS Identity and Access Management (IAM) policies in requests for this API operation.

  • SetIdentityPoolRoles and GetOpenIdTokenForDeveloperIdentity are authorized via IAM using credentials.

Therefore, whether a user can receive credentials is determined not by the caller's IAM policies, but by the identity pool configuration, the role's trust policy, and the IdP token validation process (Inference).

4. The Two Flows

This chapter outlines two flows – enhanced and basic – detailing the order of calls and specifying who selects roles and who invokes AWS STS. The developer identity flow also operates within one of these two flows.

4.1 The Enhanced Flow

In the enhanced flow, the application calls two APIs. It receives an identity ID using GetId, and then passes the same IdP token and identity ID to GetCredentialsForIdentity to receive temporary credentials.

The authentication flow page states that in the enhanced flow, the identity pool configuration selects the role.

Enhanced authentication manages the logic of IAM role selection and credentials retrieval in your identity pool configuration.

The same page describes that GetCredentialsForIdentity functions identically to calling AssumeRoleWithWebIdentity after GetOpenIdToken. Amazon Cognito invokes AWS STS.

This operation is functionally equivalent to calling GetOpenIdToken, then AssumeRoleWithWebIdentity. For Amazon Cognito to call AssumeRoleWithWebIdentity on your behalf, your identity pool must have IAM roles associated with it.

The IAM roles page also states that when the enhanced flow is successful, Amazon Cognito internally calls AssumeRoleWithWebIdentity. The same page, in the explanation of guest scope-down, indicates that the request includes the user's identity ID, the ARN of the role the user assumes, and two session policies (see Section 7.2).

4.2 The Basic Flow

In the basic flow, the application calls three APIs. It receives an identity ID using GetId, obtains an OpenID token from the identity pool using GetOpenIdToken, and then passes that token to AWS STS's AssumeRoleWithWebIdentity to receive temporary credentials.

The authentication flow page states that in the basic flow, the application selects a role.

When you implement the basic authentication flow, your application selects the IAM role that you want users to assume.

The same page describes which roles the token received in the basic flow can be exchanged for.

Users can exchange the tokens from basic authentication for any IAM roles that trust your identity pool and amr, or authenticated/unauthenticated state.

Therefore, in the basic flow, the identity pool configuration does not select a specific role. Any role that trusts the identity pool and the amr can be a potential option. The documentation highlights a benefit of the basic flow as the ability to specify the length of the role session.

4.3 The Developer Identity Flow

Developer identity is a method for verifying users using a developer's own authentication system, separate from Amazon Cognito. The backend calls GetOpenIdTokenForDeveloperIdentity with IAM credentials, receiving an identity ID and an OpenID token. Following this, the process proceeds along one of two paths:

  • Enhanced form: The received token is placed in the Logins parameter and GetCredentialsForIdentity is called.
  • Basic form: The received token is passed to AssumeRoleWithWebIdentity in the WebIdentityToken parameter.

The authentication flow page describes developer identity as a shortcut that bypasses the need for IdP authentication verification.

Amazon Cognito trusts the AWS credentials that authorize a GetOpenIdTokenForDeveloperIdentity request without additional validation of the request contents.

The same page emphasizes the importance of protecting the secret used to authorize developer identities from users.

In the enhanced form, the key within Logins must match the iss claim in the token. The developer-authenticated identities page states:

The logins map key must exactly match the iss (issuer) claim in the token.

When the values do not match, GetCredentialsForIdentity returns a NotAuthorizedException. The Region of the identity pool determines the issuer value. The documentation divides Regions into three categories: Regions that use the global issuer cognito-identity.amazonaws.com, Regions in China that use a different format, and the remaining commercial Regions that use a format including the Region name, such as cognito-identity.<region>.amazonaws.com. A table on the developer-authenticated identities page lists which format is used in each Region.

4.4 Comparing the Two Flows

The following table compares the two flows by who selects the role, who calls AWS STS, and other differences.

Two Flows Side by Side
Two Flows Side by Side
ItemEnhanced FlowBasic FlowVerification Date
Call SequenceGetId → GetCredentialsForIdentityGetId → GetOpenIdToken → AssumeRoleWithWebIdentity2026-11-10
Role SelectorIdentity pool configurationApplication2026-11-10
Calls AWS STSAmazon Cognito (called on behalf of the application)Application2026-11-10
Role MappingSupportedNot supported in identity pools with role mapping configured2026-11-10
Account with RoleSame account as the identity poolCan also request a role in a different account2026-11-10
Trust Policy aud ConditionRequiredRequired2026-11-10
Trust Policy aws:SourceIpNot usedCan be used2026-11-10
Guest Scope-DownApplied by Amazon CognitoThe application can apply the same restrictions to its own requests2026-11-10
Credential Validity Period1 hourDetermined by DurationSeconds2026-11-10

Reading the Table:

  • The "Account with Role" row refers to text found on the IAM roles page. Even with the basic flow, if a role from a different account is requested, it will fail if the role's trust policy does not include an aud condition (see Section 6.3).
  • The "Guest Scope-Down" row, in the "Basic Flow" column, refers to a note found on the IAM roles page (see Section 7.1).
  • The "Credential Validity Period" row is detailed further in Chapter 9.

4.5 What Changes When You Activate the Basic Flow

The basic flow is enabled in the identity pool configuration. The Cognito Identity API Reference documentation for CreateIdentityPool includes AllowClassicFlow, which is a Boolean type and not a required parameter. The documentation does not specify a default value.

Enables or disables the Basic (Classic) authentication flow.

The authentication flow page states that when you call GetOpenIdToken on an identity pool with role mapping configured, the following error is returned.

Basic (classic) flow is not supported with RoleMappings, please use enhanced flow.

The same page describes the enhanced flow, stating that it is the most secure choice with the lowest development effort, and includes the following best practice.

When you create a new identity pool, don't activate basic (classic) authentication by default, as a best practice.

This sentence recommends not activating the basic flow in a new identity pool. It does not state that the basic flow is disabled by default. This article has not found a statement of the default value of AllowClassicFlow (No statement found).

The console overview page describes the changes that occur when you enable the basic flow:

With the basic flow active, you can bypass the role selections you made for your IdPs and call AssumeRoleWithWebIdentity directly.

If you use the basic flow, the authentication flow page advises that you first evaluate the trust relationships of your roles for web identities, build the role selection logic into the client, and secure the client against modification by users. In essence, enabling the basic flow shifts control of role mapping and guest scope-down, which the identity pool otherwise controls, to the application and its trust policies (Inference).

5. How the Role Is Chosen

This chapter outlines how the identity pool determines which role is selected, in the enhanced flow. In the basic flow, the application chooses the role (see Section 4.2).

How the Role Is Chosen
How the Role Is Chosen

5.1 Default Roles

The identity pool allows you to configure default roles for authenticated and guest users. Pass the ARNs of the roles using the Roles parameter in SetIdentityPoolRoles, using the keys authenticated and unauthenticated. If you do not configure role mappings for a specific authentication provider, the default authenticated role will be used for users of that provider.

The console overview page lists three options for configuring roles for each authentication provider: the default role, role selection based on rules, and role selection using preferred_role in user pool tokens. In the API, the Type field in RoleMappings will be either Token or Rules.

5.2 Choosing by Token Claims

Users in the user pool will receive roles configured in the user pool's groups in the ID token claims. The role-based access control page describes the two claims as follows:

  • cognito:preferred_role: The ARN of the role. This claim contains the role from the group with the lowest Precedence value. If only one role is permitted, that role will be included in this claim. If multiple roles are available and a single role with the lowest Precedence cannot be determined, this claim will not be present.
  • cognito:roles: A string containing the ARNs of the permitted roles, separated by commas. This claim is included if there is at least one role.

5.3 Choosing by Rules

Rules are used to map tokens' claims and roles. Each rule consists of four elements: a claim, a match type, a value, and a role. The available match types are Equals, NotEqual, StartsWith, and Contains.

The role-based access control page specifies the order in which rules are evaluated as follows:

Rules are evaluated in order, and the IAM role for the first matching rule is used, unless CustomRoleArn is specified to override the order.

The same page also states an exception for rules that use the NotEqual match type.

If the match type is NotEqual and the claim doesn't exist, the rule is not evaluated.

There is a limit to the number of rules that can be defined.

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.

When no rule matches, the system determines whether to use a default authenticated role or reject the request, based on the AmbiguousRoleResolution setting (see Section 5.5).

5.4 CustomRoleArn and the Three-Step Order

GetCredentialsForIdentity accepts a CustomRoleArn. The Cognito Identity API Reference describes this as an optional argument that allows you to specify the ARN of the role to assume for the user when the IdP token or SAML assertion contains multiple role claims.

When selecting a role based on the token's claims, the role-based access control page states that for users who may have multiple roles, the system selects the role in the following order.

Use the GetCredentialsForIdentity CustomRoleArn parameter if it is set and it matches a role in the cognito:roles claim. If this parameter doesn't match a role in cognito:roles, deny access.
If the cognito:preferred_role claim is set, use it.
If the cognito:preferred_role claim is not set, the cognito:roles claim is set, and CustomRoleArn is not specified in the call to GetCredentialsForIdentity, then the Role resolution setting in the console or the AmbiguousRoleResolution field (in the RoleMappings parameter of the SetIdentityPoolRoles API) is used to determine the role to be assigned.

These three steps mean the following:

  • CustomRoleArn is used to select a role from those listed in cognito:roles. If you provide an ARN that is not listed, the request will be rejected.
  • If no CustomRoleArn is provided, the cognito:preferred_role is used.
  • If neither is provided, but cognito:roles is present, the AmbiguousRoleResolution setting is used.

When roles are chosen by rules, too, CustomRoleArn overrides the order of the rules, as the sentence in Section 5.3 says.

5.5 AmbiguousRoleResolution

AmbiguousRoleResolution defines how to handle situations where a role cannot be determined. It has two possible values: AuthenticatedRole and Deny. AuthenticatedRole uses the default authenticated role, while Deny rejects the request. The Cognito Identity API Reference describes scenarios where a role cannot be determined in the RoleMapping as follows:

  • When no rule matches (under the Rules type).
  • With the Token type, when there is no cognito:preferred_role claim and multiple roles are present in cognito:roles.

The same page indicates whether AmbiguousRoleResolution is required, presenting this information in both the main text and a table:

If you specify Token or Rules as the Type, AmbiguousRoleResolution is required.

Valid Values: AuthenticatedRole | Deny
Required: No

The Type field can be either Token or Rules, and the Type itself is required. This article interprets the text as requiring AmbiguousRoleResolution when configuring RoleMapping, considering it a conditionally required field. It interprets the table entry Required: No as the display for an item without that condition (Inference). This article does not decide that either statement is wrong (see Section 10.1).

5.6 Developer Identities Get the Default Authenticated Role

Role mappings do not apply to users with a developer identity. The developer-authenticated identities page states:

GetCredentialsForIdentity with developer-authenticated identities returns temporary credentials for the default authenticated role of the identity pool.

The Cognito Identity API Reference's GetCredentialsForIdentity page also states that, for developer identities, it issues credentials for the default authenticated role, while for users from external identity providers (IdPs), it issues credentials for a role selected from either the token's role claim, the default role, or a configured rule. The developer-authenticated identities page states that, in the basic form, the caller requests an IAM role ARN with appropriate trust relationships using AssumeRoleWithWebIdentity.

5.7 Claims the End User Can Modify

Role selection relies on claims. The role-based access control page outlines the following best practices:

If the claim that you are mapping to a role can be modified by the end user, any end user can assume your role and set the policy accordingly. Only map claims that cannot be directly set by the end user to roles with elevated permissions.

Within user pools, you can configure read and write permissions for app clients for each user attribute. The same considerations apply to access control based on attributes, as described in Chapter 8.

6. What the Role's Trust Policy Must Say

This chapter outlines the conditions required for the trust policies associated with roles assumed by users of an identity pool.

6.1 aud Is Required When the Policy Is Saved

When the Principal in the trust policy is cognito-identity.amazonaws.com, it is not possible to create a trust policy that lets any identity pool assume the role. The IAM roles page states:

Other condition keys are available, but aud is required. If you attempt to save a role trust policy without a condition of this type, IAM returns an error.

This requirement applies to both enhanced and basic flows. The IAM roles page also states that, for the basic flow, trust policies without the aud condition cannot be saved.

This restriction was not initially enforced when the service was first launched. The documentation indicates that trust policies created before the enforcement will be handled as follows:

After the enforcement of this requirement, AWS STS permits web identities to assume roles that are not secured with conditions, but those roles can't be modified without introducing those conditions.

In other words, the aud requirement is enforced when a trust policy is saved. It is possible for accounts to still have roles with older trust policies that do not have this condition.

6.2 amr and sub

The IAM roles page lists three condition keys for the identity pool.

Condition KeyDescriptionVerification Date
cognito-identity.amazonaws.com:audRestricts the role to one or more identity pools. The aud claim in the identity pool token indicates the originating identity pool.2026-11-10
cognito-identity.amazonaws.com:amrRestricts the role to either authenticated or guest users. The amr claim in the token indicates the authentication status.2026-11-10
cognito-identity.amazonaws.com:subRestricts the role to one or more users identified by a UUID. This UUID is the identity ID within the identity pool.2026-11-10

The amr claim can have multiple values. For authenticated users, the token includes the value authenticated along with the name of the provider used for authentication. Therefore, the documentation provides an example using ForAnyValue:StringLike to examine the amr claim, allowing you to create roles that only trust users authenticated through a specific provider. The documentation also recommends allowing only authenticated users through the amr condition.

The sub claim is not the IdP's sub. The IAM roles page states:

This UUID is the user's identity ID in the identity pool. This value isn't the sub value from the user's original identity provider.

In access policies, you can use the policy variable ${cognito-identity.amazonaws.com:sub} to separate S3 prefixes and DynamoDB items by identity ID. The IAM roles page notes that guest identities lack a consistent user ID and advises caution when using this approach.

6.3 The Basic Flow Across Accounts

The IAM roles page distinguishes the account of the role between the two flows as follows.

Enhanced-flow authentication requires that the IAM role be in the same AWS account as the identity pool.

In the basic flow, the application composes the AssumeRoleWithWebIdentity request, so it can also request a role in a different account. AWS STS compares the originating account shown in the identity pool token with the account of the role. If the request is cross-account, AWS STS verifies whether the role's trust policy includes an aud condition. If this condition is missing, the request will fail. For requests originating from the same account, AWS STS does not perform this check. The documentation recommends including the aud condition in both scenarios as a best practice.

6.4 The Enhanced Flow Does Not Use aws:SourceIp

The IAM roles page says not to use the aws:SourceIp condition key in the trust policies of roles assumed in the enhanced flow. The page gives the reason as follows:

Because the enhanced flow generates the AssumeRoleWithWebIdentity request on behalf of your application, the source IP of the request will not be the IP of your application client, and the condition will never be satisfied.

Network condition keys are only valid for IAM roles assumed through the basic flow.

7. What a Guest Gets

This chapter describes what guest credentials are narrowed to.

7.1 Scope-Down Applies Only to Guests in the Enhanced Flow

The IAM roles page states the target of the scope-down policy as follows:

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 target is the credentials passed to guests through GetCredentialsForIdentity in the enhanced flow. The documentation does not describe this scope-down for the credentials of authenticated users.

Regarding the basic flow, the same page includes the following note:

In the basic (classic) flow, you make your own AssumeRoleWithWebIdentity API request, and can apply these restrictions to the request.

In the basic flow, Amazon Cognito does not create requests to AWS STS. The documentation states that the application can apply the same restrictions to its own requests. The same page continues with the following best practice:

As a best security practice, don't assign any permissions above this scope-down policy to unauthenticated users.

7.2 Two Session Policies

The scope-down policy is composed of two session policies. The AssumeRoleWithWebIdentity request that Amazon Cognito makes in the background in the enhanced flow includes the following two:

  • Policy: An inline session policy.
  • PolicyArns: The AWS managed session policy AmazonCognitoUnAuthedIdentitiesSessionPolicy.

The IAM roles page states that the actual permissions for a role's session are the intersection of the permissions attached to the role and the session policy. Therefore, if a guest user is accessing a service, the necessary permissions must also be included in the role's policy. The session policy does not grant permissions; instead, it makes the permissions in the role's policy that fall outside the session policy unusable.

The inline session policy has two variations, depending on the Region. In the Regions enabled by default, the documentation's JSON specifies 32 actions. For other Regions, the documentation states that it removes the following Action statements from the policy for the Regions enabled by default.

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

Of these six, sumerian:View* is not included in the JSON for the Regions enabled by default.

The IAM roles page describes the value for PolicyArns as an AWS managed policy that grants additional permissions in Amazon CloudWatch. The JSON document for AmazonCognitoUnAuthedIdentitiesSessionPolicy, also listed on the same page, includes, in addition to rum:PutRumEvents, the geo actions of Amazon Location Service, and eight actions of AWS KMS. The description and the contents do not cover the same scope (see Section 10.1).

7.3 Services That Guests Can Use

The IAM roles page lists the services available to guests in the enhanced flow in a table. This article does not reproduce the product names listed in that table. The table still contains products whose names or status have changed. For example, the table lists Amazon CodeWhisperer, while AWS Toolkit documentation states that Amazon CodeWhisperer is part of Amazon Q Developer as of April 30, 2024.

Instead of the table, this article shows the scope with the namespaces in the JSON of the inline session policy. As of November 10, 2026, the inline session policy for the Regions enabled by default permits the following actions:

"cloudwatch:*", "logs:*", "dynamodb:*", "kinesis:*", "mobileanalytics:*", "s3:*", "ses:*", "sns:*", "sqs:*", "lambda:*", "machinelearning:*", "execute-api:*", "iot:*", "gamelift:*", "cognito-identity:*", "cognito-idp:*", "lex:*", "polly:*", "comprehend:*", "translate:*", "transcribe:*", "rekognition:*", "mobiletargeting:*", "firehose:*", "appsync:*", "personalize:*", "sagemaker:InvokeEndpoint", "cognito-sync:*", "codewhisperer:*", "textract:DetectDocumentText", "textract:AnalyzeDocument", "sdb:*"

This JSON does not include all actions listed in the table. Actions related to AWS KMS and Amazon Location Service are defined in the AmazonCognitoUnAuthedIdentitiesSessionPolicy. A smaller table that follows the main table on the IAM roles page lists the permitted actions for services such as AWS KMS, Amazon SageMaker AI, Amazon Textract, and Amazon Location Service. When verifying the scope, reopen the table on the IAM roles page and the two JSON documents on the day you check.

7.4 Restrictions That Apply to All Users

The IAM roles page describes restrictions that apply to both authenticated and guest users as follows:

Amazon Cognito also prevents authenticated and unauthenticated users from making API requests to Amazon Cognito identity pools and Amazon Cognito Sync.

This is a separate restriction from scope-down. The documentation notes that other AWS services may also impose their own limitations on access originating from web identities.

7.5 When You Want Services Outside the List

The IAM roles page says that if users see NotAuthorizedException errors from services that the guest role's policies allow, first evaluate whether those services can be removed from your use case, and if they cannot, switch to the basic flow. For services outside the list, the page states:

To grant access to AWS services beyond this list, activate the basic (classic) authentication flow in your identity pool.

This article reads this sentence together with the two sentences in Section 4.5. The authentication flow page states that it is best practice not to activate the basic flow by default in a new identity pool. The IAM roles page states that it is best practice not to grant guests permissions above the scope-down policy. When the basic flow is enabled, the role mappings and the guest scope-down of that identity pool become controls on the application side (Inference).

8. Attributes for Access Control

This chapter outlines the key aspects of access control based on attributes within an identity pool. The attributes for access control page describes this as an implementation of Attribute-Based Access Control (ABAC) for the identity pool.

Attributes for access control is the Amazon Cognito identity pools implementation of attribute-based access control (ABAC).

Attribute-based access control is not a mechanism for selecting roles. Instead, it is a system that attaches principal tags to user sessions based on the user's token claims. IAM policies evaluate these tags using ${aws:PrincipalTag/tagkey}.

Configuration options are available on a per-authentication provider basis, with three options to choose from:

  • Disabled: No principal tags are attached.
  • Default Mapping: Tags are attached based on the sub and aud claims in the IdP's token.
  • Custom Mapping: You specify the tag key and the claim that will serve as the tag's value.

The role's trust policy must allow Amazon Cognito to attach tags to the user's session. The attributes for access control page recommends adding sts:TagSession in addition to sts:AssumeRoleWithWebIdentity.

For the default mapping, the tag values are derived from the claims in the IdP's token. In a user pool's ID token, aud represents the application client's ID, and sub represents the user pool user's ID. This is a different value than the identity ID referenced in Section 6.2, cognito-identity.amazonaws.com:sub.

The attributes for access control page also recommends ensuring that when mapping custom attributes from the user pool to tags, users cannot modify those attributes. The page also says that values containing characters like * or ? function as wildcards during policy evaluation and can match more resources than intended.

9. How Long Each Credential and Token Lasts

This chapter lists the validity periods of the credentials and tokens encountered in the identity pool flow.

9.1 The Lifetime Table

ItemAPI That Issues ItValidity PeriodField for Specifying DurationVerification Date
Enhanced flow credentialsGetCredentialsForIdentity1 hourDocumentation does not list2026-11-10
Basic flow credentialsAssumeRoleWithWebIdentityDefault: 3600 seconds. Range: 900 seconds to the maximum session duration of the role.DurationSeconds2026-11-10
GetOpenIdToken TokenGetOpenIdToken10 minutesDocumentation does not list2026-11-10
Developer Identity TokenGetOpenIdTokenForDeveloperIdentityDefault: 15 minutes. Maximum: 24 hoursTokenDuration2026-11-10

Reading the Table:

  • Enhanced flow credentials refers to a statement on the authentication flow page. The documentation does not explicitly state that this duration cannot be modified. The GetCredentialsForIdentity request does not include a field for specifying the duration.

The AWS credentials from enhanced authentication are valid for one hour.

  • Basic flow credentials refers to a statement in the STS API Reference. The maximum session duration of the role can range from 1 hour to 12 hours.

You can provide a value from 900 seconds (15 minutes) up to the maximum session duration setting for the role. This setting can have a value from 1 hour to 12 hours.

  • The GetOpenIdToken token is based on the statement in the Cognito Identity API Reference: The OpenID token is valid for 10 minutes.
  • For the developer identity token, TokenDuration is specified in seconds, with a range of 1 to 86400. The documentation notes that extending the token duration may result in compromised tokens being used during that period.
  • The Expiration of Credentials is the date and time at which the received credentials expire (see Section 3.3).

9.2 When Credentials Expire

As a general description of web identity federation, the IAM federation page says that the credentials are valid for one hour by default, and that when they expire, or before then, you obtain new credentials. Since the IdP token also expires, you may need to refresh the IdP token before obtaining a new one.

The authentication flow page indicates that the credentials providers of the AWS Mobile SDKs and the AWS SDK for JavaScript in the Browser handle caching of the identity ID. The order in which the SDKs search for credentials is covered in this site's The AWS Credential Provider Chain Across SDKs and the CLI.

10. Where the Sources Disagree and What They Do Not Say

This chapter identifies inconsistencies and missing information found in the sources reviewed for this article.

10.1 Where the Sources Disagree

This article treats the following six as Sources disagree. For each, this article does not decide that either side is wrong.

  1. Explanation of cognito-identity.amazonaws.com:aud and cognito-identity.amazonaws.com:sub. The IAM roles page describes aud as the identity pool ID and sub as the identity pool identity ID. The IAM condition keys page, under the Amazon Cognito section, describes aud differently and explains sub as a unique identifier for a user in a user pool. The example conditions provided in that same section use a value in the format of an identity pool ID for aud and a value in the format of an identity ID for sub.

The user pool app client that authenticated your user. Amazon Cognito renders the same value in the access token client_id claim.

  1. Length of the credentials exchanged for a developer identity token. The Cognito Identity API Reference, in the description of TokenDuration in GetOpenIdTokenForDeveloperIdentity, states that the credentials obtained by exchanging the token with AWS STS are valid for a maximum of one hour. The STS API Reference states that the DurationSeconds parameter can be set from 900 seconds to the maximum session duration of the role. The authentication flow page states that the session length for a role can be specified in the basic flow.

You can exchange the token with Amazon STS for temporary AWS credentials, which are valid for a maximum of one hour.

  1. Whether AmbiguousRoleResolution is required. The Cognito Identity API Reference's RoleMapping page states that AmbiguousRoleResolution is required if either Token or Rules is specified, while the table on the same page lists it as Required: No (Section 5.5).

  1. The token that the enhanced flow uses. The authentication flow page lists ID tokens as the proof of authentication that the identity pool accepts from user pools and OIDC IdPs. The same page also states that in the enhanced flow, GetCredentialsForIdentity requests a role based on the contents of the access token.

  1. Explanation of the managed policy in the guest scope-down. The IAM roles page describes the value for PolicyArns as an AWS managed policy that grants additional permissions in Amazon CloudWatch. The JSON for AmazonCognitoUnAuthedIdentitiesSessionPolicy, also on the same page, includes actions for services such as AWS KMS and Amazon Location Service, in addition to Amazon CloudWatch (Section 7.2).

  1. Permissions of the role that the console creates by default. The authentication flow page states that the role created by default in the Amazon Cognito console has permissions for Amazon Cognito Sync and Amazon Mobile Analytics. However, later on the same page, it states that the default role created by the console essentially has no permissions. It is unclear from the text which of these descriptions accurately reflects the current console configuration.

10.2 Items with No Statement Found

No statement of the following items was found in the materials reviewed for this article (No statement found). None of them shows that the item does not exist.

  • The default value of AllowClassicFlow.
  • How to change the duration of enhanced flow credentials.
  • Whether an identity pool is covered under the feature plan for Amazon Cognito.
  • The update history for identity pools. The history page could not be accessed using curl.

10.3 Timing of Related Changes

  • AWS PrivateLink: One of the What's New posts announced that identity pools now support AWS PrivateLink, with a publication date of December 11, 2025. The announcement specifies that this applies to all Regions except for the China (Beijing) Region operated by Sinnet and the AWS GovCloud (US) Region.
  • Amazon Cognito Sync: The Cognito Sync page indicates that the service is no longer accepting new customers. The page does not give a date. One of the What's New posts, published on June 30, 2026, states that starting July 30, 2026, services including Amazon Cognito Sync will no longer be available to new customers. Existing customers can continue to use them.
  • Token Issuers: The developer-authenticated identities page includes a table listing token issuers by Region. This article does not list those Regions (see Section 4.3).

10.4 Important Notes When Reading

  • The tables listing services available to guest users, and the session policy JSON, are subject to change by AWS. The JSON in Section 7.3 contains information as of the verification date.
  • The table on the IAM roles page still lists products whose names or status have changed. Do not simply copy the table names as they appear.
  • The discrepancies in Section 10.1 disappear if the documentation is corrected. Before the design, reopen the sources you use on that day.

11. Failure Modes

This chapter gathers common failures identified from the materials presented in Chapters 3 through 10.

  • Misunderstanding that scope-down applies to authenticated users as well: The documentation mentions scope-down only for guest credentials in the enhanced flow (Section 7.1).
  • Misunderstanding that because scope-down exists, the guest role's policy can be broad: The documentation addresses scope-down in the context of the enhanced flow. It recommends against granting the guest role permissions that exceed scope-down (Section 7.1).
  • Misunderstanding that the aud condition is only required for the basic flow: The aud condition is required for both flows; trust policies without this condition cannot be saved (Section 6.1).
  • Misunderstanding that the basic flow is disabled by default: The documentation recommends against enabling the basic flow by default in new identity pools. No statement of the default value was found (Section 4.5).
  • Misunderstanding that the basic flow can be used in an identity pool with role mapping configured: The GetOpenIdToken API returns an error (Section 4.5).
  • Misunderstanding that CustomRoleArn allows the application to choose any role: CustomRoleArn is used to select a role from the list defined in cognito:roles. If a role that is not listed is provided, the request is rejected (Section 5.4).
  • Misunderstanding that all rules are evaluated and all matching roles are usable: Only the role associated with the first matching rule is used (Section 5.3).
  • Misunderstanding that rules and token claims apply to developer identity users: Developer identity users receive credentials for the default authenticated role (Section 5.6).
  • Attempting to map user-modifiable claims and attributes to higher-permission roles or principal tags: This would allow users to select those roles or tags themselves (Section 5.7 and Chapter 8).
  • Misinterpreting cognito-identity.amazonaws.com:sub as the same value as the IdP token's sub: This value is the identity pool's identity ID (Section 6.2).
  • Attempting to apply an aws:SourceIp condition to the trust policy of the role used in the enhanced flow: Since requests originate from Amazon Cognito, this condition will not be met (Section 6.4).
  • Configuring the Logins key in the enhanced form for a developer identity to use a value different from the token issuer: The GetCredentialsForIdentity API returns a NotAuthorizedException (Section 4.3).
  • Designing based on the assumption that the one-hour duration in the enhanced flow is an "unchangeable" value, which the documentation does not explicitly state: The documentation simply states valid for one hour (Section 9.1).
  • Determining the values for the aud and sub conditions solely based on the description on the IAM condition keys page: This conflicts with the explanation in the Cognito documentation (Section 10.1).
  • Directly copying product names from the table on the IAM roles page: This can result in outdated product names and statuses remaining (Section 7.3).

12. Frequently Asked Questions About Cognito Identity Pools

This chapter answers the assumptions listed in Section 1.1 with the statements in Chapters 3 to 10.

Q1. Are identity pool credentials narrowed by scope-down for every user?

No, they are not. The IAM roles page describes scope-down only for the credentials passed to guest users in the enhanced flow. The documentation does not describe this narrowing for the credentials of authenticated users. The limitation preventing authenticated and guest users from calling the identity pool and Amazon Cognito Sync APIs applies to both (see Sections 7.1 and 7.4).

Q2. Is the aud condition in the trust policy only required during the basic flow?

It is required in both flows. The IAM roles page states that aud is mandatory, and attempting to save a trust policy without this condition will result in an IAM error. The basic flow also has the same restriction. The differences specific to the basic flow are that it can request a role in a different account and that the aws:SourceIp condition takes effect (Chapter 6).

Q3. Is the basic flow disabled by default?

The documentation does not state this. The authentication flow page states, as a best practice, not to activate the basic flow by default in a new identity pool. The AllowClassicFlow setting within CreateIdentityPool is an optional Boolean, and no statement of a default value was found (Section 4.5).

Q4. Who selects the role?

In the enhanced flow, the identity pool configuration determines the role. The specific method for selecting the role – whether using the default role, token claims, or rules – is configured on a per-authentication provider basis. In the basic flow, the application specifies the role when calling AssumeRoleWithWebIdentity. During this process, roles with trust policies that trust the identity pool become potential candidates (see Chapters 4 and 5).

Q5. If the CustomRoleArn is provided, can the application choose any role it wants?

No. When selecting a role using the token's claims, the CustomRoleArn must match a role listed in the cognito:roles claim. If there is no match, the request will be rejected (see Section 5.4).

Q6. Does the cognito-identity.amazonaws.com:sub value in the trust policy match the sub value of the IdP?

It does not. The IAM roles page refers to this value as the identity pool's identity ID, explicitly stating that it is not the sub value from the user's original IdP. The description on the IAM condition keys page disagrees with this (Sections 6.2 and 10.1).

Q7. Is the lifetime of enhanced flow credentials set by the role's maximum session duration?

The documentation does not state this. The authentication flow page indicates that credentials from the enhanced flow are valid for one hour, and the GetCredentialsForIdentity request does not include a field to specify a duration. The maximum session duration of the role applies to the basic flow, where the application specifies the DurationSeconds parameter in the AssumeRoleWithWebIdentity call (see Section 9.1).

Q8. Where do you check the range of services that guests can use?

You can check this by reviewing the table on the IAM roles page, the JSON of the inline session policy on the same page, and the JSON for AmazonCognitoUnAuthedIdentitiesSessionPolicy. When reviewing the table, be sure to cross-reference the product names with the namespaces in the JSON documents (see Section 7.3), as the table still contains products whose names or status have changed.

13. Summary

Before designing the roles for your identity pool and guest access, ensure the following:

  • Review the authentication flow page, role-based access control page, and IAM roles page. Verify that the flow, role selection process, and guest scope have not changed since November 10, 2026, the verification date of this article.
  • Determine whether to use the enhanced or basic flow. If you are not using the basic flow, ensure it is disabled in that identity pool.
  • For each authentication provider, decide whether roles will be selected based on the default role, token claims, or rules. Also, define the AmbiguousRoleResolution behavior when a role cannot be determined.
  • Arrange the rules in order, assuming that the first matching rule will be applied.
  • Ensure that the default authenticated role is used for developer identities, and that this is reflected in the role permissions.
  • Do not associate user-modifiable claims or attributes with higher-permission roles or principal tags.
  • Ensure that all roles have a trust policy that includes an aud condition, and that the authenticated role is limited to authenticated users based on an amr condition.
  • Do not include an aws:SourceIp condition in the trust policy for roles used with the enhanced flow.
  • Do not grant guest roles permissions above the scope-down policy.
  • Verify the lifetimes of credentials and tokens against the table and documentation in Section 9.1.

14. References



References:
Tech Blog with curated related content

Written by Hidekazu Konishi