Using trusted identity propagation with Amazon managed applications - Amazon IAM Identity Center
SetupRequest flowsAfter an application obtains a tokenIdentity-enhanced IAM role sessionsTypes of identity-enhanced IAM role sessionsSetup process and request flow
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using trusted identity propagation with Amazon managed applications

Trusted identity propagation enables an Amazon managed application to request access to data in Amazon services on behalf of a user. Data access management is based on a user’s identity, so administrators can grant access based on users' existing user and group memberships. The user's identity, actions performed on their behalf, and other events are recorded in service-specific logs and CloudTrail events.

Trusted identity propagation is based on the OAuth 2.0 standard. To use this capability, Amazon managed applications must integrate with IAM Identity Center. Amazon analytics services might provide driver-based interfaces that enable a compatible application to use trusted identity propagation. For example, JDBC, ODBC, and Python drivers enable compatible query tools to use trusted identity propagation without the need for you to complete additional setup steps.

Set up Amazon managed applications for trusted identity propagation

Amazon services that support trusted identity propagation provide an administrative user interface and APIs that you can use to set up this capability. No configuration is required within IAM Identity Center for these services.

Following is the high-level process for setting up an Amazon service for trusted identity propagation. The specific steps vary depending on the administrative interface and APIs provided by the application.

  1. Use the application console or APIs to connect the application to your instance of IAM Identity Center

    Use the console for the Amazon managed application or the application APIs to connect the application to your instance of IAM Identity Center. When you use the console for the application, the administrative user interface includes a widget that streamlines the setup and connection process.

  2. Use the application console or APIs to set up user access to the application’s resources

    Complete this step to authorize which resources, or data, a user can access. Access is based on the user’s identity or group membership. The authorization model varies based on the application.

    Important

    You must complete this step to enable users to access the Amazon service's resources. Otherwise, users can't access resources, even if the requesting application is authorized to request access to the service.

Trusted identity propagation request flows for Amazon managed applications

All trusted identity propagation flows to Amazon managed applications must begin with an application that obtains a token from IAM Identity Center. This token is required because it contains a reference to a user that is known to IAM Identity Center and applications that are registered with IAM Identity Center.

The following sections describe the ways in which an Amazon managed application can obtain a token from IAM Identity Center to initiate trusted identity propagation.

Web-based, IAM Identity Center authentication

For this flow, the Amazon managed application provides a web-based single sign-on experience using IAM Identity Center for authentication.

When a user opens an Amazon managed application, a single sign-on flow that uses IAM Identity Center is triggered. If there isn't an active session for the user in IAM Identity Center, the user is presented with a sign-in page based on the identity source that you have specified, and IAM Identity Center creates a session for the user.

IAM Identity Center provides the Amazon managed application with a token that includes the user’s identity and a list of audiences (Auds) and related scopes that the application is registered to use. The application can then use the token to make requests to other receiving Amazon services.

Console-based, user-initiated authentication requests

For this flow, the Amazon managed application provides a console experience that users initiate.

In this case, the Amazon managed application is entered from the Amazon Management Console after assuming a role. For the application to obtain a token, the user must initiate a process to trigger the application to authenticate the user. This initiates authentication using IAM Identity Center, which will redirect the user to the identity source that you have configured.

After an application obtains a token

After a requesting application obtains a token from IAM Identity Center, the application periodically refreshes the token, which can be used for the life of the user’s session. During this time, the application might:

  • Obtain more information about the token to determine who the user is and which scopes the application can use with other receiving Amazon managed applications.

  • Pass the token in calls to other receiving Amazon managed applications that support the use of tokens.

  • Obtain identity-enhanced IAM role sessions that it can use to make requests to other Amazon managed applications that use Amazon Signature Version 4.

    An identity-enhanced IAM role session is an IAM role session that contains the user's propagated identity stored in a token that is created by IAM Identity Center.

Identity-enhanced IAM role sessions

The Amazon Security Token Service enables an application to obtain an identity-enhanced IAM role session. Amazon managed applications that support the user context in a role session can use the identity information to authorize access based on the user that is in the role session. This new context enables applications to make requests to Amazon managed applications that support trusted identity propagation through Amazon Signature Version 4 API requests.

When an Amazon managed application uses an identity-enhanced IAM role session to access a resource, CloudTrail logs the user’s identity (user-ID), the initiating session, and the action taken.

When an application makes a request using an identity-enhanced IAM role session to a receiving application, it adds context to the session so that the receiving application can authorize access based on the user's identity or group membership, or the IAM role. Receiving applications that support trusted identity propagation will return an error if the receiving application or the requested resource is not configured to authorize access based on the user's identity or group memberships.

To avoid this issue, do either of the following:

  • Verify that the receiving application is connected to IAM Identity Center.

  • Use the console for the receiving application or the application APIs to set up the application to authorize access to resources based on the user's identity or group memberships. The setup requirements for this vary based on the application.

For more information, see the documentation for the receiving Amazon managed application.

Types of identity-enhanced IAM role sessions

An application obtains an identity-enhanced IAM role session by making a request to the Amazon STS AssumeRole API and passing a context assertion in the ProvidedContexts parameter of the AssumeRole request. The context assertion is obtained from the idToken claim that is available in the response from the SSO OIDC CreateTokenWithIAM request.

Amazon STS can create two different types of identity-enhanced IAM role sessions, depending on the context assertion provided to the AssumeRole request:

  • Sessions that only log the user's identity to CloudTrail.

  • Sessions that enable authorization based on the propagated user identity and log it to CloudTrail.

To obtain an identity-enhanced IAM role session from Amazon STS that only provides auditing information that is registered in a CloudTrail trail, provide the value of the sts:audit_context claim to the AssumeRole request. To obtain a session that also allows the receiving Amazon service to authorize the IAM Identity Center user to perform an action, provide the value of the sts:identity_context claim to the AssumeRole request. You can only provide one context.

Identity-enhanced IAM role sessions created with sts:audit_context

When a request is made to an Amazon service using an identity-enhanced IAM role session that is created with sts:audit_context, the user's IAM Identity Center userId is logged to CloudTrail in the OnBehalfOf element.

"userIdentity": {
      "type": "AssumedRole",
      "principalId": "AROAEXAMPLE:MyRole",
      "arn": "arn:aws:sts::111111111111:assumed-role/MyRole/MySession",
      "accountId": "111111111111",
      "accessKeyId": "ASIAEXAMPLE",
      "sessionContext": {
        "sessionIssuer": {
            "type": "Role",
            "principalId": "AROAEXAMPLE",
            "arn": "arn:aws:iam::111111111111:role/MyRole",
            "accountId": "111111111111",
            "userName": "MyRole"
        },
        "attributes": {
            "creationDate": "2023-12-12T13:55:22Z",
            "mfaAuthenticated": "false"
        }
    },
    "onBehalfOf": {
        "userId": "11111111-1111-1111-1111-1111111111",
        "identityStoreArn": "arn:aws:identitystore::111111111111:identitystore/d-111111111"
    }
}
Note

These sessions can't be used for authorizing the Identity Center user. They can still be used to authorize the IAM role.

To obtain this type of role session from Amazon STS, provide the value of the sts:audit_context field to the AssumeRole request in the ProvidedContexts request parameter. Use arn:aws:iam::aws:contextProvider/IdentityStore as the value for ProviderArn.

Identity-enhanced IAM role sessions created with sts:identity_context

When a user makes a request to an Amazon service using an identity-enhanced IAM role session that is created with sts:identity_context, the user's IAM Identity Center userId is logged to CloudTrail in the onBehalfOf element in the same way as a session that is created with sts:audit_context.

In addition to logging the IAM Identity Center user's userId to CloudTrail, this type of session is also used by supported APIs to authorize actions based on the propagated user identity. For a list of IAM actions for the supported APIs, see the AWSIAMIdentityCenterAllowListForIdentityContext Amazon managed policy. This Amazon managed policy is supplied as a session policy when an identity-enhanced IAM role session is created with sts:identity_context. The policy prevents you from using the role session with unsupported Amazon services.

To obtain this type of role session from Amazon STS, provide the value of the sts:identity_context field to the AssumeRole request in the ProvidedContexts request parameter. Use arn:aws:iam::aws:contextProvider/IdentityStore as the value for ProviderArn.

Setup process and request flow for Amazon managed applications

This section describes the setup process and request flow for Amazon managed applications that use trusted identity propagation and that provide a web-based single sign-on experience.

The following diagram provides an overview of this process.

Setup process and request flows for Amazon managed applications that use trusted identity propagation

The following steps provide additional information about this process.

  1. Use the console for the Amazon managed application or the application APIs to do the following:

    1. Connect the application to your instance of IAM Identity Center.

    2. Set up permissions to authorize which application resources a user can access.

  2. The request flow begins when a user opens an Amazon managed application that can request access to resources (a requesting application).

  3. To obtain a token to access the receiving Amazon managed application, the requesting Amazon managed application initiates a sign-in request to IAM Identity Center.

    If the user isn't signed in, IAM Identity Center triggers a user authentication flow to the identity source that you have specified. This creates a new Amazon Web Services access portal session for the user with the duration that you configured in IAM Identity Center. IAM Identity Center then generates a token that is associated with the session, and the application can operate for the remaining duration of the user's Amazon Web Services access portal session. If the user signs out of their application, or if you delete their session, the session automatically ends within two hours.

  4. The Amazon managed application initiates a request to the receiving application and provides its token.

  5. 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. The receiving application might also make requests to obtain user attributes or the user’s group memberships from the Identity Center directory.

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

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

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