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

Identity-enhanced IAM role sessions

The Amazon Security Token Service (STS) enables an application to obtain an identity-enhanced IAM role session. Identity-enhanced role sessions have an added identity context that carries a user identifier to the Amazon Web Services service that it calls. Amazon Web Services services can look up the group memberships and attributes of the user in IAM Identity Center and use them to authorize the user’s access to resources.

Amazon applications obtain identity-enhanced role sessions by making requests to the Amazon STS AssumeRole API action and passing a context assertion with the user’s identifier (userId) in the ProvidedContexts parameter of the request to AssumeRole. The context assertion is obtained from the idToken claim received in response to a request to SSO OIDC to CreateTokenWithIAM. When an Amazon application uses an identity-enhanced role session to access a resource, CloudTrail logs the 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. Applications that have obtained Id tokens from IAM Identity Center can add sts:identiy_context (recommended) or sts:audit_context (Supported for backward compatibility) to IAM role sessions. An identity-enhanced IAM role session can have only one of these context assertions, not both.

Identity-enhanced IAM role sessions created with sts:identity_context

When an identity-enhanced role session contains sts:identity_context the called Amazon Web Services 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. Amazon Web Services 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.

Amazon Web Services 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 Identity-enhanced IAM role session logging.

To obtain this type of identity-enhanced role session from Amazon STS, 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.

For more information on how the authorization behaves, see the documentation for the receiving Amazon Web Services service.

Identity-enhanced IAM role sessions created with sts:audit_context

In the past, sts:audit_context was used to enable Amazon Web Services services to log the user identity without using it to make an authorization decision. Amazon Web Services services are now able to use a single context - sts:identity_context - to achieve this as well as to make authorization decisions. We recommend using sts:identity_context in all new deployments of trusted identity propagation.

Identity-enhanced IAM role session logging

When a request is made to an Amazon Web Services service using an identity-enhanced IAM role session, 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 Services service. Not all Amazon Web Services services log the onBehalfOf element.

The following is an example of how a request made to an Amazon Web Services 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"
    }
}