Using applications with a trusted token issuer
Trusted token issuers enable you to use trusted identity propagation with applications that authenticate outside of AWS. With trusted token issuers, you can authorize these applications to make requests on behalf of their users to access AWS managed applications.
The following topics describe how trusted token issuers work and provide setup guidance.
Topics
Trusted token issuer overview
Trusted identity propagation provides a mechanism that enables applications that authenticate outside of AWS to make requests on behalf of their users with the use of a trusted token issuer. A trusted token issuer is an OAuth 2.0 authorization server that creates signed tokens. These tokens authorize applications that initiate requests (requesting applications) for access to AWS services (receiving applications). Requesting applications initiate access requests on behalf of users that the trusted token issuer authenticates. The users are known to both the trusted token issuer and IAM Identity Center.
AWS services that receive requests manage fine-grained authorization to their resources based on their users and group membership as represented in the Identity Center directory. AWS services can't use the tokens from the external token issuer directly.
To solve this, IAM Identity Center provides a way for the requesting application, or an AWS driver that the requesting application uses, to exchange the token issued by the trusted token issuer for a token that is generated by IAM Identity Center. The token that is generated by IAM Identity Center refers to the corresponding IAM Identity Center user. The requesting application, or the driver, uses the new token to initiate a request to the receiving application. Because the new token references the corresponding user in IAM Identity Center, the receiving application can authorize the requested access based on the user or their group membership as represented in IAM Identity Center.
Important
Choosing an OAuth 2.0 authorization server to add as a trusted token issuer is a security decision that requires careful consideration. Only choose trusted token issuers that you trust to perform the following tasks:
-
Authenticate the user who is specified in the token.
-
Authorize that user’s access to the receiving application.
-
Generate a token that IAM Identity Center can exchange for an IAM Identity Center created token.
Prerequisites and considerations for trusted token issuers
Before you set up a trusted token issuer, review the following prerequisites and considerations.
-
Trusted token issuer configuration
You must configure an OAuth 2.0 authorization server (the trusted token issuer). Although the trusted token issuer is typically the identity provider that you use as your identity source for IAM Identity Center, it doesn’t have to be. For information about how to set up the trusted token issuer, see the documentation for the relevant identity provider.
Note
You can configure up to 10 trusted token issuers for use with IAM Identity Center, as long you map the identity of each user in the trusted token issuer to a corresponding user in IAM Identity Center.
-
The OAuth 2.0 authorization server (the trusted token issuer) that creates the token must have an OpenID Connect (OIDC)
discovery endpoint that IAM Identity Center can use to obtain public keys to verify the token signatures. For more information, see OIDC discovery endpoint URL (issuer URL). -
Tokens issued by the trusted token issuer
Tokens from the trusted token issuer must meet the following requirements:
-
The token must be signed and in JSON Web Token (JWT)
format using the RS256 algorithm. -
The token must contain the following claims:
-
Issuer
(iss) – The entity that issued the token. This value must match the value that is configured in the OIDC discovery endpoint (issuer URL) in the trusted token issuer. -
Subject
(sub) – The authenticated user. -
Audience
(aud) – The intended recipient of the token. This is the AWS service that will be accessed after the token is exchanged for a token from IAM Identity Center. For more information, see Aud claim. -
Expiration Time
(exp) – The time after which the token expires.
-
-
The token can be an identity token or an access token.
-
The token must have an attribute that can be mapped uniquely to one IAM Identity Center user.
Note
Using a custom signing key for JWTs from Microsoft Entra ID is not supported. In order to use tokens from Microsoft Entra ID with trusted token issuer, you can't use a custom signing key.
-
-
Optional claims
IAM Identity Center supports all optional claims that are defined in RFC 7523. For more information, see Section 3: JWT Format and Processing Requirements
of this RFC. For example, the token can contain a JTI (JWT ID) claim
. This claim, when present, prevents tokens that have the same JTI from being reused for token exchanges. For more information about JTI claims, see JTI claim details. -
IAM Identity Center configuration to work with a trusted token issuer
You must also enable IAM Identity Center, configure the identity source for IAM Identity Center, and provision users that correspond to the users in the trusted token issuer’s directory.
To do this, you must do either of the following:
-
Synchronize users into IAM Identity Center by using the System for Cross-domain Identity Management (SCIM) 2.0 protocol.
-
Create the users directly in IAM Identity Center.
Note
Trusted token issuers aren't supported if you use Active Directory Domain Service as your identity source.
-
JTI claim details
If IAM Identity Center receives a request to exchange a token that IAM Identity Center has already exchanged, the request fails. To detect and prevent reuse of a token for token exchanges, you can include a JTI claim. IAM Identity Center protects against the replay of tokens based on the claims in the token.
Not all OAuth 2.0 authorization servers add a JTI claim to tokens. Some OAuth 2.0 authorization servers might not allow you to add a JTI as a custom claim. OAuth 2.0 authorization servers that support the use of a JTI claim might add this claim to identity tokens only, access tokens only, or both. For more information, see the documentation for your OAuth 2.0 authorization server.
For information about building applications that exchange tokens, see the IAM Identity Center API documentation. For information about configuring a customer managed application to obtain and exchange the correct tokens, see the documentation for the application.
