Trusted identity propagation overview

With trusted identity propagation, user access to AWS resources can be more easily defined, granted, and logged. Trusted identity propagation is built on the OAuth 2.0 Authorization Framework, which allows applications to access and share user data securely without sharing passwords. OAuth 2.0 provides secure delegated access to application resources. Access is delegated because the resource administrator approves, or delegates the application that the user signs in to, to access the other application.

To avoid sharing user passwords, trusted identity propagation uses tokens. Tokens provide a standard way for a trusted application to claim who the user is and what requests are permitted between two applications. AWS managed applications that integrate with trusted identity propagation obtain tokens from IAM Identity Center directly. IAM Identity Center also provides an option for applications to exchange identity tokens and access tokens that come from an external OAuth 2.0 authorization server. This makes it possible for an application to authenticate and obtain tokens outside of AWS, exchange the token for an IAM Identity Center token, and use the new token to make requests to AWS services. For more information, see Using applications with a trusted token issuer.

The OAuth 2.0 process starts when a user signs in to an application. The application that the user signs in to initiates a request to access the resources of an AWS service. The initiating (requesting) application can access the receiving service on behalf of the user by requesting a token from the authorization server. The authorization server returns the token, and the initiating application passes that token, with a request for access, to the receiving service. The following are variations of this flow applicable to different types of initiating applications and receiving services:

• AWS managed applications can authenticate using IAM Identity Center, receive a token, and pass it to AWS services that use it to make authorization decisions. For more information, see Trusted identity propagation request flows for AWS managed applications.

• Customer managed applications can use an external OIDC authorization server to obtain an access token or an identity token. They exchange the token for an IAM Identity Center token and pass it to AWS services that use it to make authorization decisions. For more information, see Using applications with a trusted token issuer.

• AWS managed applications and customer managed applications that possess an IAM Identity Center token can call AWS Security Token Service and add the user identity context to an IAM role that the application uses to call a SigV4 service. For more information, see Identity-enhanced IAM role sessions.

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 receiving service might:

• Obtain more information about the token to determine who the user is and which scopes the service can use with other receiving AWS services.

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

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

Trusted identity propagation request flows for AWS managed applications

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.

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.

Identity-enhanced IAM role sessions

The AWS Security Token Service (STS) enables an AWS managed application or a customer managed application to obtain an identity-enhanced IAM role session. These identity-enhanced role sessions have an added identity context that propagates user identity to the AWS services that are called from the role session. This enables an application to use identity-enhanced role sessions when making requests to an AWS service, and the AWS service can authorize access to resources based on the user that is represented in the role session.

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 and customer managed applications that have obtained Id tokens from IAM Identity Center can add sts:identiy_context or sts:audit_context to IAM role sessions. An identity-enhanced role session can have only one of these context assertions, not both. These identity-enhanced role sessions can be used when calling any AWS service.

Identity-enhanced IAM role sessions created with sts:audit_context

AWS managed applications and customer managed applications may specify sts:audit_context in identity-enhanced role sessions. When this is used, AWS services disregard the context in making authorization decisions. Calling applications may receive an error if the service doesn't have any role-based authorizations for the specified resources. Due to recent changes in how sts:identity_context is used in AWS managed services, AWS recommends using sts:identity_context rather than sts:audit_context.

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 identity-enhanced role session contains sts:identity_context the called AWS service determines if resource authorization is based on the user who is represented in the role session, or if it's based on the role.

AWS services that support user-based authorization provide the application's administrator with controls to assign access to the user or to groups for which the user is a member.

AWS services that do not support user-based authorization disregard the sts:identity_context. CloudTrail logs the userId of the IAM Identity Center user with all actions taken by the role. For more information, see the Identity-enhanced IAM role session logging section below.

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.

In some cases, if an AWS managed application or customer managed application makes requests using sts:identity_context it may receive an error if the called AWS service supports sts:identity_context and is not connected to IAM Identity Center, or if the requested resource is not configured for user or group-membership based authorization.

To avoid this issue, do the following:

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

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

For more information on how the authorization behaves for AWS services that support sts:identity_context, see the documentation for the receiving AWS service.

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