# Identity-enhanced IAM role sessions
<a name="trustedidentitypropagation-identity-enhanced-iam-role-sessions"></a>

The [Amazon Security Token Service](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_credentials_sts-comparison.html) (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](https://docs.amazonaws.cn//STS/latest/APIReference/API_AssumeRole.html) 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 [https://docs.amazonaws.cn/singlesignon/latest/OIDCAPIReference/API_CreateTokenWithIAM.html](https://docs.amazonaws.cn/singlesignon/latest/OIDCAPIReference/API_CreateTokenWithIAM.html). 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](#trustedidentitypropagation-identity-enhanced-iam-role-session-logging).

**Topics**
+ [Types of identity-enhanced IAM role sessions](#types-identity-enhanced-iam-role-sessions)
+ [Identity-enhanced IAM role session logging](#trustedidentitypropagation-identity-enhanced-iam-role-session-logging)

## Types of identity-enhanced IAM role sessions
<a name="types-identity-enhanced-iam-role-sessions"></a>

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`
<a name="role_session_sts_identity_context"></a>

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 is 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](#trustedidentitypropagation-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](https://docs.amazonaws.cn/STS/latest/APIReference/API_AssumeRole.html) 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`
<a name="role_session_sts_audit_context"></a>

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
<a name="trustedidentitypropagation-identity-enhanced-iam-role-session-logging"></a>

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