Using trusted identity propagation with AWS managed applications

Trusted identity propagation enables an AWS managed application to request access to data in AWS 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, AWS managed applications must integrate with IAM Identity Center. AWS 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 AWS managed applications for trusted identity propagation

AWS 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 AWS 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 AWS 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 AWS 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 AWS managed applications

All trusted identity propagation flows to AWS 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 AWS managed application can obtain a token from IAM Identity Center to initiate trusted identity propagation.

Topics

• Web-based, IAM Identity Center authentication
• Console-based, user-initiated authentication requests

Web-based, IAM Identity Center authentication

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

When a user opens an AWS 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 AWS 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 AWS services.

Console-based, user-initiated authentication requests

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

In this case, the AWS managed application is entered from the AWS 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 AWS managed applications.

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

• Obtain identity-enhanced IAM role sessions that it can use to make requests to other AWS managed applications that use AWS 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 AWS Security Token Service enables an AWS 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 AWS managed application. These identity-enhanced role sessions have an added identity context that the requested AWS managed application can use to authorize access.

An application obtains an identity-enhanced role session by making a request to the AWS 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 AWS 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

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

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

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

AWS 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 AWS 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 AWS 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 AWS STS, AWS 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 AWS managed application or customer managed application requires the requested AWS 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 AWS 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 AWS STS, AWS 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 AWS managed application or customer managed application makes a request to an AWS 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 AWS managed policy, which is supplied as a session policy, lists supported AWS service API actions that can be used with sts:identity_context. This policy prevents the use of unsupported AWS services. To view the permissions for this policy, see AWSIAMIdentityCenterAllowListForIdentityContext in the AWS Managed Policy Reference.

An AWS managed application or customer managed application that makes requests using sts:identity_context will also receive an error if the called AWS 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 AWS managed application is connected to IAM Identity Center.

• Use the console for the receiving AWS 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 AWS managed application.

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

Identity-enhanced IAM role session logging

When a request is made to an AWS 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 AWS service. Not all AWS services log the onBehalfOf element.

The following is an example of how a request made to an AWS 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 AWS managed applications

This section describes the setup process and request flow for AWS 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.

The following steps provide additional information about this process.

1. Use the console for the AWS 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 AWS managed application that can request access to resources (a requesting application).

3. To obtain a token to access the receiving AWS managed application, the requesting AWS 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 AWS 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 AWS 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 AWS 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 AWS CloudTrail events. The specific way in which this information is logged varies based on the application.