Identity provider and relying party endpoints - Amazon Cognito
OIDC issuer
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Identity provider and relying party endpoints

Federation endpoints are user pool endpoints that serve a purpose for one of the authentication standards used by user pools. They include SAML ACS URLs, OIDC discovery endpoints, and service endpoints for user pool roles both as identity provider and relying party. Federation endpoints initiate authentication flows, receive proof of authentication from IdPs, and issue tokens to clients. They interact with IdPs, applications, and administrators, but not with users.

The full-page topics after this page have details about the OAuth 2.0 and OIDC provider endpoints that become available when you add a domain to your user pool. The following chart is a list of all federation endpoints.

Examples of user pool domains are:

  1. Prefix domain: mydomain.auth.us-east-1.amazoncognito.com

  2. Custom domain: auth.example.com

User pool federation endpoints
Endpoint URL Description How it's accessed
https://Your user pool domain/oauth2/authorize Redirects a user to either managed login or to sign in with their IdP. Invoked in customer browser to begin user authentication. See Authorize endpoint.
https://Your user pool domain/oauth2/token Returns tokens based on an authorization code or client credentials request. Requested by app to retrieve tokens. See Token endpoint.
https://Your user pool domain/oauth2/userInfo Returns user attributes based on OAuth 2.0 scopes and user identity in an access token. Requested by app to retrieve user profile. See userInfo endpoint.
https://Your user pool domain/oauth2/revoke Revokes a refresh token and the associated access tokens. Requested by app to revoke a token. See Revoke endpoint.
https://cognito-idp.Region.amazonaws.com/your user pool ID/.well-known/openid-configuration A directory of the OIDC architecture of your user pool.1 Requested by app to locate user pool issuer metadata.
https://cognito-idp.Region.amazonaws.com/your user pool ID/.well-known/jwks.json Public keys that you can use to validate Amazon Cognito tokens.2 Requested by app to verify JWTs.
https://Your user pool domain/oauth2/idpresponse Social identity providers must redirect your users to this endpoint with an authorization code. Amazon Cognito redeems the code for a token when it authenticates your federated user. Redirected from OIDC IdP sign-in as the IdP client callback URL.
https://Your user pool domain/saml2/idpresponse The Assertion Consumer Response (ACS) URL for integration with SAML 2.0 identity providers. Redirected from SAML 2.0 IdP as the ACS URL, or the origination point for IdP-initiated sign-in3.
https://Your user pool domain/saml2/logout The Single Logout (SLO) URL for integration with SAML 2.0 identity providers. Redirected from SAML 2.0 IdP as the single logout (SLO) URL. Accepts POST binding only.

1 The openid-configuration document might be updated at any time with additional information that keeps the endpoint compliant with the OIDC and OAuth2 specifications.

2The jwks.json JSON file might be updated at any time to with new public token signing keys.

3 For more information about IdP-initiated SAML sign-in, see Implement IdP-initiated SAML sign-in.

For more information on the OpenID Connect and OAuth standards, see OpenID Connect 1.0 and OAuth 2.0.

Amazon Cognito user pools as an OIDC issuer

Amazon Cognito user pools function as OpenID Connect (OIDC) identity providers, serving as an issuer that application libraries can use for OIDC federation. Application libraries for OIDC federation can reference the two different paths as discussed below as an autodiscovery endpoint. This endpoint provides access to the JSON Web Key Set (JWKS) at /.well-known/jwks.json and OIDC discovery metadata at /.well-known/openid-configuration, where applications can discover the authorization, token, and userInfo endpoints.

Applications that support OIDC autodiscovery can automatically configure themselves by querying these well-known endpoints. For applications that don't support autodiscovery, you can hardcode your application with the specific OIDC endpoints that are listed in the previous section.

User pool issuer types
Original issuer

The current default issuer configuration for user pools. The issuer URL is hosted in the user pool's Region and provides OIDC endpoints specific to that Region.

Original issuers take the format https://cognito-idp.eusc-de-east-1.amazonaws.com/eusc-de-east-1_EXAMPLE.

Updated issuer

Recommended for all user pools, including for multi-Region replication. Updated issuers host the same JWKS content in multiple Regions, resulting in improved resilience and efficiency.

Updated issuers take the format https://issuer-cognito-idp.eusc-de-east-1.amazonaws.com/eusc-de-east-1_EXAMPLE, where Region is the primary AWS Region of your user pool.

Note

The updated issuer type is not currently compatible with Application Load Balancer authentication with Amazon Cognito (Authenticate users using an Application Load Balancer) or Amazon API Gateway Amazon Cognito authorizers (Control access to REST APIs using Amazon Cognito user pools as authorizer).

Prepare for changes to the discovery document

The openid-configuration document is a standard OpenID Connect discovery document. Amazon Cognito can add metadata entries to it over time to keep it compliant with the OpenID Connect and OAuth 2.0 specifications and to improve compatibility with OIDC client libraries. These additions are backward compatible: Amazon Cognito adds new members, but it does not rename, change the type of, or remove the members that your application already reads. Write your client so that it keeps working as the document grows.

Ignore members that you don't recognize

As the OpenID Connect Discovery specification requires, treat metadata members that you don't understand as optional. Don't reject, fail, or throw an error when the document contains a member that your application doesn't use.

Don't hard-code the set or order of members

Parse the document as a general JSON object rather than a fixed structure. The members can appear in any order, and the set of members can change between requests and over time. Address each member by name, and read each one as the type that the specification defines for it.

Test strict clients against the current document

If your client validates the discovery document strictly, fetch the current document from your user pool's /.well-known/openid-configuration endpoint and confirm that your client accepts it before you depend on a specific set of members.

Amazon Cognito tokens follow the same additive, forward-compatible approach. For more information about parsing the claims in an ID or access token, see Parse user pool tokens safely.

Topics