When sub Changes on Every Sign-In - Ephemeral Subject Identifiers and the AWS Receivers That Key on It

First Published: 2026-11-09
Last Updated: 2026-11-09

The sub claim in an OpenID Connect ID token is an identifier assigned to a user by the OpenID Provider (OP). OpenID Connect Core 1.0 defines two types for this identifier: public, which returns the same value for all Relying Parties (RPs), and pairwise, which returns a different value for each RP. OpenID Connect Ephemeral Subject Identifier 1.0, finalized in October 2026, introduced a third type: ephemeral. With ephemeral, the sub value will be different for every authentication request, even when a user signs in to the same RP.

AWS has several receivers that use the sub value to identify users. Amazon Cognito User Pools create usernames from the sub claim received from external OIDC Identity Providers. IAM role trust policies can use the condition key <provider>:sub to match the sub value. Amazon Verified Permissions creates a Cedar principal ID from the token claims.

This article separates the three types using primary sources and details how the documentation of AWS receivers handles the sub value when the OP returns a different value for every authentication request (i.e., using the ephemeral type). It presents a table, organized by receiver, outlining what happens at each point. It also identifies areas where the specifications are not fully defined, referencing the relevant specification text. This article does not make a recommendation on whether to use ephemeral. It is not an introduction to the new specification, and does not discuss pricing.

This article distinguishes between what the sources state, what is not found in the sources, and where discrepancies exist between the sources. The information presented in the sources was verified as of November 8, 2026.

Related articles on this site:

1. Scope and Assumptions
2. How to Read the Tables
3. Three Types of Subject Identifiers
4. The Range in Which the Value Stays the Same
5. A Map of the AWS Receivers
6. In Amazon Cognito User Pools
7. In IAM and AWS STS
8. In ALB, API Gateway, Verified Permissions, IAM Identity Center, and Amazon EKS
9. Design Options That Do Not Use sub as the Primary Key
10. Where the Sources Disagree and What They Do Not Say
11. What This Setup Showed
12. Failure Modes
13. Frequently Asked Questions About Ephemeral Subject Identifiers and AWS Receivers
14. Summary
15. References

1. Scope and Assumptions

This chapter will first define the intended audience, the scope of this article, the relevant source materials, and the terminology used. The following thirteen points will outline the conclusions.

OpenID Connect Core 1.0, Section 8, defines two types: public and pairwise. public returns the same sub value for all Relying Parties (RPs) and is the default when the OpenID Provider (OP) Discovery document lacks subject_types_supported. pairwise returns a different sub value for each RP, and its calculation must be deterministic (MUST) (Chapter 3).
Ephemeral Subject Identifier 1.0, Section 4, defines ephemeral as a type where the sub in the ID token is different for every authentication request. The OP must not reuse the value of ephemeral (MUST NOT) (Chapter 3).
Section 1 of the same specification states that the identifier for ephemeral remains constant for the duration of the authentication session. The term authentication session is not defined in either RFC 6749 (which Section 3 references) or OpenID Connect Core 1.0. This article does not combine Sections 1 and 4 into a single sentence (Chapter 4).
Regarding the sub value in the ID token returned during a refresh, OpenID Connect Core 1.0, Section 12.2, states that it must be the same as the original value (MUST). Logout tokens for Back-Channel Logout without an sid are intended to apply to all sessions for that user on the RP. Ephemeral Subject Identifier 1.0 does not discuss refresh or logout (Chapter 4).
As of November 8, 2026, two GitHub issues have been open that raise these two points. Both were submitted as comments after the public review deadline, and the sakimura account in the repository has responded accordingly. This article does not treat these as decisions or defects of the specification (Section 4.4).
The specification’s header date is October 7, 2026, and the announcement of approval by the OpenID Foundation is October 8, 2026. These are separate events and do not represent a discrepancy in the sources (Section 4.5).
Amazon Cognito User Pools create usernames by prepending the name of the external OIDC IdP to the sub value. If a linked profile is not present during the initial sign-in, a new profile is created. The inference (Inference) of this article, based on these two statements, is that a new profile is created with each sign-in with an ephemeral OP (Chapter 6).
The page for creating IAM OIDC IdPs instructs users to ensure that the Discovery document includes subject_types_supported: public. There is no mention of IAM rejecting OPs that only support ephemeral (Section 7.1).
In the response from AWS STS’s AssumeRoleWithWebIdentity, the SubjectFromWebIdentityToken field contains the value of the ID token’s sub. The API reference describes this as “typically” a pairwise identifier. This description does not refer to ephemeral (Section 7.3).
ALB’s x-amzn-oidc-identity is an unsigned header for backward compatibility. To verify the user and identify them, the signed x-amzn-oidc-data header must be validated, and the sub value extracted from it (Section 8.1).
The list of claims that the API Gateway’s JWT authorizer evaluates does not include sub. Verified Permissions creates a principal ID from the claim selected using principalIdClaim. IAM Identity Center matches users from external IdPs using SAML’s NameID. For Amazon EKS OIDC, the default usernameClaim is sub (Chapter 8).
Apart from public on the IAM create page, the documentation for AWS receivers does not mention distinguishing between subject identifier types (Section 10.3). Chapter 11 presents a minimal OP that returns ephemeral’s sub to observe the results from Amazon Cognito and IAM.
In the configuration presented in Chapter 11, signing in to an ephemeral OP five times resulted in five users being created in the Amazon Cognito user pool. An OP with only ephemeral listed in its Discovery document could also be created as an IAM OIDC IdP, and its token successfully passed AWS STS’s AssumeRoleWithWebIdentity. All of these are observations (Observation) from a single configuration.

1.1 Intended Audience

This article is intended for developers who:

Integrate external OIDC Identity Providers (IdPs) using Amazon Cognito User Pools, IAM OIDC configuration, ALB OIDC authentication, or Verified Permissions, and use the sub claim as the user's key.
Need to understand what changes when their integrated IdP modifies the type of the sub claim, or when they, as an RP, request ephemeral.
Are responsible for creating documentation outlining specifications and AWS-specific details related to the use of sub.

This article assumes that readers are considering the following points, and each will be verified through the provided materials:

An ephemeral sub always changes with every login.
IAM cannot register an OP that lists only ephemeral.
The pairwise identifier mentioned in the STS documentation refers to ephemeral.
The sub claim is a value that does not change, used to identify users.

1.2 What This Article Covers and What It Does Not

This article addresses the definitions and normative text of three types of subject identifiers, the values associated with Discovery and Dynamic Client Registration, what the specifications say about the range in which the value stays the same, the specification version and approval history (one paragraph), and the usage of sub within various AWS services (Amazon Cognito User Pools, IAM and AWS STS, ALB, HTTP API JWT authorizers in API Gateway, Verified Permissions, IAM Identity Center, and Amazon EKS), and what the documents allow us to say when sub changes.

This article does not cover the following.

Regarding Amazon Cognito attribute mapping and the code for the linking procedures, refer to Chapters 8 and 10 of the Amazon Cognito Federation Complete Implementation Guide on this site.
This site's AWS IAM Inbound Workload Federation covers the format of the sub value for IAM condition keys, partial matches, and details regarding sts:SourceIdentity.
The site's AWS Verified Permissions and Cedar Policy Language Complete Guide addresses Cedar policies and the design of identity sources.
JWT Signing Algorithms on AWS Endpoints and Secure Web Application Reference Architecture on AWS cover signature verification for Application Load Balancers (ALB) and the algorithms used for JWT signatures.
The sub value issued by AWS, the format of the sub value for Amazon EKS IRSA, and the sub value within chains of delegation for AI agents.
Amazon Cognito ID pools and JWT validation for Application Load Balancers (ALB), a feature designed for communication between services.
This article does not compile documentation regarding OpenID Providers (OPs) to determine if they support ephemeral. It does not address the compatibility status of major OPs.
Other articles within this series cover related topics. The requirements for synced passkeys are addressed in the article on synced passkeys (Synced Passkeys Under NIST SP 800-63B-4), which is based on NIST SP 800-63B-4. The dates and update relationships of the OAuth and OpenID standards are covered in the OAuth standards timeline (OAuth Standards History and Timeline).
Pricing.

1.3 Date of Review and Materials Reviewed

This article was written after reviewing the following materials on November 8, 2026. Throughout the text, the short names in parentheses will be used.

OpenID Connect Ephemeral Subject Identifier 1.0, final version (ESID final text)
OpenID Connect Core 1.0 incorporating errata set 2 (Core)
OpenID Connect Discovery 1.0 incorporating errata set 2 (Discovery)
OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 2 (Registration)
OpenID Connect Back-Channel Logout 1.0 incorporating errata set 1 (Back-Channel Logout)
OpenID Foundation: review announcement, vote announcement, and approval announcement.
GitHub repository openid/connect-ephemeral-sub, issues #20 and #21.
RFC 6749
Amazon Cognito Developer Guide: attribute mapping page, linking page, OIDC IdP page, OIDC flow page, federation overview page, pre sign-up page, inbound federation page.
Amazon Cognito User Pools API Reference: AdminLinkProviderForUser page.
AWS Identity and Access Management User Guide: IAM create page and condition keys page.
AWS STS API Reference: AssumeRoleWithWebIdentity page (STS API page).
Elastic Load Balancing: user authentication page (ALB authentication page).
Amazon API Gateway Developer Guide: JWT authorizer page for HTTP APIs.
Amazon Verified Permissions: Verified Permissions API page for CreateIdentitySource, OpenIdConnectAccessTokenConfiguration page, Verified Permissions user guide page for identity sources, CloudFormation page for AWS::VerifiedPermissions::IdentitySource, Security Blog post on Verified Permissions and Amazon Neptune.
AWS IAM Identity Center User Guide: external IdP page (SAML and SCIM), trusted token issuer page, and trusted token issuer apps page.
Amazon EKS API Reference: OidcIdentityProviderConfigRequest page (EKS API page).

None of the AWS pages in Section 1.3 use the term "ephemeral." This article presents a comparison of specifications and AWS documentation, but the comparison is not a statement in the AWS pages themselves.

1.4 Terms, and Different Things with the Same Spelling

This article will consistently use the following terms:

OP: The entity that issues an ID token (OpenID Provider). In this article, it is also referred to as an external IdP.
RP: The entity that receives the ID token (relying party). In the specifications, this is also referred to as "Client."
Receiver: A term used in this article, not a term found in external documentation. It refers to the functions of AWS services that receive the sub value and use it as the key for users or in conditions.
Subject identifier type: The three types public, pairwise, and ephemeral. This article writes the type names in this spelling, without translation.
Authentication request: A single request from the RP to the OP requesting authentication. This is a term used in Section 4 of the ESID final text.
Authentication session: A term used in Section 1 of the ESID final text. None of the sources defines it (Section 4.1).
Sign-in: A term used in the title and body of this article. In this article, it refers to a user accessing the RP after a single authentication request process. This is not a term used in the specifications.

The term sub appears in this article with three different meanings. This article will not combine these three meanings into a single term.

sub claim: The value that the OP includes in the ID token. When this article simply uses the term sub, it refers to this.
Amazon Cognito sub attribute: A value that Amazon Cognito User Pools create for each user profile. This is a different value from the sub claim of an external IdP.
Condition key <provider>:sub: A condition key used in the IAM role trust policy to match the value of the sub claim. <provider> represents the name of an OIDC IdP.

2. How to Read the Tables

This chapter defines the columns in the tables presented in this article, as well as the way to describe the state of the sources, and the way to write normative terms. The columns in the summary table, presented in Chapter 9, are used consistently across three articles within the same series.

2.1 Table Columns

The summary table in Section 9.5 has the following seven columns:

Requirement or Behavior: The requirement (a specification statement) or the behavior of an AWS service in the row.
Who Must Act (Spec): The entity responsible for fulfilling the requirement. In this article, this column specifies the subject of the specification text.
AWS Receiver: The AWS service involved in the row. For rows that are not settings of an AWS receiver, this column has —.
What You Can Set: The configuration or value that can be set for the row. The existence of a corresponding setting does not indicate compliance with the specification.
What You Cannot Set: Configurations explicitly stated as not supported in the documentation, as well as configurations for which no information is found. The cell states which one it is, with the terms in Section 2.2.
Where It Is Written: The source of the information for the row.
Source State: The state of the documentation, written with the terms in Section 2.2.

The tables in Sections 3.4 (regarding the types), 4.6 (regarding undefined points in the specification), 5.2 (regarding receivers), 6.6 (regarding Amazon Cognito), and 7.5 (regarding IAM and AWS STS) use columns specific to this article. Each section provides a detailed explanation of the columns.

2.2 Terms for the State of the Sources

This article uses eight terms to describe the state of the documentation. These terms, including their English spellings, are also used within 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.
Not recorded (stated): The documentation states that the information is not included in logs or records.
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 does not settle which statement applies. This article will present both statements and their sources without designating either as incorrect.
Inference: This is 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.
Observation: This is based on observations made during testing (as described in Chapter 11) and is not a commitment made by the documentation. This article will not override statements found in the documentation with observations.

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.3 How This Article Writes Normative Terms

Section 2 of the ESID final text defines normative terms as follows.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP14 when, and only when, they appear in all capitals, as shown here.

BCP 14 consists of RFC 2119 and RFC 8174. Section 1.1 of Core states that the same terminology is to be interpreted as described in RFC 2119.

This article will retain the original capitalization of terms such as MUST, MUST NOT, SHOULD, and MAY, without translation. When this article rephrases requirements, the original terms will also be included in parentheses. Terms written in lowercase in the original text will not be treated as normative terms.

This article will indicate the source of each statement in the same sentence. Even when referring to the same AWS service, the text from the API reference, the user guide, and the AWS Security Blog will be treated as separate sources.

3. Three Types of Subject Identifiers

This chapter differentiates three types of subject identifiers: two within Core and a third added in the ESID final text, as defined by the specification. Figure 1 illustrates the different sub values received by the RP when the same user signs in twice to each of two different RPs.

3.1 `public`

Section 8 of Core defines public as follows:

public
This provides the same sub (subject) value to all Clients. It is the default if the provider has no subject_types_supported element in its discovery document.

A public OP returns the same sub to every RP. If the OP's Discovery document does not include subject_types_supported, then public is the default.

3.2 `pairwise`

Section 8 of Core defines pairwise as follows:

pairwise
This provides a different sub value to each Client, so as not to enable Clients to correlate the End-User's activities without permission.

The OP of pairwise returns a different sub value for each RP. The purpose is to prevent RPs from correlating a user's activities without permission. Section 8.1 of Core states the following regarding the calculation of pairwise values:

The algorithm MUST be deterministic.

Because the calculation is deterministic, the sub value of pairwise will remain the same regardless of how many times the same user signs in to the same RP. Section 8.1 of Core also requires that no party other than the OP can reverse the value (MUST NOT be reversible) and that the value will differ if the sector identifier is different (MUST).

3.3 `ephemeral`

Section 4 of the ESID final text adds a third type to Section 8 of Core. The definition reads as follows:

ephemeral
type of an identifier when the sub provided by ID Token is different for every authentication request

The same section also requires OP to provide the following four points to prevent RP from associating multiple authentication responses:

The identifier value for ephemeral must not be reused (MUST NOT).
A value must be generated with a probability of prediction no greater than 2^-128 (MUST).
The target should be a probability of prediction no greater than 2^-160 (SHOULD).
Values should be generated with a probability of collision that is negligible given the expected operational period and scale (SHOULD).

The original text for the section on collision probability reads as follows:

SHOULD generate the value with a collision probability that is infeasible for the expected lifetime and scale of the deployment.

Section 7 of the ESID final text states that if a collision occurs, RP may associate two authentication responses, potentially for two different users, to the same record. This can result in account mix-ups and incorrect authorization decisions. The section also notes that generic pseudo-random function capabilities are insufficient.

Section 2 of Core describes sub as follows:

A locally unique and never reassigned identifier within the Issuer for the End-User

Section 5.7 of Core states that sub and iss, used together, are the only claims that an RP can rely upon as a stable identifier for the End-User. A statement on how Sections 2 and 5.7 of Core apply to ephemeral was not found in the ESID final text (No statement found).

3.4 How the Type Is Chosen

The OP lists the types and the RP selects one. The relevant text for ESID final, Core, and Registration is as follows:

Core §8 states that the OP's Discovery document must list its supported types in the subject_types_supported field (MUST). If multiple types are available, the RP may indicate its preferred type in the Registration subject_type field (MAY).
Discovery §3 and Registration §2 list pairwise and public as valid types.
ESID final text §5 adds the value ephemeral to the OP's Discovery subject_types_supported field.
ESID final text §6 describes how the RP requests ephemeral as follows:

by registering ephemeral as the subject_type in OpenID Dynamic Client Registration 1.0 or by other means

The ESID final text does not say what or by other means covers.

The following table lists the three types: The columns are Type, sub when signing in twice to the same RP, sub for a different RP, how it is determined, the relevant text in the specifications, where it is documented, and the state of the documentation.

Type	Same RP, Two Sign-Ins	Different RPs	How It Is Chosen	Normative Text	Where It Is Written	Source State
`public`	Same value	Same value	Default when `subject_types_supported` is not present	Text stating it is the default (no normative language)	Core §8	Stated
`pairwise`	Same value (deterministic calculation)	Different value	`subject_types_supported` and `subject_type`	The calculation must be deterministic (MUST).	Core §8, §8.1	Stated
`ephemeral`	Different value	Different value	`subject_types_supported` and `subject_type`, or by other means	The value must not be reused (MUST NOT).	ESID final text §4, §5, §6	Stated

4. The Range in Which the Value Stays the Same

This chapter clarifies what the specifications state and do not state regarding the range within which the sub value of an ephemeral identifier remains constant.

4.1 Section 1 and Section 4

Section 1 of the ESID final text is written as follows, serving as an introductory statement:

The ephemeral subject identifier identifies the End-User for a short time and remains constant for the duration of the authentication session.

Section 4 of the ESID final text is written as follows, serving as a definition:

type of an identifier when the sub provided by ID Token is different for every authentication request

Section 1 says "constant for the duration of the authentication session," while Section 4 says "different for every authentication request." Whether these two sections refer to the same scope is determined by the meaning of authentication session. Section 3 specifies the use of terms from RFC 6749 and Core. Based on a search conducted on November 8, 2026, the term "authentication session" appeared zero times in either RFC 6749 or Core, and only once within the ESID final text, specifically in Section 1. The definition of authentication session was not found (No statement found).

Section 1 also states that a different value is returned on subsequent visits, and that the ephemeral identifier is passed in the ID token and the UserInfo response.

4.2 ID Tokens Returned by a Refresh

Core §12.2 specifies the requirements for returning an ID token in response to a refresh request, stating:

its sub Claim Value MUST be the same as in the ID Token issued when the original authentication occurred

The ESID final text does not mention refresh (No statement found). It is not possible to determine from the ESID final text whether the sub value of the ephemeral token remains unchanged during the refresh process.

4.3 Back-Channel Logout

Section 2.4 of Back-Channel Logout describes the logout token, stating the following two points:

A Logout Token MUST contain either a sub or a sid Claim, and MAY contain both.

If a sid Claim is not present, the intent is that all sessions at the RP for the End-User identified by the iss and sub Claims be logged out.

Section 2.2 of Back-Channel Logout specifies that the default value for backchannel_logout_session_required, with which the RP requires sid, is set to false. The ESID final text does not contain any information regarding logout (No statement found). The sub for ephemeral is different for every authentication request, so it is not determined by the specifications whether RP can find other sessions of the same user using only the sub claim in the logout token. This is this article's inference (Inference).

4.4 Issues That Raise the Same Points

Here are two issues in the GitHub repository openid/connect-ephemeral-sub that raise the same points as those discussed in Sections 4.2 and 4.3. As of November 8, 2026, both issues are open.

Issue #20 highlights a problem with logout. The title is Ephemeral sub breaks logout when RPs don't require a session ID.
Issue #21 raises concerns about refresh tokens and the fact that authentication session is undefined. The title is Refresh Token continuation is unaddressed, and could quietly defeat the document's own anti-correlation goal.

The same user filed both issues on September 21, 2026. On October 5, 2026, the sakimura account within the repository responded to both issues, noting that the comments arrived after the public review deadline (September 15, 2026), and requesting that the user provide identifying information as required by the Contribution Agreement. The authors of the ESID final text are N. Sakimura and E. Jay. Issue #21 references the sentence from Section 1 of the ESID final text as a Section 4 sentence, while this article references it as a sentence from Section 1 of the ESID final text.

This article does not present these two issues as decisions of the specification, nor as defects in the specification, nor as topics being addressed by the working group. The table in Section 4.6 is composed solely of specification language, and the issues are added as issues that raise the same points.

4.5 Version and Approval

The header of the ESID final text shows Published: 7 October 2026 and Status: Final. The OpenID Foundation’s review announcement began a 60-day public review period on July 17, 2026, with the deadline set for September 15, 2026. The vote announcement was released on September 2, 2026, establishing a voting period from September 16, 2026, to September 30, 2026. The approval announcement, released on October 8, 2026, detailed the results: 79 votes in favor, 4 votes against, and 19 abstentions. The publication date and the dates of the announcements represent separate events and do not indicate any discrepancies in the documentation. According to the approval announcement, the final specification will not be further revised. The list of specifications on openid.net includes drafts ranging from -00 (June 24, 2025) to -03. The dates of the OAuth and OpenID standards are covered in the OAuth standards timeline (OAuth Standards History and Timeline).

4.6 Table of Points the Specifications Do Not Settle

The following table lists sentences from the ESID final text and other OpenID specifications regarding an ephemeral sub. The columns represent: question, sentence from the ESID final text, sentence from other OpenID specifications, state of the sources, and the issue that raises the same point.

Question	ESID Final Text	Other OpenID Specifications	Source State	Open Issue (Checked on 2026-11-08)
What does the value change with?	§4: Different for every authentication request	—	Stated	—
Over what range is the value constant?	§1: Constant for the duration of the authentication session	The definition of authentication session is not found in RFC 6749 or in the Core specification.	No statement found (definition)	issue #21
`sub` in the ID token returned by a refresh	Not stated.	Core §12.2: MUST be the same as the original value	No statement found (ESID final text)	issue #21
Logout tokens without `sid`	Not stated.	Back-Channel Logout §2.4: Intended to apply to all sessions of the user.	No statement found (ESID final text)	issue #20
`sub` for UserInfo	§1: Passed in both the ID token and the UserInfo response.	—	Stated	—
How does the RP request `ephemeral`?	§6: Through the `subject_type` in Registration, or through other means.	Registration §2: Lists `pairwise` and `public` as valid types.	Stated (what other means covers: No statement found)	—

5. A Map of the AWS Receivers

This chapter lists which AWS receivers receive the sub value and where. Figure 2 illustrates where the sub value from the OP's ID token is directed in each receiver.

5.1 Receivers and Where `sub` Goes

Amazon Cognito User Pools: the username (sub after the IdP name). Chapter 6.
IAM: Condition key in the role trust policy: <provider>:sub. Chapter 7.
AWS STS: SubjectFromWebIdentityToken in the response of AssumeRoleWithWebIdentity and AWS CloudTrail logs. Chapter 7.
Application Load Balancer (ALB): Headers passed to the target. Section 8.1.
API Gateway HTTP API JWT authorizer: Token validation. Section 8.2.
Verified Permissions: ID of the Cedar principal. Section 8.3.
IAM Identity Center: NameID from external IdP's SAML and trusted token issuer attribute mapping. Section 8.4.
Amazon EKS: Kubernetes username (usernameClaim). Section 8.5.

5.2 Receiver Table

The following table lists, for each receiver, how sub is used, text about distinguishing types, what can be said from the documents when sub changes, the source, and the state of the sources.

AWS Receiver	Where sub Goes	Text About Subject Types	When sub Changes (From the Documents)	Where It Is Written	Source State
Amazon Cognito user pool	Username (`sub` after the IdP name)	Not found	If linked profile is not present, a new profile is created. It is inferred that a new profile is created every time.	Attribute mapping page, linking page	Stated (username), Inference (new profile every time), No statement found (type)
IAM OIDC IdP creation	—	Confirmation step that the Discovery document includes `subject_types_supported: public`	No statement was found that an OP that lists only `ephemeral` is rejected	IAM create page	Stated (procedure), No statement found (rejection)
IAM role trust policy	Condition key `<provider>:sub`	Not found	A condition fixed to one value can be inferred not to match the value of the next authentication request	Condition keys page	Stated (condition key), Inference (comparison)
AWS STS response and CloudTrail	`SubjectFromWebIdentityToken`, CloudTrail logs	Described as typically a pairwise identifier	—	STS API page	Stated
ALB	`x-amzn-oidc-data`'s `sub`, legacy `x-amzn-oidc-identity`	Not found	—	ALB authentication page	Stated (header), No statement found (type)
API Gateway JWT authorizer	The list of claims to evaluate does not include `sub`.	Not found	—	JWT authorizer page	Documentation does not list (`sub`)
Verified Permissions	Principal ID (claim from `principalIdClaim`)	Not found	It can be inferred that the principal ID changes for each authentication request.	Verified Permissions API page, page for `OpenIdConnectAccessTokenConfiguration`	Stated (ID format), Inference (changes)
IAM Identity Center (external IdP)	SAML `NameID` is matched to the Username	—	This is not a path that uses OIDC `sub`.	External IdP page	Stated
IAM Identity Center (trusted token issuer)	Finds a single user by the claim chosen in attribute mapping	Not found	No statement was found that specifically mentions `sub`.	Trusted token issuer page	Stated (mapping), No statement found (`sub`)
Amazon EKS	Kubernetes username (default for `usernameClaim` is `sub`)	Not found	—	EKS API page	Stated

6. In Amazon Cognito User Pools

This chapter examines how Amazon Cognito User Pools utilize the sub claim from external OIDC Identity Providers (IdPs), based on the information provided in the Developer Guide and API Reference.

6.1 Usernames

The attribute mapping page explains that when integrating with an external Identity Provider (IdP), the user profile's username attribute is created from a specific claim provided by the IdP. In the context of OIDC, that claim is sub. The attribute mapping page provides an example of this format.

MyOIDCIdP_[sub]

The OIDC IdP page also states that Amazon Cognito automatically maps the OIDC sub claim to the username attribute of the profile being created. Amazon Cognito's sub attribute is a separate value created by Amazon Cognito itself. Chapter 8 of the Amazon Cognito Federation Complete Implementation Guide addresses this distinction between the two.

The attribute mapping page further explains that if you want users to have an attribute that precisely matches an attribute from an external directory, you should configure it to map to an Amazon Cognito sign-in attribute, such as preferred_username.

6.2 First Sign-In and Profile

The linking page contains the following two statements regarding the first sign-in:

When a federated user signs in to your user pool for the first time, Amazon Cognito looks for a local profile that you have linked to their identity.

If no linked profile exists, your user pool creates a new profile.

With an ephemeral OP, the sub which forms the basis of the username is different for every authentication request. Combining these two statements with the statement in Section 6.1, it can be inferred that with each sign-in, Amazon Cognito creates a new profile with a different username. This is this article's inference (Inference), and is not explicitly stated on the Amazon Cognito pages. In the setup in Chapter 11, when signing in five times with an ephemeral OP, Amazon Cognito created a new user with a different username each time, and the Pre sign-up trigger was invoked each time (Observation).

The pre sign-up page states that the Pre sign-up trigger is invoked during the first sign-in with a trusted IdP. The federation page states that if the attributes of the mapped IdP change, the attributes of the users in the user pool also change.

6.3 Linking with Claims Other Than `sub`

The linking page describes how to connect users using specific claims within OIDC and SAML Identity Providers (IdPs). The AdminLinkProviderForUser page states that, for OIDC, ProviderAttributeName can be any mapped value from a claim in the ID token or from a value that the app retrieves from the UserInfo endpoint.

There are two limits, and this article does not combine these two limits into a single number.

A single profile can be linked to a maximum of five linked users (as described on the linking page and the AdminLinkProviderForUser page).
For each IdP, a maximum of five claim attributes can be used when linking (as described on the linking page).

The linking page also states that to link users who have already signed in, it is necessary to first delete their existing profile. This site's Amazon Cognito Federation Complete Implementation Guide, Chapter 10, details the process of calling AdminLinkProviderForUser using the Pre sign-up trigger.

6.4 Inbound Federation Trigger

According to the inbound federation page, this trigger receives ID tokens (including the sub claim) and UserInfo responses from an external IdP, and returns the attributes to be mapped as specified in userAttributesToMap. There is no statement found indicating that this trigger allows modification of the original value of the username.

6.5 Statements About Distinguishing Types

The OIDC flow page lists items that Amazon Cognito verifies using ID tokens from external IdPs, such as signatures, iss, aud, and exp. However, there is no mention of distinguishing subject identifier types, either on the OIDC IdP page or the OIDC flow page (No statement found).

6.6 Amazon Cognito Table

The following table summarizes Sections 6.1 through 6.5. The columns are the item, what Amazon Cognito states, what can be said with an ephemeral OP, the source, and the state of the sources.

Item	What Amazon Cognito States	With an ephemeral OP	Where It Is Written	Source State
Username	`sub` after the IdP name	Becomes a different username for each authentication request	Attribute mapping page, OIDC IdP page	Stated (format), Inference (different username)
First Sign-in	Creates a new profile if linked profile is not present	A new profile is created with each sign-in	Linking page	Stated (text), Inference (every time)
Pre sign-up Trigger	Invoked on the first sign-in with a trusted IdP	Invoked with each sign-in	Pre sign-up page	Stated (text), Inference (every time)
Linking with claims other than `sub`	For OIDC, any mapped claim. Up to 5 users per profile, and up to 5 claims per IdP	Links without relying on `sub`	Linking page, `AdminLinkProviderForUser` page	Stated
Inbound Federation Trigger	Returns the attributes to map	It is unclear whether the original username value can be changed	Inbound federation page	No statement found (username)
Identifying the type	—	—	OIDC IdP page, OIDC flow page	No statement found

7. In IAM and AWS STS

This chapter examines how the sub claim is handled when using IAM's OIDC identity provider, the role's trust policy, and AWS STS's AssumeRoleWithWebIdentity functionality.

7.1 `public` on the Page for Creating an OIDC IdP

The page for creating an OIDC IdP states that before creating an IdP, it is necessary to verify that the IdP configuration (openid-configuration) includes the following values. The introductory text reads:

Confirm the following values are included in your provider’s configuration information. If your openid-configuration is missing any of these fields, you must update your discovery document.

The list of values to verify includes: response_types_supported: id_token, subject_types_supported: public, and id_token_signing_alg_values_supported. The JSON example on the same page also shows "subject_types_supported": [ "public" ].

This text is a confirmation step. However, the IAM create page does not explicitly state whether IAM will inspect the subject_types_supported value at registration or whether it will reject registrations from OpenID Providers (OPs) that only include ephemeral (No statement found). This article does not interpret the wording as either "IAM rejects ephemeral" or "IAM accepts ephemeral." In the setup in Chapter 11, an OP configured with only ["ephemeral"] for subject_types_supported could still be created as an IAM OIDC IdP, and AssumeRoleWithWebIdentity succeeded using tokens from that OP (Observation). Section 4.2 of this site's AWS IAM Inbound Workload Federation details the items that IAM checks for OIDC IdPs.

7.2 Condition Key `<provider>:sub`

The condition keys page describes how to create condition keys for OIDC, specifying the claim name after the name of the OIDC Identity Provider (IdP). In the generic OIDC table, the condition key sub corresponds to the sub claim in the ID token and is available in the session (marked as "Available in session" as Yes). In the same table, the condition key aud maps to the azp claim, and to the aud claim when no value is set for azp.

If you fix a single value for the condition key <provider>:sub in the trust policy, only ID tokens with a sub value matching that fixed value will satisfy the condition. In an ephemeral OP, the sub value of the next authentication request is different, so it can be inferred that tokens from that OP will not satisfy the fixed condition. This is this article's inference (Inference). In the configuration described in Chapter 11, when the condition key <provider>:sub was fixed to the value of the first ephemeral token, that token succeeded, while the remaining three tokens resulted in AccessDenied (Observation). The format and partial matches of the sub value are discussed in Sections 6.5 and 11.2 of this site's AWS IAM Inbound Workload Federation.

7.3 `SubjectFromWebIdentityToken`

The STS API page describes the SubjectFromWebIdentityToken element in the response to AssumeRoleWithWebIdentity as the unique user identifier returned by the Identity Provider (IdP). The description reads:

The identifier is typically unique to the user and the application that acquired the WebIdentityToken (pairwise identifier).

In OpenID Connect ID tokens, this element corresponds to the value of the sub claim. The length constraint is between 6 and 255 characters, inclusive. This constraint applies to the element in the response and is not a restriction on the input token itself.

The description uses the term "pairwise" with the qualifier "typically." It does not refer to "ephemeral" values. The STS API page does not specify how SubjectFromWebIdentityToken is handled when it contains values such as "public" or "ephemeral" (No statement found).

7.4 AWS CloudTrail and Personal Information

The note under "Important" on the STS API page states that calls to AssumeRoleWithWebIdentity may be logged by AWS CloudTrail, and that those logs include the Subject of the token. It recommends avoiding the use of personally identifiable information in this context. An example provided states:

For example, you could instead use a GUID or a pairwise identifier, as suggested in the OIDC specification.

The example recommended in that text uses GUIDs and pairwise identifiers, but does not mention ephemeral. In the setup in Chapter 11, the userName field within the userIdentity section of CloudTrail event history records for AssumeRoleWithWebIdentity contained the token's sub value, both in cases of success and in cases of AccessDenied (Observation). Whether an ephemeral sub in those logs could be used to link entries to one user is not determined by the text on the STS API page.

7.5 IAM and AWS STS Table

The following table summarizes Sections 7.1 through 7.4. The columns are the item, what IAM and AWS STS state, what can be said with an ephemeral OP, the source, and the state of the sources.

Item	What IAM and AWS STS State	With an ephemeral OP	Where It Is Written	Source State
OIDC IdP Creation	Confirm that the Discovery document includes `subject_types_supported: public`	Whether registration is rejected is not stated	IAM create page	Stated (procedure), No statement found (rejection)
Condition Key `<provider>:sub`	Corresponds to the `sub` value in the ID token and is usable in a session.	A condition fixed to one value does not match the next authentication request	Condition keys page	Stated (key), Inference (matching)
`SubjectFromWebIdentityToken`	The value of `sub`. Typically a pairwise identifier. Length 6 to 255	—	STS API page	Stated
CloudTrail Logging	Includes the token's Subject. Recommends using a GUID or a pairwise identifier.	`ephemeral` is not listed as an example.	STS API page	Stated

8. In ALB, API Gateway, Verified Permissions, IAM Identity Center, and Amazon EKS

This chapter focuses on the remaining receivers, verifying where sub is located and what information it contains.

8.1 ALB

The ALB authentication page describes the headers that ALB passes to the target after OIDC authentication. Only the x-amzn-oidc-data header is signed; this header contains the user's claims in the form of a JWT. To verify and identify the user, the ALB authentication page states:

To securely identify a user, verify the signature of x-amzn-oidc-data and extract the sub claim from the validated JWT payload.

The x-amzn-oidc-identity header is listed under the Legacy unsigned headers: subheading. The ALB authentication page indicates that this header contains the sub value from the UserInfo endpoint in plain text, and that it is provided without a signature and cannot be independently verified by the application. The subsequent note clarifies that this header is a legacy, unsigned header provided for backward compatibility.

The ALB authentication page also states that, until the cookie expires, subsequent requests will only pass through a portion of the authentication process. The same page uses the term authentication session for the ALB's own session, and states that its length is determined by the session timeout configured on the ALB for the authentication feature. This article does not read that as a definition of the term in Section 1 of the ESID final text. When the IdP provides a valid refresh token, the ALB will update the user's claims using that token each time the access token expires. Whether the sub value received by ALB remains the original value during this update is subject to the same considerations as outlined in Section 4.2, and is not determined by the ESID final text. This is this article's inference (Inference). A statement regarding distinguishing subject identifier types is not found in the ALB authentication page (No statement found).

8.2 API Gateway JWT Authorizer

The JWT authorizer page lists the following claims that the JWT authorizer evaluates: kid, iss, aud or client_id, exp, nbf, iat, scope or scp. The list does not include sub (Documentation does not list). The listed validation steps do not use the value of sub. Using sub as the user's key is up to the application after it receives the token.

8.3 Verified Permissions

The API Reference for Verified Permissions, specifically the OpenIdConnectAccessTokenConfiguration section, describes the principalIdClaim as the claim used to determine the principal within an OIDC access token, providing sub as an example. The Verified Permissions API page specifies the format of the principal ID when using an OIDC Identity Provider (IdP) as follows:

Namespace::[Entity type]::[entityIdPrefix]|[user principal attribute]

When the principalIdClaim is sub and the OP is ephemeral, the principal ID will change for every authentication request. This is this article's inference (Inference). The implications of specifying a particular principal within Cedar policies are discussed in Chapter 5 of this site's AWS Verified Permissions and Cedar Policy Language Complete Guide.

The format of the principal ID when using an Amazon Cognito user pool varies depending on the page. This is addressed in Section 10.1.

8.4 IAM Identity Center

IAM Identity Center has two paths related to sub.

The first is authentication through an external Identity Provider (IdP). The external IdP page states that the value of the NameID within the Subject of the SAML assertion must precisely match the username configured within IAM Identity Center. This path uses SAML and does not utilize the OIDC sub claim.

The second is through a trusted token issuer. The trusted token issuer page describes attribute mapping as follows:

Attribute mappings enable IAM Identity Center to match the user that is represented in a token issued by a trusted token issuer to a single user in IAM Identity Center.

This mechanism maps a single IAM Identity Center user based on a claim within an external OIDC token. No statement was found explicitly mentioning the use of sub for this mapping (No statement found). The trusted token issuer apps page lists Subject (sub) – The authenticated user. among the claims that the token must contain. This page also does not state that the mapping uses sub.

8.5 Amazon EKS

The EKS API page describes the configuration of the OIDC Identity Provider (IdP), specifically regarding the usernameClaim, as follows:

The default is sub, which is expected to be a unique identifier of the end user.

By default, the Kubernetes username is built from the value of sub (the EKS API page states that claims other than email are prefixed with the issuer URL). The EKS API page states that other claims, such as email or name, can also be selected. This article infers (Inference) that if using an ephemeral OP, the Kubernetes username will change for every authentication request by default.

9. Design Options That Do Not Use `sub` as the Primary Key

The options presented in this chapter are all this article's inferences (Inference) and are not recommendations found in AWS documentation or specifications. The choice of which option to adopt is ultimately up to the reader.

9.1 Mapping Another Claim and Identifying by It

In Amazon Cognito, the attribute mapping page tells you to map attributes that must match an external directory to attributes such as preferred_username (see Section 6.1). If the OP (OpenID Provider) provides a claim other than sub that does not change, mapping that claim and using it for identification is a potential option. However, an RP (Relying Party) that chose ephemeral requests that users not be linked. Using a persistent claim would contradict that purpose.

9.2 Linking with Claims Other Than `sub`

Amazon Cognito's AdminLinkProviderForUser allows you to link users using any claim mapped in OIDC (see Section 6.3). The limits are 5 users per profile and 5 claims per Identity Provider (IdP).

9.3 Not Fixing `sub` in the IAM Trust Policy

When the condition key <provider>:sub is not constrained, the trust policy will rely on other conditions, such as aud, to narrow the scope. With the aud condition alone, tokens issued by that OP to that client satisfy the condition for any user; this is this article's inference (Inference). In Section 11.4, both tokens passed for the /ephemeral-only role (Observation). The discussion of how to propagate user attributes downstream using sts:SourceIdentity is covered in Section 6.8 of AWS IAM Inbound Workload Federation on this site.

9.4 Choosing the Type on the RP Side

If your side is RP, you can select the type through the subject_type in Registration (see Section 3.4). However, no information was found indicating that Amazon Cognito User Pools or IAM register the subject_type with external IdPs (No statement found).

9.5 Summary Table

The following table lists the requirements and behavior described in this article, in the seven columns of Section 2.1.

Requirement or Behavior	Who Must Act (Spec)	AWS Receiver	What You Can Set	What You Cannot Set	Where It Is Written	Source State
MUST NOT reuse an `ephemeral` value	OP	—	—	—	ESID final text §4	Stated
Request `ephemeral`.	RP	Amazon Cognito user pool, IAM	—	Configuration to register `subject_type` with an external IdP: No statement found	ESID final text §6	Stated (Specification), No statement found (AWS)
The `sub` in an ID token returned by a refresh MUST be the same as the original	OP	ALB	—	—	Core §12.2	Stated (Core), No statement found (ESID final text)
Create a username from `sub`.	—	Amazon Cognito user pool	Mapping to `preferred_username`, etc.; `AdminLinkProviderForUser`	Setting to change the claim the username comes from: No statement found	Attribute mapping page, linking page	Stated (username), No statement found (setting)
Verify `public` during OIDC IdP registration.	—	IAM	—	Whether an OP that lists only `ephemeral` can be registered: No statement found	IAM create page	Stated (procedure), No statement found (whether it can be registered)
Match `sub` in the trust policy.	—	IAM	Condition key `<provider>:sub`, `aud`	—	Condition keys page	Stated
Identify the user using a signed header.	—	ALB	Verification of the signature in `x-amzn-oidc-data`	—	ALB authentication page	Stated
Create the principal ID from a claim.	—	Verified Permissions	`principalIdClaim`	—	Verified Permissions API page, `OpenIdConnectAccessTokenConfiguration` page	Stated
Create the username from a claim.	—	Amazon EKS	`usernameClaim`	—	EKS API page	Stated

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

10.1 Where the Sources Disagree

Verified Permissions, Amazon Cognito – Principal ID (Sources disagree): A security blog post states that Verified Permissions maps tokens issued by Amazon Cognito to the principal ID, formed by combining the pool ID and sub. A CloudFormation page states that it references users of the same identity source using a combination of the pool identifier and the client ID. A Verified Permissions API page lists a combination of the pool ID and the user principal attribute. A Verified Permissions user guide page states that the user identity in the token is mapped to the principal ID. This article does not definitively identify any of these as incorrect.
Section number for issue #21: Issue #21 cites a sentence as being in Section 4. However, the ESID final text identifies that same sentence as being in Section 1. This article will cite it as Section 1 in the ESID final text.

10.2 What the Documentation Does Not List

The list of claims that the API Gateway JWT authorizer evaluates does not include sub (Documentation does not list).

10.3 Items with No Statement Found

No statement found that AWS services (Amazon Cognito User Pools, IAM, AWS STS, ALB, API Gateway, Verified Permissions, IAM Identity Center, Amazon EKS) distinguish subject identifier types. The public on the IAM create page is the confirmation step described in Section 7.1. The terms searched for were ephemeral, pairwise, subject_types_supported, and subject type, using the pages from Section 1.3 and searching within aws-knowledge.
No statement found regarding whether it is possible to register an IAM OIDC Identity Provider (IdP) for an OP that lists only ephemeral. In the setup in Chapter 11, it could be created (Observation).
No statement found regarding the definition of authentication session.
No statement found regarding refresh and logout within the ESID final text.
No statement found regarding what "other means" in Section 6 of the ESID final text covers.
No statement found regarding whether Amazon Cognito allows modification of a user's original username within an inbound federation trigger.
No statement found regarding any statements that explicitly mention the sub claim within the trusted token issuer mapping in IAM Identity Center.

10.4 Important Notes When Reading

The absence of a description does not necessarily mean that a particular feature or functionality does not exist. In particular, avoid interpreting the instructions on the IAM create page regarding the public setting as a rejection of ephemeral OP configurations.
The identifiers for "pairwise" on the STS API page do not refer to ephemeral.
That Amazon Cognito creates a new profile with each sign-in is an inference based on two statements in the documentation. The observation in Chapter 11 is the result of a single configuration.
Issues #20 and #21 were open issues as of November 8, 2026, and do not represent finalized specifications.
This article does not investigate the status of support for major OPs. Do not assume that it indicates a lack of support.

11. What This Setup Showed

This chapter details the results obtained through the configuration described in Section 11.1. All findings presented here are observations (Observation) and are not commitments made by the documentation. Actual values for AWS account IDs, ARNs, hostnames, pool IDs, client IDs, usernames, and the sub field have been redacted.

11.1 Setup

In the us-east-1 region, a minimal OP was deployed, utilizing an AWS Lambda function URL. This OP serves for testing purposes, automatically approving a single, fixed test user and signing ID tokens with the RS256 algorithm. It features three issuers: /public, which returns a fixed sub value; /ephemeral, which returns a sub value consisting of a 256-bit random number for every authentication request; and /ephemeral-only, which returns the same kind of values as /ephemeral. The /ephemeral-only instance has subject_types_supported in its Discovery document set to ["ephemeral"] only. This instance is not intended to represent the process for creating production-ready OPs.

The Discovery document for /ephemeral lists ["public", "ephemeral"] in the subject_types_supported field.

An Amazon Cognito user pool (Lite) was configured to register both /public and /ephemeral as external OIDC Identity Providers (IdPs). The number of invocations was tracked within the Pre sign-up trigger. Sign-in was performed without using a browser, instead following the managed login redirect via script and stopping at the point where the callback received an authorization code.

An attempt was made to register three issuers as OIDC IdPs within IAM. Three roles were created, each without any associated permission policies. The trust policy conditions were configured as follows:

Role for /public: aud and sub set to the fixed value of /public.
Role for /ephemeral: aud and sub set to the value of the first ephemeral token.
Role for /ephemeral-only: aud only.

The experiment was conducted between 21:03 and 21:09 UTC on November 8, 2026, and the same procedure was run twice. During the second run, a sign-in was performed once via /public and twice via /ephemeral. CloudTrail logs were reviewed at 21:32 UTC.

11.2 Amazon Cognito User Pools

When signing in three times via /public, a single user was created. The username was EsidPublic_ followed by the fixed sub.

When signing in five times via /ephemeral, five users were created. Each of the five usernames consisted of EsidEphemeral_ followed by a different value. For each user, the userId within the identities section matched the value at the end of their username.

The pre sign-up trigger was invoked a total of six times: once via /public and five times via /ephemeral. In each instance, the triggerSource was PreSignUp_ExternalProvider.

These results align with the inference in Section 6.2 (that a new profile is created with each sign-in). Each user had an Amazon Cognito sub attribute.

11.3 Registering the IAM OIDC IdPs

All three issuers were successfully created as IAM OIDC IdPs. The Discovery document for /ephemeral-only lists only ["ephemeral"] under subject_types_supported and does not include public. There were no errors during the creation process.

11.4 AWS STS and Trust Policies

The result of using AWS STS's AssumeRoleWithWebIdentity was as follows:

Token	Role Condition	Result
Token for `/public` (2 times)	`sub` set to a fixed value of `/public`	Successful both times
First `ephemeral` token	`sub` set to the value of the first `ephemeral` token	Successful
Other `ephemeral` tokens (three tokens)	Same role	`AccessDenied` for all three; the message was `Not authorized to perform sts:AssumeRoleWithWebIdentity`
Tokens for `/ephemeral-only` (two tokens)	`aud` only	Successful both times

For all successful responses, the SubjectFromWebIdentityToken value matched the token's sub value. The length of the sub value was 20 characters for /public and 43 characters for ephemeral.

11.5 AWS CloudTrail

CloudTrail event history showed 8 records of AssumeRoleWithWebIdentity actions. Five were successful, while three resulted in AccessDenied errors. In all 8 records, the type in the userIdentity was WebIdentityUser, with the userName field containing the value of the token's sub. The principalId field contained a string formed by concatenating the OIDC IdP's ARN, aud, and sub with colons. In the 3 AccessDenied records, the requestParameters were null, and the ARN of the role was not included in the record.

11.6 Requests Received by the OP

The OP's logs showed that Amazon Cognito and AWS STS retrieved the Discovery document and JWKS. The User-Agent for Amazon Cognito was Amazon/Cognito, and for AWS STS, it was AWS Security Token Service. AWS STS also retrieved the Discovery document for /ephemeral-only. When the IAM OIDC IdP was created, there were no requests claiming to be IAM in the OP's logs.

11.7 What This Setup Does Not Show

Whether the AWS receivers read the value of subject_types_supported to make a determination. With this configuration, even if ephemeral is the only value listed, you can only confirm that creation and invocation were successful.
Results from different times, different regions, or different configurations.
How sub is handled during refresh and logout. This configuration does not test refresh tokens or logout.
Results from ALB, API Gateway, Verified Permissions, IAM Identity Center, and Amazon EKS. This configuration does not test these five services.
The behavior of a production OP. This OP is for testing purposes and automatically approves a single user.

12. Failure Modes

This chapter gathers failures that are likely, based on the source text in Chapters 3 through 8.

Assuming that the sub value remains constant: With Core's public and pairwise types, the sub value for the same RP remains the same. However, with ephemeral in the ESID final text, the value differs for every authentication request. The OP's Discovery document and the RP's registration (or other means) determine the type.
Concluding that the same value persists throughout the login session based solely on the text in §1: authentication session in §1 is not defined, and the ESID final text does not mention refresh.
Fixing the sub value of an ephemeral OP within the IAM trust policy to a single value: It can be inferred that this fixed value will not match the sub value of the next authentication request.
Separating Amazon Cognito usernames into the IdP name and sub and then using that sub to identify the user: With an ephemeral OP, the separated sub value will not match the value of the next sign-in.
Believing that all sessions for the same user can be identified using only a logout token containing the sub value: An ephemeral sub value differs for every authentication request, and the ESID final text does not address logout.
Identifying the user using the legacy x-amzn-oidc-identity header in ALB: This header does not contain a signature. The ALB authentication page states that the x-amzn-oidc-data header, which has been validated for signatures, should be used to obtain the sub value.
Interpreting the text describing the public procedure in the IAM create page as a description of how to reject an ephemeral OP: The text describes a procedure, not a rejection.
Reading the description of the STS pairwise identifier as a description of ephemeral: The description is an explanation of pairwise, with the qualifier "typically."

13. Frequently Asked Questions About Ephemeral Subject Identifiers and AWS Receivers

This chapter answers the reader assumptions in Section 1.1 with the text in Chapters 3 through 10.

Q1. Does an `ephemeral` `sub` always change with each login?

The ESID final text, Section 4, states that the sub value is different for every authentication request. Section 1 indicates that the value remains constant for the duration of the authentication session. There is no definition for authentication session, and the ESID final text does not address the sub value of the ID token returned by a refresh. Core, Section 12.2, states that the sub value of the ID token returned by a refresh must be the same as the original value (MUST) (Chapter 4).

Q2. Can IAM not register an OP that lists only `ephemeral`?

The IAM create page instructs you to verify the presence of subject_types_supported: public in the Discovery document. There is no mention of rejecting registration (Section 7.1). In the setup in Chapter 11, an OP that lists only ephemeral could be created, and calls to AWS STS using the tokens from that OP also succeeded. This is an observation (Observation) from one setup and is not a commitment made by the documentation.

Q3. Does Amazon Cognito create a new user every time someone signs in?

The Amazon Cognito documentation states that usernames are created from the sub identifier, and that a new profile is created if no linked profile exists. The assertion that a new profile is created with each sign-in with an ephemeral OP is an inference drawn from these two statements (Section 6.2). In the setup in Chapter 11, signing in five times with an ephemeral OP created five distinct users (Observation).

Q4. What is the difference between `pairwise` and `ephemeral`?

pairwise refers to different values for each RP, but returns the same value for the same RP. The calculation must be deterministic (MUST). ephemeral refers to different values for every authentication request, even for the same RP, and the OP must not reuse these values (MUST NOT) (see Chapter 3).

Q5. Does the pairwise identifier in the AWS STS description refer to `ephemeral`?

No. The STS API page describes SubjectFromWebIdentityToken as "typically" a pairwise identifier. This description matches the Core's "pairwise," and the page does not mention "ephemeral" (Section 7.3).

Q6. Which header does the application behind the ALB use to identify the user?

The ALB authentication page instructs you to verify the signature of the x-amzn-oidc-data header and extract the sub claim from the validated JWT. The x-amzn-oidc-identity header is provided for backward compatibility and does not include a signature (see Section 8.1). If the OpenID Provider (OP) is ephemeral, the sub claim itself will change for every authentication request.

Q7. Do the major OPs support `ephemeral`?

This article does not investigate the support status of major OPs. Section 1 of the ESID final text states that ephemeral is already used in some ecosystems, but it does not specify which ecosystems.

Q8. Should you use `ephemeral`?

This article does not make a judgment. Rather, it outlines what can be determined from AWS documentation when an ephemeral OP is placed in front of AWS receivers, and what is not settled (Chapters 5 and 10).

14. Summary

Before placing an ephemeral OP in front of the AWS receivers that use sub as the user's key, ensure the following:

Verify the subject_types_supported in the Discovery document of the integrated OP and the subject_type registered on your RP.
Understand that the sub for ephemeral is different for every authentication request (Section 4), and that authentication session (Section 1) is not defined.
Be aware that the ESID final text does not specify how sub is handled during refresh and logout.
Identify all locations where sub is used as a key, including Amazon Cognito usernames, the IAM condition key <provider>:sub, Verified Permissions principal IDs, and the usernameClaim in Amazon EKS.
Confirm that the wording on the IAM create page regarding the public confirmation step is not interpreted as a rejection message.
Ensure that sub is extracted from the signed x-amzn-oidc-data behind the ALB.
Consider whether alternative claims, other than sub, for identification align with the intended purpose of using ephemeral.
Document any items for which descriptions were not found, along with the search terms, pages, and dates.

15. References

References:
Tech Blog with curated related content

Written by Hidekazu Konishi