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 sessionsIdentity-enhanced IAM role session loggingSetup 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 Amazon managed application or a customer managed application to obtain an identity-enhanced IAM role session. The application can use this identity-enhanced role session when making requests to an Amazon managed application. These identity-enhanced role sessions have an added identity context that the requested Amazon managed application can use to authorize access.

An application obtains an identity-enhanced role session by making a request to the Amazon STS AssumeRole API action 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. This context adds the userId of the IAM Identity Center user to the identity-enhanced role session context.

When an Amazon managed application uses an identity-enhanced role session to access a resource, CloudTrail logs the user’s identity (userId), the initiating session, and the action taken. For more information, see Identity-enhanced IAM role session logging.

Types of identity-enhanced IAM role sessions

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

  • Amazon managed applications that receive a role session with sts:audit_context only log the user's identity (userId) to CloudTrail.

  • Amazon managed applications that receive a role session with sts:identity_context can authorize access based on the propagated user identity and logs the userId to CloudTrail.

An identity-enhanced role session can have only one of these context assertions, not both.

Identity-enhanced IAM role sessions created with sts:audit_context

Amazon managed applications and customer managed applications that only require the IAM Identity Center user's userId to be logged with actions taken by the IAM role, must obtain an identity-enhanced IAM role session with sts:audit_context. This context assertion is compatible with all Amazon API actions that the role has permission to call.

Note

When using sts:audit_context in the ProvidedContexts parameter of the AssumeRole request, the called Amazon Web Service uses only the role to authorize access. These sessions can't be used for authorizing access based on the IAM Identity Center user.

To obtain this type of identity-enhanced role session from Amazon STS, Amazon managed applications and customer managed applications provide the value of the sts:audit_context field in the AssumeRole request using the ProvidedContexts request parameter. Use arn:aws:iam::aws:contextProvider/IdentityCenter as the value for ProviderArn.

Identity-enhanced IAM role sessions created with sts:identity_context

When an Amazon managed application or customer managed application requires the requested Amazon Web Service to authorize access based on the user's identity or group membership, the application must use an identity-enhanced IAM role session that is created with sts:identity_context. In addition to the requested Amazon managed application authorizing access based on the user, CloudTrail logs the userId of the IAM Identity Center user with all actions taken by the role.

To obtain this type of identity-enhanced role session from Amazon STS, Amazon managed applications and customer managed applications provide the value of the sts:identity_context field in the AssumeRole request using the ProvidedContexts request parameter. Use arn:aws:iam::aws:contextProvider/IdentityCenter as the value for ProviderArn.

Important

If an Amazon managed application or customer managed application makes a request to an Amazon Web Service using an identity-enhanced IAM role session that is created with sts:identity_context, and the API action that is called is not enabled for trusted identity propagation, the request will result in an error. The AWSIAMIdentityCenterAllowListForIdentityContext Amazon managed policy, which is supplied as a session policy, lists supported Amazon Web Service API actions that can be used with sts:identity_context. This policy prevents the use of unsupported Amazon Web Services. To view the permissions for this policy, see AWSIAMIdentityCenterAllowListForIdentityContext in the Amazon Managed Policy Reference.

An Amazon managed application or customer managed application that makes requests using sts:identity_context will also receive an error if the called Amazon managed application is not connected to IAM Identity Center or the requested resource is not configured for user or group-membership based authorization.

To avoid this issue, do either of the following:

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

  • Use the console for the receiving Amazon managed application or its APIs to configure authorization to its resources based on the user's identity or group memberships. The setup requirements for this vary based on the Amazon managed application.

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

Identity-enhanced IAM role session logging

When a request is made to an Amazon Web Service using an identity-enhanced IAM role session that is created with sts:audit_context or the sts:identity_context, the user's IAM Identity Center userId is logged to CloudTrail in the OnBehalfOf element. The way in which events are logged in CloudTrail varies based on the Amazon Web Service. Not all Amazon Web Services log the onBehalfOf element.

The following is an example of how a request made to an Amazon Web Service using an identity-enhanced role session is logged in CloudTrail.

"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"
    }
}

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 apps using 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.