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.

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.

• 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.

Trusted token issuer configuration settings

The following sections describe the settings required to set up and use a trusted token issuer.

Topics

• OIDC discovery endpoint URL (issuer URL)
• Attribute mapping
• Aud claim

OIDC discovery endpoint URL (issuer URL)

When you add a trusted token issuer to the IAM Identity Center console, you must specify the OIDC discovery endpoint URL. This URL is commonly referred to by its relative URL, /.well-known/openid-configuration. In the IAM Identity Center console, this URL is called the issuer URL.

Note

You must paste the URL of the discovery endpoint up until and without .well-known/openid-configuration. If .well-known/openid-configuration is included in the URL, the trusted token issuer configuration won't work. Because IAM Identity Center doesn't validate this URL, if the URL isn't correctly formed, the trusted token issuer setup will fail without notification.

IAM Identity Center uses this URL to obtain additional information about the trusted token issuer. For example, IAM Identity Center uses this URL to obtain the information required to verify the tokens that the trusted token issuer generates. When you add a trusted token issuer to IAM Identity Center, you must specify this URL. To find the URL, see the documentation for the OAuth 2.0 authorization server provider that you use to generate tokens for your application, or contact the provider directly for assistance.

Attribute mapping

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. You must specify the attribute mapping when you add the trusted token issuer to IAM Identity Center. This attribute mapping is used in a claim in the token that is generated by the trusted token issuer. The value in the claim is used to search IAM Identity Center. The search uses the specified attribute to retrieve a single user in IAM Identity Center, who will be used as the user within AWS. The claim that you choose must be mapped to one attribute in a fixed list of available attributes in the IAM Identity Center identity store. You can choose one of the following IAM Identity Center identity store attributes: user name, email, and external ID. The value for the attribute that you specify in IAM Identity Center must be unique for each user.

Aud claim

An aud claim identifies the audience (recipients) for which a token is intended. When the application requesting access authenticates through an identity provider that is not federated to IAM Identity Center, that identity provider must be set up as a trusted token issuer. The application that receives the access request (the receiving application) must exchange the token that is generated by the trusted token issuer for a token that is generated by IAM Identity Center.

For information about how to obtain the aud claim values for the receiving application as they are registered in the trusted token issuer, see the documentation for your trusted token issuer or contact the trusted token issuer administrator for assistance.

Setting up a trusted token issuer

To enable trusted identity propagation for an application that authenticates externally to IAM Identity Center, one or more administrators must set up a trusted token issuer. A trusted token issuer is an OAuth 2.0 authorization server that issues tokens to applications that initiate requests (requesting applications). The tokens authorize these applications to initiate requests on behalf of their users to a receiving application (an AWS service).

Topics

• Coordinating administrative roles and responsibilities
• Tasks for setting up a trusted token issuer
• How to add a trusted token issuer to the IAM Identity Center console
• How to view or edit trusted token issuer settings in the IAM Identity Center console
• Setup process and request flow for applications that use a trusted token issuer

Coordinating administrative roles and responsibilities

In some cases, a single administrator might perform all of the necessary tasks for setting up a trusted token issuer. If multiple administrators perform these tasks, close coordination is required. The following table describes how multiple administrators might coordinate to set up a trusted token issuer and configure AWS service to use it.

Note

The application can be any AWS service that is integrated with IAM Identity Center and supports trusted identity propagation.

For more information, see Tasks for setting up a trusted token issuer.

Role	Performs these tasks	Coordinates with
IAM Identity Center administrator	Adds the external IdP as a trusted token issuer to the IAM Identity Center console. Helps set up the correct attribute mapping between IAM Identity Center and the external IdP. Notifies the AWS service administrator when the trusted token issuer is added to the IAM Identity Center console.	External IdP (trusted token issuer) administrator AWS service administrator
External IdP (trusted token issuer) administrator	Configures the external IdP to issue tokens. Helps set up the correct attribute mapping between IAM Identity Center and the external IdP. Provides the audience name (Aud claim) to the AWS service administrator.	IAM Identity Center administrator AWS service administrator
AWS service administrator	Checks the AWS service console for the trusted token issuer. The trusted token issuer will be visible in the AWS service console after the IAM Identity Center administrator adds it to the IAM Identity Center console. Configures the AWS service to use the trusted token issuer.	IAM Identity Center administrator External IdP (trusted token issuer) administrator

Tasks for setting up a trusted token issuer

To set up a trusted token issuer, an IAM Identity Center administrator, external IdP (trusted token issuer) administrator, and application administrator must complete the following tasks.

Note

The application can be any AWS service that is integrated with IAM Identity Center and supports trusted identity propagation.

1. Add the trusted token issuer to IAM Identity Center – The IAM Identity Center administrator adds the trusted token issuer by using the IAM Identity Center console or APIs. This configuration requires specifying the following:

   • A name for the trusted token issuer

   • The OIDC discovery endpoint URL (in the IAM Identity Center console, this URL is called the issuer URL).

   • Attribute mapping for user lookup. This attribute mapping is used in a claim in the token that is generated by the trusted token issuer. The value in the claim is used to search IAM Identity Center. The search uses the specified attribute to retrieve a single user in IAM Identity Center.

2. Connect the AWS service to IAM Identity Center – The AWS service administrator must connect the application to IAM Identity Center by using the console for the application or the application APIs.

   After the trusted token issuer is added to the IAM Identity Center console, it is also visible in the AWS service console and available for the AWS service administrator to select.

3. Configure the use of token exchange – In the AWS service console, the AWS service administrator configures AWS service to accept tokens issued by the trusted token issuer. These tokens are exchanged for tokens generated by IAM Identity Center. This requires specifying the name of the trusted token issuer from Step 1, and the Aud claim value that corresponds to the AWS service.

   The trusted token issuer places the Aud claim value in the token it issues to indicate that the token is intended for use by the AWS service. To obtain this value, contact the administrator for the trusted token issuer.

How to add a trusted token issuer to the IAM Identity Center console

In an organization that has multiple administrators, this task is performed by an IAM Identity Center administrator. If you are the IAM Identity Center administrator, you must choose which external IdP to use as a trusted token issuer.

To add a trusted token issuer to the IAM Identity Center console

1. Open the IAM Identity Center console.

2. Choose Settings.

3. On the Settings page, choose the Authentication tab.

4. Under Trusted token issuers, choose Create trusted token issuer.

5. On the Set up an external IdP to issue trusted tokens page, under Trusted token issuer details, do the following:

   • For Issuer URL, specify the OIDC discovery URL of the external IdP that will issue tokens for trusted identity propagation. You must specify the URL of the discovery endpoint up until and without .well-known/openid-configuration. The administrator of the external IdP can provide this URL.

     Note

     Note This URL must match the URL in the Issuer (iss) claim in tokens that are issued for trusted identity propagation.

   • For Trusted token issuer name, enter a name to identify this trusted token issuer in IAM Identity Center and in the application console.

6. Under Map attributes, do the following:

   • For Identity provider attribute, select an attribute from the list to map to an attribute in the IAM Identity Center identity store.

   • For IAM Identity Center attribute, select the corresponding attribute for the attribute mapping.

7. Under Tags (optional), choose Add new tag, specify a value for Key, and optionally for Value.

   For information about tags, see Tagging AWS IAM Identity Center resources.

8. Choose Create trusted token issuer.

9. After you finish creating the trusted token issuer, contact the application administrator to let them know the name of the trusted token issuer, so that they can confirm that the trusted token issuer is visible in the applicable console.

10. The application administrator must select this trusted token issuer in the applicable console to enable user access to the application from applications that are configured for trusted identity propagation.

How to view or edit trusted token issuer settings in the IAM Identity Center console

After you add a trusted token issuer to the IAM Identity Center console, you can view and edit the relevant settings.

If you plan to edit the trusted token issuer settings, keep in mind that doing so might cause users to lose access to any applications that are configured to use the trusted token issuer. To avoid disrupting user access, we recommend that you coordinate with the administrators for any applications that are configured to use the trusted token issuer before you edit settings.

To view or edit trusted token issuer settings in the IAM Identity Center console

1. Open the IAM Identity Center console.

2. Choose Settings.

3. On the Settings page, choose the Authentication tab.

4. Under Trusted token issuers, select the trusted token issuer that you want to view or edit.

5. Choose Actions, and then choose Edit.

6. On the Edit trusted token issuer page, view or edit settings as needed. You can edit the trusted token issuer name, attribute mappings, and tags.

7. Choose Save changes.

8. In the Edit trusted token issuer dialog box, you're prompted to confirm that you want to make changes. Choose Confirm.

Setup process and request flow for applications that use a trusted token issuer

This section describes the setup process and request flow for applications that use a trusted token issuer for trusted identity propagation. The following diagram provides an overview of this process.

The following steps provide additional information about this process.

1. Set up IAM Identity Center and the receiving AWS managed application to use a trusted token issuer. For information, see Tasks for setting up a trusted token issuer.

2. The request flow begins when a user opens the requesting application.

3. The requesting application requests a token from the trusted token issuer to initiate requests to the receiving AWS managed application. If the user hasn't authenticated yet, this process triggers an authentication flow. The token contains the following information:

   • The subject (Sub) of the user.

   • The attribute that IAM Identity Center uses to look up the corresponding user in IAM Identity Center.

   • An audience (Aud) claim that contains a value that the trusted token issuer associates with the receiving AWS managed application. If other claims are present, they aren't used by IAM Identity Center.

4. The requesting application, or the AWS driver that it uses, passes the token to IAM Identity Center and requests that the token be exchanged for a token that is generated by IAM Identity Center. If you use an AWS driver, you might need to configure the driver for this use case. For more information, see the documentation for the relevant AWS managed application.

5. IAM Identity Center uses the OIDC Discovery endpoint to obtain the public key that it can use to verify the authenticity of the token. IAM Identity Center then does the following:

   • Verifies the token.

   • Searches the Identity Center directory. To do this, IAM Identity Center uses the mapped attribute specified in the token.

   • Verifies that the user is authorized to access the receiving application. If the AWS managed application is configured to require assignments to users and groups, the user must have a direct or group-based assignment to the application; otherwise the request is denied. If the AWS managed application is configured to not require user and group assignments, processing continues.

     Note

     AWS services have a default setting configuration that determines whether assignments are required for users and groups. We recommend that you do not modify the Require assignments setting for these applications if you plan to use them with trusted identity propagation. Even if you have configured fine-grained permissions that allow user access to specific application resources, modifying the Require assignments setting might result in unexpected behavior, including disrupted user access to these resources.

   • Verifies that the requesting application is configured to use valid scopes for the receiving AWS managed application.

6. If the previous verification steps are successful, IAM Identity Center creates a new token. The new token is an opaque (encrypted) token that includes the identity of the corresponding user in IAM Identity Center, the audience (Aud) of the receiving AWS managed application, and the scopes that the requesting application can use when making requests to the receiving AWS managed application.

7. The requesting application, or the driver that it uses, initiates a resource request to the receiving application and passes the token that IAM Identity Center generated to the receiving application.

8. The receiving application makes calls to IAM Identity Center to obtain the identity of the user and the scopes that are encoded in the token. It might also make requests to obtain user attributes or the user’s group memberships from the Identity Center directory.

9. The receiving application uses its authorization configuration to determine if the user is authorized to access the requested application resource.

10. If the user is authorized to access the requested application resource, the receiving application responds to the request.

11. The user's identity, actions performed on their behalf, and other events recorded in the receiving application logs and CloudTrail events. The specific way in which this information is logged varies based on the application.