# Tags for AWS Identity and Access Management resources
<a name="id_tags"></a>

A *tag* is a custom attribute label that you can assign to an AWS resource. Each tag has two parts:
+ A *tag key* (for example, `CostCenter`, `Environment`, `Project`, or `Purpose`).
+ An optional field known as a *tag value* (for example, `111122223333`, `Production`, or a team name). Omitting the tag value is the same as using an empty string.

Together these are known as key-value pairs. For limits on the number of tags you can have on IAM resources, see [IAM and AWS STS quotas](reference_iam-quotas.md).

**Note**  
For details about case sensitivity for tag keys and tag key values, see [Case sensitivity](#case-sensitivity).

Tags help you identify and organize your AWS resources. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related. For example, you can assign the same tag to an IAM role that you assign to an Amazon S3 bucket. For more information about tagging strategies, see the *[Tagging AWS resources](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html) User Guide*.

In addition to identifying, organizing, and tracking your IAM resources with tags, you can use tags in IAM policies to help control who can view and interact with your resources. To learn more about using tags to control access, see [Controlling access to and for IAM users and roles using tags](access_iam-tags.md).

You can also use tags in AWS STS to add custom attributes when you assume a role or federate a user. For more information, see [Pass session tags in AWS STS](id_session-tags.md).

**Topics**
+ [

## Choose an AWS tag naming convention
](#id_tags_naming)
+ [

## Rules for tagging in IAM and AWS STS
](#id_tags_rules)
+ [

# Tag IAM users
](id_tags_users.md)
+ [

# Tag IAM roles
](id_tags_roles.md)
+ [

# Tag customer managed policies
](id_tags_customer-managed-policies.md)
+ [

# Tag OpenID Connect (OIDC) identity providers
](id_tags_oidc.md)
+ [

# Tag IAM SAML identity providers
](id_tags_saml.md)
+ [

# Tag instance profiles for Amazon EC2 roles
](id_tags_instance-profiles.md)
+ [

# Tag server certificates
](id_tags_server-certificates.md)
+ [

# Tag virtual MFA devices
](id_tags_virtual-mfa.md)
+ [

# Pass session tags in AWS STS
](id_session-tags.md)

## Choose an AWS tag naming convention
<a name="id_tags_naming"></a>

When you begin attaching tags to your IAM resources, choose your tag naming convention carefully. Apply the same convention to all of your AWS tags. This is especially important if you use tags in policies to control access to AWS resources. If you already use tags in AWS, review your naming convention and adjust it accordingly.

**Note**  
If your account is a member of AWS Organizations, see [Tag policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_tag-policies.html) in the AWS Organizations user guide to learn more about using tags in AWS Organizations.

### Best practices for tag naming
<a name="id_tags_naming_best_practices"></a>

These are some best practices and naming conventions for tags.

Ensure that tag names are used consistently. For example, the tags `CostCenter` and `costcenter` are different, so one might be configured as a cost allocation tag for financial analysis and reporting and the other one might not be. Similarly, the `Name` tag appears in the AWS Console for many resources, but the `name` tag does not. For details about case sensitivity for tag keys and tag key values, see [Case sensitivity](#case-sensitivity).

A number of tags are predefined by AWS or created automatically by various AWS services. Many AWS-defined tags names use all lowercase, with hyphens separating words in the name, and prefixes to identify the source service for the tag. For example: 
+ `aws:ec2spot:fleet-request-id` identifies the Amazon EC2 Spot Instance Request that launched the instance.
+ `aws:cloudformation:stack-name` identifies the CloudFormation stack that created the resource. 
+ `elasticbeanstalk:environment-name` identifies the application that created the resource.

Consider naming your tags using all lowercase, with hyphens separating words, and a prefix identifying the organization name or abbreviated name. For example, for a fictitious company named *AnyCompany*, you might define tags such as:
+ `anycompany:cost-center` to identify the internal Cost Center code 
+ `anycompany:environment-type` to identify whether the environment is development, test, or production
+ `anycompany:application-id` to identify the application the resource was created for 

The prefix ensures that tags are clearly identified as having been defined by your organization and not by AWS or a third-party tool that you may be using. Using all lowercase with hyphens for separators avoids confusion about how to capitalize a tag name. For example, `anycompany:project-id` is simpler to remember than `ANYCOMPANY:ProjectID`, `anycompany:projectID`, or `Anycompany:ProjectId`.

## Rules for tagging in IAM and AWS STS
<a name="id_tags_rules"></a>

A number of conventions govern the creation and application of tags in IAM and AWS STS.

### Naming tags
<a name="id_tags_rules_creating"></a>

Observe the following conventions when formulating a tag naming convention for IAM resources, AWS STS assume-role sessions, and AWS STS federated user sessions:

**Character requirements** – Tag keys and values can include any combination of letters, numbers, spaces, and \$1 . : / = \$1 - @ symbols.

**Case sensitivity** – Case sensitivity for tag keys differs depending on the type of IAM resource that is tagged. Tag key values for IAM users and roles are not case sensitive, but case is preserved. This means that you cannot have separate **Department** and **department** tag keys. If you have tagged a user with the **Department=finance** tag and you add the **department=hr** tag, it replaces the first tag. A second tag is not added.

For other IAM resource types, tag key values are case sensitive. That means you can have separate **Costcenter** and **costcenter** tag keys. For example, if you have tagged a customer managed policy with the **Costcenter = 1234** tag and you add the **costcenter = 5678** tag, the policy will have both the **Costcenter** and **costcenter** tag keys.

As a best practice, we recommend that you avoid using similar tags with inconsistent case treatment. We recommend that you decide on a strategy for capitalizing tags, and consistently implement that strategy across all resource types. To learn more about best practices for tagging, see [Tagging AWS Resources](https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html) in the AWS General Reference.

The following lists show the differences in case sensitivity for tag keys that are attached to IAM resources.

Tag key values are **not** case sensitive:
+ IAM roles
+ IAM users

Tag key values are case sensitive:
+ Customer managed policies
+ Instance profiles
+ OpenID Connect identity providers
+ SAML identity providers
+ Server certificates
+ Virtual MFA devices

Additionally, the following rules apply:
+ You cannot create a tag key or value that begins with the text **aws:**. This tag prefix is reserved for AWS internal use.
+ You can create a tag with an empty value such as **phoneNumber = **. You cannot create an empty tag key.
+ You cannot specify multiple values in a single tag, but you can create a custom multivalue structure in the single value. For example, assume that the user Zhang works on the engineering team and the QA team. If you attach the **team = Engineering** tag and then attach the **team = QA** tag, you change the value of the tag from **Engineering** to **QA**. Instead, you can include multiple values in a single tag with a custom separator. In this example, you could attach the **team = Engineering:QA** tag to Zhang.
**Note**  
To control access to engineers in this example using the **team** tag, you must create a policy that allows for every configuration that might include **Engineering**, including **Engineering:QA**. To learn more about using tags in policies, see [Controlling access to and for IAM users and roles using tags](access_iam-tags.md).

### Applying and editing tags
<a name="id_tags_rules_applying"></a>

Observe the following conventions when attaching tags to IAM resources:
+ You can tag most IAM resources, but not groups, assumed roles, access reports, or hardware-based MFA devices.
+ You cannot use Tag Editor to tag IAM resources. Tag Editor does not support IAM tags. For information about using Tag Editor with other services, see [Working with Tag Editor](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/tag-editor.html) in the *AWS Resource Groups User Guide*.
+ To tag an IAM resource, you must have specific permissions. To tag or untag resources, you must also have permission to list tags. For more information, see the list of topics for each IAM resource at the end of this page. 
+ The number and size of IAM resources in an AWS account are limited. For more information, see [IAM and AWS STS quotas](reference_iam-quotas.md).
+ You can apply the same tag to multiple IAM resources. For example, suppose you have a department named `AWS_Development` with 12 members. You can have 12 users and a role with the tag key of **department** and a value of **awsDevelopment** (**department = awsDevelopment**). You can also use the same tag on resources in other [services that support tagging](reference_aws-services-that-work-with-iam.md).
+ IAM entities (users or roles) cannot have multiple instances of the same tag key. For example, if you have a user with the tag key-value pair **costCenter = 1234**, you can then attach the tag key-value pair **costCenter = 5678**. IAM updates the value of the **costCenter** tag to **5678**.
+ To edit a tag that is attached to an IAM entity (user or role), attach a tag with a new value to overwrite the existing tag. For example, assume that you have a user with the tag key-value pair **department = Engineering**. If you need to move the user to the QA department, then you can attach the **department = QA** tag key-value pair to the user. This results in the **Engineering** value of the **department** tag key being replaced with the **QA** value.

# Tag IAM users
<a name="id_tags_users"></a>

You can use IAM tag key-value pairs to add custom attributes to an IAM user. For example, to add location information to a user, you can add the tag key **location** and the tag value **us\$1wa\$1seattle**. Or you could use three separate location tag key-value pairs: **loc-country = us**, **loc-state = wa**, and **loc-city = seattle**. You can use tags to control a user's access to resources or to control what tags can be attached to a user. To learn more about using tags to control access, see [Controlling access to and for IAM users and roles using tags](access_iam-tags.md).

You can also use tags in AWS STS to add custom attributes when you assume a role or federate a user. For more information, see [Pass session tags in AWS STS](id_session-tags.md).

## Permissions required for tagging IAM users
<a name="id_tags_users_permissions"></a>

You must configure permissions to allow an IAM user to tag other users. You can specify one or all of the following IAM tag actions in an IAM policy:
+ `iam:ListUserTags`
+ `iam:TagUser`
+ `iam:UntagUser`

**To allow an IAM user to add, list, or remove a tag for a specific user**  
Add the following statement to the permissions policy for the IAM user that needs to manage tags. Use your account number and replace *<username>* with the name of the user whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListUserTags",
        "iam:TagUser",
        "iam:UntagUser"
    ],
    "Resource": "arn:aws:iam::<account-number>:user/<username>"
}
```

**To allow an IAM user to self-manage tags**  
Add the following statement to the permissions policy for users to allow users to manage their own tags. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListUserTags",
        "iam:TagUser",
        "iam:UntagUser"
    ],
    "Resource": "arn:aws:iam::user/${aws:username}"
}
```

**To allow an IAM user to add a tag to a specific user**  
Add the following statement to the permissions policy for the IAM user that needs to add, but not remove, tags for a specific user.

**Note**  
The `iam:TagUser` action requires that you also include the `iam:ListUserTags` action.

To use this policy, replace *<username>* with the name of the user whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListUserTags",
        "iam:TagUser"
    ],
    "Resource": "arn:aws:iam::<account-number>:user/<username>"
}
```

Alternatively, you can use an AWS managed policy such as [IAMFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/IAMFullAccess) to provide full access to IAM.

## Managing tags on IAM users (console)
<a name="id_tags_users_procs-console"></a>

You can manage tags for IAM users from the AWS Management Console.

**To manage tags on users (console)**

1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane of the console, choose **Users** and then choose the name of the user that you want to edit.

1. Choose the **Tags** tab and then complete one of the following actions:
   + Choose **Add new tag** if the user does not yet have tags.
   + Choose **Manage tags** to manage the existing set of tags.

1. Add or remove tags to complete the set of tags. Then choose **Save changes**.

## Managing tags on IAM users (AWS CLI or AWS API)
<a name="id_tags_users_procs-cli-api"></a>

You can list, attach, or remove tags for IAM users. You can use the AWS CLI or the AWS API to manage tags for IAM users.

**To list the tags currently attached to an IAM user (AWS CLI or AWS API)**
+ AWS CLI: [aws iam list-user-tags](https://docs.aws.amazon.com/cli/latest/reference/iam/list-user-tags.html)
+ AWS API: [ListUserTags](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListUserTags.html)

**To attach tags to an IAM user (AWS CLI or AWS API)**
+ AWS CLI: [aws iam tag-user](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-user.html)
+ AWS API: [TagUser](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagUser.html)

**To remove tags from an IAM user (AWS CLI or AWS API)**
+ AWS CLI: [aws iam untag-user](https://docs.aws.amazon.com/cli/latest/reference/iam/untag-user.html)
+ AWS API: [UntagUser](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagUser.html)

For information about attaching tags to resources for other AWS services, see the documentation for those services. 

For information about using tags to set more granular permissions with IAM permissions policies, see [IAM policy elements: Variables and tags](reference_policies_variables.md).

# Tag IAM roles
<a name="id_tags_roles"></a>

You can use IAM tag key-value pairs to add custom attributes to an IAM role. For example, to add location information to a role, you can add the tag key **location** and the tag value **us\$1wa\$1seattle**. Or you could use three separate location tag key-value pairs: **loc-country = us**, **loc-state = wa**, and **loc-city = seattle**. You can use tags to control a role's access to resources or to control what tags can be attached to a role. To learn more about using tags to control access, see [Controlling access to and for IAM users and roles using tags](access_iam-tags.md).

You can also use tags in AWS STS to add custom attributes when you assume a role or federate a user. For more information, see [Pass session tags in AWS STS](id_session-tags.md).

## Permissions required for tagging IAM roles
<a name="id_tags_roles_permissions"></a>

You must configure permissions to allow an IAM role to tag other entities (users or roles). You can specify one or all of the following IAM tag actions in an IAM policy:
+ `iam:ListRoleTags`
+ `iam:TagRole`
+ `iam:UntagRole`
+ `iam:ListUserTags`
+ `iam:TagUser`
+ `iam:UntagUser`

**To allow an IAM role to add, list, or remove a tag for a specific user**  
Add the following statement to the permissions policy for the IAM role that needs to manage tags. Use your account number and replace *<username>* with the name of the user whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListUserTags",
        "iam:TagUser",
        "iam:UntagUser"
    ],
    "Resource": "arn:aws:iam::<account-number>:user/<username>"
}
```

**To allow an IAM role to add a tag to a specific user**  
Add the following statement to the permissions policy for the IAM role that needs to add, but not remove, tags for a specific user.

To use this policy, replace *<username>* with the name of the user whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListUserTags",
        "iam:TagUser"
    ],
    "Resource": "arn:aws:iam::<account-number>:user/<username>"
}
```

**To allow an IAM role to add, list, or remove a tag for a specific role**  
Add the following statement to the permissions policy for the IAM role that needs to manage tags. Replace *<rolename>* with the name of the role whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListRoleTags",
        "iam:TagRole",
        "iam:UntagRole"
    ],
    "Resource": "arn:aws:iam::<account-number>:role/<rolename>"
}
```

Alternatively, you can use an AWS managed policy such as [IAMFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/IAMFullAccess) to provide full access to IAM.

## Managing tags on IAM roles (console)
<a name="id_tags_roles_procs-console"></a>

You can manage tags for IAM roles from the AWS Management Console.

**To manage tags on roles (console)**

1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane of the console, choose **Roles** and then choose the name of the role that you want to edit.

1. Choose the **Tags** tab and then complete one of the following actions:
   + Choose **Add new tag** if the role does not yet have tags.
   + Choose **Manage tags** to manage the existing set of tags.

1. Add or remove tags to complete the set of tags. Then, choose **Save changes**.

## Managing tags on IAM roles (AWS CLI or AWS API)
<a name="id_tags_roles_procs-cli-api"></a>

You can list, attach, or remove tags for IAM roles. You can use the AWS CLI or the AWS API to manage tags for IAM roles.

**To list the tags currently attached to an IAM role (AWS CLI or AWS API)**
+ AWS CLI: [aws iam list-role-tags](https://docs.aws.amazon.com/cli/latest/reference/iam/list-role-tags.html)
+ AWS API: [ListRoleTags](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListRoleTags.html)

**To attach tags to an IAM role (AWS CLI or AWS API)**
+ AWS CLI: [aws iam tag-role](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-role.html)
+ AWS API: [TagRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagRole.html)

**To remove tags from an IAM role (AWS CLI or AWS API)**
+ AWS CLI: [aws iam untag-role](https://docs.aws.amazon.com/cli/latest/reference/iam/untag-role.html)
+ AWS API: [UntagRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagRole.html)

For information about attaching tags to resources for other AWS services, see the documentation for those services. 

For information about using tags to set more granular permissions with IAM permissions policies, see [IAM policy elements: Variables and tags](reference_policies_variables.md).

# Tag customer managed policies
<a name="id_tags_customer-managed-policies"></a>

You can use IAM tag key-value pairs to add custom attributes to your customer managed policies. For example, to tag a policy with department information, you can add the tag key **Department** and the tag value **eng**. Or, you might want to tag policies to indicate that they are for a specific environment, such as **Environment = lab**. You can use tags to control access to resources or to control what tags can be attached to a resource. To learn more about using tags to control access, see [Controlling access to and for IAM users and roles using tags](access_iam-tags.md).

You can also use tags in AWS STS to add custom attributes when you assume a role or federate a user. For more information, see [Pass session tags in AWS STS](id_session-tags.md).

## Permissions required for tagging customer managed policies
<a name="id_tags_customer-managed-policies_permissions"></a>

You must configure permissions to allow an IAM entity (users or roles) to tag customer managed policies. You can specify one or all of the following IAM tag actions in an IAM policy:
+ `iam:ListPolicyTags`
+ `iam:TagPolicy`
+ `iam:UntagPolicy`

**To allow an IAM entity (user or role) to add, list, or remove a tag for a customer managed policy**  
Add the following statement to the permissions policy for the IAM entity that needs to manage tags. Use your account number and replace *<policyname>* with the name of the policy whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListPolicyTags",
        "iam:TagPolicy",
        "iam:UntagPolicy"
    ],
    "Resource": "arn:aws:iam::<account-number>:policy/<policyname>"
}
```

**To allow an IAM entity (user or role) to add a tag to a specific customer managed policy**  
Add the following statement to the permissions policy for the IAM entity that needs to add, but not remove, tags for a specific policy. 

**Note**  
The `iam:TagPolicy` action requires that you also include the `iam:ListPolicyTags` action.

To use this policy, replace *<policyname>* with the name of the policy whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListPolicyTags",
        "iam:TagPolicy"
    ],
    "Resource": "arn:aws:iam::<account-number>:policy/<policyname>"
}
```

Alternatively, you can use an AWS managed policy such as [IAMFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/IAMFullAccess) to provide full access to IAM.

## Managing tags on IAM customer managed policies (console)
<a name="id_tags_customer-managed-policies_procs-console"></a>

You can manage tags for IAM customer managed policies from the AWS Management Console.

**To manage tags on customer managed policies (console)**

1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane of the console, choose **Policies** and then choose the name of the customer managed policy that you want to edit.

1. Choose the **Tags** tab and then choose **Manage tags**.

1. Add or remove tags to complete the set of tags. Then choose **Save changes**.

## Managing tags on IAM customer managed policies (AWS CLI or AWS API)
<a name="id_tags_customer-managed-policies_procs-cli-api"></a>

You can list, attach, or remove tags for IAM customer managed policies. You can use the AWS CLI or the AWS API to manage tags for IAM customer managed policies.

**To list the tags currently attached to an IAM customer managed policy (AWS CLI or AWS API)**
+ AWS CLI: [aws iam list-policy-tags](https://docs.aws.amazon.com/cli/latest/reference/iam/list-policy-tags.html)
+ AWS API: [ListPolicyTags](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListPolicyTags.html)

**To attach tags to an IAM customer managed policy(AWS CLI or AWS API)**
+ AWS CLI: [aws iam tag-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-policy.html)
+ AWS API: [TagPolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagPolicy.html)

**To remove tags from an IAM customer managed policy (AWS CLI or AWS API)**
+ AWS CLI: [aws iam untag-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/untag-policy.html)
+ AWS API: [UntagPolicy](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagPolicy.html)

For information about attaching tags to resources for other AWS services, see the documentation for those services. 

For information about using tags to set more granular permissions with IAM permissions policies, see [IAM policy elements: Variables and tags](reference_policies_variables.md).

# Tag OpenID Connect (OIDC) identity providers
<a name="id_tags_oidc"></a>

You can use IAM tag key-values to add custom attributes to IAM OpenID Connect (OIDC) identity providers. For example, to identify an OIDC identity provider, you can add the tag key **google** and the tag value **oidc**. You can use tags to control access to resources or to control what tags can be attached to an object. To learn more about using tags to control access, see [Controlling access to and for IAM users and roles using tags](access_iam-tags.md).

## Permissions required for tagging IAM OIDC identity providers
<a name="id_tags_oidc_permissions"></a>

You must configure permissions to allow an IAM entity (user or role) to tag IAM OIDC identity providers. You can specify one or all of the following IAM tag actions in an IAM policy:
+ `iam:ListOpenIDConnectProviderTags`
+ `iam:TagOpenIDConnectProvider`
+ `iam:UntagOpenIDConnectProvider`

**To allow an IAM entity to add, list, or remove a tag for an IAM OIDC identity provider**  
Add the following statement to the permissions policy for the IAM entity that needs to manage tags. Use your account number and replace *<OIDCProviderName>* with the name of the OIDC provider whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListOpenIDConnectProviderTags",
        "iam:TagOpenIDConnectProvider",
        "iam:UntagOpenIDConnectProvider"
    ],
    "Resource": "arn:aws:iam::<account-number>:oidc-provider/<OIDCProviderName>"
}
```

**To allow an IAM entity (user or role) to add a tag to a specific IAM OIDC identity provider**  
Add the following statement to the permissions policy for the IAM entity that needs to add, but not remove, tags for a specific identity provider.

**Note**  
The `iam:TagOpenIDConnectProvider` action requires that you also include the `iam:ListOpenIDConnectProviderTags` action.

To use this policy, replace *<OIDCProviderName>* with the name of the OIDC provider whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListOpenIDConnectProviderTags",
        "iam:TagOpenIDConnectProvider"
    ],
    "Resource": "arn:aws:iam::<account-number>:oidc-provider/<OIDCProviderName>"
}
```

Alternatively, you can use an AWS managed policy such as [IAMFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/IAMFullAccess) to provide full access to IAM.

## Managing tags on IAM OIDC identity providers (console)
<a name="id_tags_oidc_procs-console"></a>

You can manage tags for IAM OIDC identity providers from the AWS Management Console.

**To manage tags on OIDC identity providers (console)**

1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane of the console, choose **Identity providers** and then choose the name of the identity provider that you want to edit.

1. Choose the **Tags** tab, then in the **Tags** section, choose **Manage tags** and then complete one of the following actions:
   + Choose **Add tag** if the OIDC identity provider does not yet have tags or to add a new tag.
   + Edit existing tag keys and values.
   + Choose **Remove tag** to remove a tag.

1. Then choose **Save changes**.

## Managing tags on IAM OIDC identity providers (AWS CLI or AWS API)
<a name="id_tags_oidc_procs-cli-api"></a>

You can list, attach, or remove tags for IAM OIDC identity providers. You can use the AWS CLI or the AWS API to manage tags for IAM OIDC identity providers.

**To list the tags currently attached to an IAM OIDC identity provider (AWS CLI or AWS API)**
+ AWS CLI: [aws iam list-open-id-connect-provider-tags](https://docs.aws.amazon.com/cli/latest/reference/iam/list-open-id-connect-provider-tags.html)
+ AWS API: [ListOpenIDConnectProviderTags](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListOpenIDConnectProviderTags.html)

**To attach tags to an IAM OIDC identity provider (AWS CLI or AWS API)**
+ AWS CLI: [aws iam tag-open-id-connect-provider](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-open-id-connect-provider.html)
+ AWS API: [TagOpenIDConnectProvider](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagOpenIDConnectProvider.html)

**To remove tags from an IAM OIDC identity provider (AWS CLI or AWS API)**
+ AWS CLI: [aws iam untag-open-id-connect-provider](https://docs.aws.amazon.com/cli/latest/reference/iam/untag-open-id-connect-provider.html)
+ AWS API: [UntagOpenIDConnectProvider](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagOpenIDConnectProvider.html)

For information about attaching tags to resources for other AWS services, see the documentation for those services. 

For information about using tags to set more granular permissions with IAM permissions policies, see [IAM policy elements: Variables and tags](reference_policies_variables.md).

# Tag IAM SAML identity providers
<a name="id_tags_saml"></a>

You can use IAM tag key-value pairs to add custom attributes to SAML identity providers. For example, to identify a provider, you can add the tag key **okta** and the tag value **saml**. You can use tags to control access to resources or to control what tags can be attached to an object. To learn more about using tags to control access, see [Controlling access to and for IAM users and roles using tags](access_iam-tags.md).

## Permissions required for tagging SAML identity providers
<a name="id_tags_saml_permissions"></a>

You must configure permissions to allow an IAM entity (users or roles) to tag SAML 2.0–based Identity Providers (IdPs). You can specify one or all of the following IAM tag actions in an IAM policy:
+ `iam:ListSAMLProviderTags`
+ `iam:TagSAMLProvider`
+ `iam:UntagSAMLProvider`

**To allow an IAM entity (user or role) to add, list, or remove a tag for a SAML identity provider**  
Add the following statement to the permissions policy for the IAM entity that needs to manage tags. Use your account number and replace *<SAMLProviderName>* with the name of the SAML provider whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListSAMLProviderTags",
        "iam:TagSAMLProvider",
        "iam:UntagSAMLProvider"
    ],
    "Resource": "arn:aws:iam::<account-number>:saml-provider/<SAMLProviderName>"
}
```

**To allow an IAM entity (user or role) to add a tag to a specific SAML identity provider**  
Add the following statement to the permissions policy for the IAM entity that needs to add, but not remove, tags for a specific SAML provider.

**Note**  
The `iam:TagSAMLProvider` action requires that you also include the `iam:ListSAMLProviderTags` action.

To use this policy, replace *<SAMLProviderName>* with the name of the SAML provider whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListSAMLProviderTags",
        "iam:TagSAMLProvider"
    ],
    "Resource": "arn:aws:iam::<account-number>:saml-provider/<SAMLProviderName>"
}
```

Alternatively, you can use an AWS managed policy such as [IAMFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/IAMFullAccess) to provide full access to IAM.

## Managing tags on IAM SAML identity providers (console)
<a name="id_tags_saml_procs-console"></a>

You can manage tags for IAM SAML Identity Providers from the AWS Management Console.

**To manage tags on SAML identity providers (console)**

1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane of the console, choose **Identity providers** and then choose the name of the SAML identity provider that you want to edit.

1. Choose the **Tags** tab, then in the **Tags** section, choose **Manage tags** and then complete one of the following actions:
   + Choose **Add tag** if the SAML identity provider does not yet have tags or to add a new tag.
   + Edit existing tag keys and values.
   + Choose **Remove tag** to remove a tag.

1. Add or remove tags to complete the set of tags. Then choose **Save changes**.

## Managing tags on IAM SAML identity providers (AWS CLI or AWS API)
<a name="id_tags_saml_procs-cli-api"></a>

You can list, attach, or remove tags for IAM SAML identity providers. You can use the AWS CLI or the AWS API to manage tags for IAM SAML identity providers.

**To list the tags currently attached to an SAML identity provider (AWS CLI or AWS API)**
+ AWS CLI: [aws iam list-saml-provider-tags](https://docs.aws.amazon.com/cli/latest/reference/iam/list-saml-provider-tags.html)
+ AWS API: [ListSAMLProviderTags](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListSAMLProviderTags.html)

**To attach tags to a SAML identity provider (AWS CLI or AWS API)**
+ AWS CLI: [aws iam tag-saml-provider](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-saml-provider.html)
+ AWS API: [TagSAMLProvider](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagSAMLProvider.html)

**To remove tags from a SAML identity provider (AWS CLI or AWS API)**
+ AWS CLI: [aws iam untag-saml-provider](https://docs.aws.amazon.com/cli/latest/reference/iam/untag-saml-provider.html)
+ AWS API: [UntagSAMLProvider](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagSAMLProvider.html)

For information about attaching tags to resources for other AWS services, see the documentation for those services. 

For information about using tags to set more granular permissions with IAM permissions policies, see [IAM policy elements: Variables and tags](reference_policies_variables.md).

# Tag instance profiles for Amazon EC2 roles
<a name="id_tags_instance-profiles"></a>

When you launch an Amazon EC2 instance, you specify an IAM role to associate with the instance. An instance profile is a container for an IAM role that you can use to pass role information to an Amazon EC2 instance when the instance starts. You can tag instance profiles when you use the AWS CLI or AWS API.

You can use IAM tag key-value pairs to add custom attributes to an instance profile. For example, to add department information to an instance profile, you can add the tag key **access-team** and the tag value **eng**. Doing this gives principals with matching tags access to instance profiles with the same tag. You could use multiple tag key-value pairs to specify a team and project: **access-team = eng **, and **project = peg**. You can use tags to control a user's access to resources or to control what tags can be attached to a user. To learn more about using tags to control access, see [Controlling access to and for IAM users and roles using tags](access_iam-tags.md).

You can also use tags in AWS STS to add custom attributes when you assume a role or federate a user. For more information, see [Pass session tags in AWS STS](id_session-tags.md).

## Permissions required for tagging instance profiles
<a name="id_tags_instance-profiles_permissions"></a>

You must configure permissions to allow an IAM entity (user or role) to tag instance profiles. You can specify one or all of the following IAM tag actions in an IAM policy:
+ `iam:ListInstanceProfileTags`
+ `iam:TagInstanceProfile`
+ `iam:UntagInstanceProfile`

**To allow an IAM entity (user or role) to add, list, or remove a tag for an instance profile**  
Add the following statement to the permissions policy for the IAM entity that needs to manage tags. Use your account number and replace *<InstanceProfileName>* with the name of the instance profile whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListInstanceProfileTags",
        "iam:TagInstanceProfile",
        "iam:UntagInstanceProfile"
    ],
    "Resource": "arn:aws:iam::<account-number>:instance-profile/<InstanceProfileName>"
}
```

**To allow an IAM entity (user or role) to add a tag to a specific instance profile**  
Add the following statement to the permissions policy for the IAM entity that needs to add, but not remove, tags for a specific instance profile. 

**Note**  
The `iam:TagInstanceProfile` action requires that you also include the `iam:ListInstanceProfileTags` action.

To use this policy, replace *<InstanceProfileName>* with the name of the instance profile whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListInstanceProfileTags",
        "iam:TagInstanceProfile"
    ],
    "Resource": "arn:aws:iam::<account-number>:instance-profile/<InstanceProfileName>"
}
```

Alternatively, you can use an AWS managed policy such as [IAMFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/IAMFullAccess) to provide full access to IAM.

## Managing tags on instance profiles (AWS CLI or AWS API)
<a name="id_tags_instance-profile_procs-cli-api"></a>

You can list, attach, or remove tags for instance profiles. You can use the AWS CLI or the AWS API to manage tags for instance profiles.

**To list the tags currently attached to an instance profile (AWS CLI or AWS API)**
+ AWS CLI: [aws iam list-instance-profile-tags](https://docs.aws.amazon.com/cli/latest/reference/iam/list-instance-profile-tags.html)
+ AWS API: [ListInstanceProfileTags](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListInstanceProfileTags.html)

**To attach tags to an instance profile (AWS CLI or AWS API)**
+ AWS CLI: [aws iam tag-instance-profile](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-instance-profile.html)
+ AWS API: [TagInstanceProfile](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagInstanceProfile.html)

**To remove tags from an instance profile (AWS CLI or AWS API)**
+ AWS CLI: [aws iam untag-instance-profile](https://docs.aws.amazon.com/cli/latest/reference/iam/untag-instance-profile.html)
+ AWS API: [UntagInstanceProfile](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagInstanceProfile.html)

For information about attaching tags to resources for other AWS services, see the documentation for those services. 

For information about using tags to set more granular permissions with IAM permissions policies, see [IAM policy elements: Variables and tags](reference_policies_variables.md).

# Tag server certificates
<a name="id_tags_server-certificates"></a>

If you use IAM to manage SSL/TLS certificates, you can tag server certificates in IAM using the AWS CLI or AWS API. For certificates in a Region supported by AWS Certificate Manager (ACM), we recommend that you use ACM instead of IAM to provision, manage, and deploy your server certificates. In unsupported Regions, you must use IAM as a certificate manager. To learn which Regions ACM supports, see [AWS Certificate Manager endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/acm.html) in the *AWS General Reference*.

You can use IAM tag key-value pairs to add custom attributes to a server certificate. For example, to add information about the owner or administrator of a server certificate, add the tag key **owner** and the tag value **net-eng**. Or you can specify a cost center by adding the tag key **CostCenter** and the tag value **1234**. You can use tags to control access to resources or to control what tags can be attached to resources. To learn more about using tags to control access, see [Controlling access to and for IAM users and roles using tags](access_iam-tags.md).

You can also use tags in AWS STS to add custom attributes when you assume a role or federate a user. For more information, see [Pass session tags in AWS STS](id_session-tags.md).

## Permissions required for tagging server certificates
<a name="id_tags_server-certificates_permissions"></a>

You must configure permissions to allow an IAM entity (user or role) to tag server certificates. You can specify one or all of the following IAM tag actions in an IAM policy:
+ `iam:ListServerCertificateTags`
+ `iam:TagServerCertificate`
+ `iam:UntagServerCertificate`

**To allow an IAM entity (user or role) to add, list, or remove a tag for a server certificate**  
Add the following statement to the permissions policy for the IAM entity that needs to manage tags. Use your account number and replace *<CertificateName>* with the name of the server certificate whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListServerCertificateTags",
        "iam:TagServerCertificate",
        "iam:UntagServerCertificate"
    ],
    "Resource": "arn:aws:iam::<account-number>:server-certificate/<CertificateName>"
}
```

**To allow an IAM entity (user or role) to add a tag to a specific server certificate**  
Add the following statement to the permissions policy for the IAM entity that needs to add, but not remove, tags for a specific server certificate.

**Note**  
The `iam:TagServerCertificate` action requires that you also include the `iam:ListServerCertificateTags` action.

To use this policy, replace *<CertificateName>* with the name of the server certificate whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListServerCertificateTags",
        "iam:TagServerCertificate"
    ],
    "Resource": "arn:aws:iam::<account-number>:server-certificate/<CertificateName>"
}
```

Alternatively, you can use an AWS managed policy such as [IAMFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/IAMFullAccess) to provide full access to IAM.

## Managing tags on server certificates (AWS CLI or AWS API)
<a name="id_tags_server-certificates_procs-cli-api"></a>

You can list, attach, or remove tags for server certificates. You can use the AWS CLI or the AWS API to manage tags for server certificates.

**To list the tags currently attached to a server certificate (AWS CLI or AWS API)**
+ AWS CLI: [aws iam list-server-certificate-tags](https://docs.aws.amazon.com/cli/latest/reference/iam/list-server-certificate-tags.html)
+ AWS API: [ListServerCertificateTags](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListServerCertificateTags.html)

**To attach tags to a server certificate(AWS CLI or AWS API)**
+ AWS CLI: [aws iam tag-server-certificate](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-server-certificate.html)
+ AWS API: [TagServerCertificate](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagServerCertificate.html)

**To remove tags from a server certificate (AWS CLI or AWS API)**
+ AWS CLI: [aws iam untag-server-certificate](https://docs.aws.amazon.com/cli/latest/reference/iam/untag-server-certificate.html)
+ AWS API: [UntagServerCertificate](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagServerCertificate.html)

For information about attaching tags to resources for other AWS services, see the documentation for those services. 

For information about using tags to set more granular permissions with IAM permissions policies, see [IAM policy elements: Variables and tags](reference_policies_variables.md).

# Tag virtual MFA devices
<a name="id_tags_virtual-mfa"></a>

You can use IAM tag key-value pairs to add custom attributes to a virtual MFA device. For example, to add cost center information for a user's virtual MFA device, you can add the tag key **CostCenter** and the tag value **1234**. You can use tags to control access to resources or to control what tags can be attached to an object. To learn more about using tags to control access, see [Controlling access to and for IAM users and roles using tags](access_iam-tags.md).

You can also use tags in AWS STS to add custom attributes when you assume a role or federate a user. For more information, see [Pass session tags in AWS STS](id_session-tags.md).

## Permissions required for tagging virtual MFA devices
<a name="id_tags_virtual-mfa_permissions"></a>

You must configure permissions to allow an IAM entity (user or role) to tag virtual MFA devices. You can specify one or all of the following IAM tag actions in an IAM policy:
+ `iam:ListMFADeviceTags`
+ `iam:TagMFADevice`
+ `iam:UntagMFADevice`

**To allow an IAM entity (user or role) to add, list, or remove a tag for a virtual MFA device**  
Add the following statement to the permissions policy for the IAM entity that needs to manage tags. Use your account number and replace *<MFATokenID>* with the name of the virtual MFA device whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListMFADeviceTags",
        "iam:TagMFADevice",
        "iam:UntagMFADevice"
    ],
    "Resource": "arn:aws:iam::<account-number>:mfa/<MFATokenID>"
}
```

**To allow an IAM entity (user or role) to add a tag to a specific virtual MFA device**  
Add the following statement to the permissions policy for the IAM entity that needs to add, but not remove, tags for a specific MFA device.

**Note**  
The `iam:TagMFADevice` action requires that you also include the `iam:ListMFADeviceTags` action.

To use this policy, replace *<MFATokenID>* with the name of the virtual MFA device whose tags need to be managed. To learn how to create a policy using this example JSON policy document, see [Creating policies using the JSON editor](access_policies_create-console.md#access_policies_create-json-editor).

```
{
    "Effect": "Allow",
    "Action": [
        "iam:ListMFADeviceTags",
        "iam:TagMFADevice"
    ],
    "Resource": "arn:aws:iam::<account-number>:mfa/<MFATokenID>"
}
```

Alternatively, you can use an AWS managed policy such as [IAMFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/IAMFullAccess) to provide full access to IAM.

## Managing tags on virtual MFA devices (AWS CLI or AWS API)
<a name="id_tags_virtual-mfa_procs-cli-api"></a>

You can list, attach, or remove tags for a virtual MFA device. You can use the AWS CLI or the AWS API to manage tags for a virtual MFA device.

**To list the tags currently attached to a virtual MFA device (AWS CLI or AWS API)**
+ AWS CLI: [aws iam list-mfa-device-tags](https://docs.aws.amazon.com/cli/latest/reference/iam/list-mfa-device-tags.html)
+ AWS API: [ListMFADeviceTags](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListMFADeviceTags.html)

**To attach tags to a virtual MFA device (AWS CLI or AWS API)**
+ AWS CLI: [aws iam tag-mfa-device](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-mfa-device.html)
+ AWS API: [TagMFADevice](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagMFADevice.html)

**To remove tags from a virtual MFA device (AWS CLI or AWS API)**
+ AWS CLI: [aws iam untag-mfa-device](https://docs.aws.amazon.com/cli/latest/reference/iam/untag-mfa-device.html)
+ AWS API: [UntagMFADevice](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagMFADevice.html)

For information about attaching tags to resources for other AWS services, see the documentation for those services. 

For information about using tags to set more granular permissions with IAM permissions policies, see [IAM policy elements: Variables and tags](reference_policies_variables.md).

# Pass session tags in AWS STS
<a name="id_session-tags"></a>

Session tags are key-value pair attributes that you pass when you assume an IAM role or federate a user in AWS STS. You do this by making an AWS CLI or AWS API request through AWS STS or through your identity provider (IdP). When you use AWS STS to request temporary security credentials, you generate a session. Sessions expire and have [credentials](https://docs.aws.amazon.com/STS/latest/APIReference/API_Credentials.html), such as an access key pair and a session token. When you use the session credentials to make a subsequent request, the [request context](reference_policies_elements_condition.md#AccessPolicyLanguage_RequestContext) includes the `aws:PrincipalTag` context key. You can use the `aws:PrincipalTag` key in the `Condition` element of your policies to allow or deny access based on those tags.

When you use temporary credentials to make a request, your principal might include a set of tags. These tags come from the following sources:

1. **Session tags** – The tags passed when you assume the role or federate the user using the AWS CLI or AWS API. For more information about these operations, see [Session tagging operations](#id_session-tags_operations).

1. **Incoming transitive session tags** – The tags inherited from a previous session in a role chain. For more information, see [Chaining roles with session tags](#id_session-tags_role-chaining) later in this topic.

1. **IAM tags** – The tags attached to your IAM assumed role.

**Topics**
+ [

## Session tagging operations
](#id_session-tags_operations)
+ [

## Things to know about session tags
](#id_session-tags_know)
+ [

## Permissions required to add session tags
](#id_session-tags_permissions-required)
+ [

## Passing session tags using AssumeRole
](#id_session-tags_adding-assume-role)
+ [

## Passing session tags using AssumeRoleWithSAML
](#id_session-tags_adding-assume-role-saml)
+ [

## Passing session tags using AssumeRoleWithWebIdentity
](#id_session-tags_adding-assume-role-idp)
+ [

## Passing session tags using GetFederationToken
](#id_session-tags_adding-getfederationtoken)
+ [

## Chaining roles with session tags
](#id_session-tags_role-chaining)
+ [

## Using session tags for ABAC
](#id_session-tags_using-abac)
+ [

## Viewing session tags in CloudTrail
](#id_session-tags_ctlogs)

## Session tagging operations
<a name="id_session-tags_operations"></a>

You can pass session tags using the following AWS CLI or AWS API operations in AWS STS. *The AWS Management Console **[Switch Role](id_roles_use_switch-role-console.md)** feature does not allow you to pass session tags.*

You can also set the session tags as transitive. Transitive tags persist during role chaining. For more information, see [Chaining roles with session tags](#id_session-tags_role-chaining).

The following table compares methods for passing session tags.


|  Operation |  **Who can assume the role**  | **Method to pass tags** |  **Method to set transitive tags**  | 
| --- | --- | --- | --- | 
| [https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role.html](https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role.html) CLI or [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API operation | IAM user or a session | Tags API parameter or --tags CLI option | TransitiveTagKeys API parameter or --transitive-tag-keys CLI option | 
| [https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role-with-saml.html](https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role-with-saml.html) CLI or [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API operation | Any user authenticated using a SAML identity provider | PrincipalTag SAML attribute | TransitiveTagKeys SAML Attribute | 
| [https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role-with-web-identity.html](https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role-with-web-identity.html) CLI or [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) API operation | Any user authenticated using an OIDC provider | PrincipalTag OIDC token | TransitiveTagKeys OIDC token | 
| [https://docs.aws.amazon.com/cli/latest/reference/sts/get-federation-token.html](https://docs.aws.amazon.com/cli/latest/reference/sts/get-federation-token.html) CLI or [https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html) API operation | IAM user or root user | Tags API parameter or --tags CLI option | Not supported | 

Operations that support session tagging can fail under the following conditions:
+ You pass more than 50 session tags.
+ The plaintext of your session tag keys exceeds 128 characters.
+ The plaintext of your session tag values exceeds 256 characters.
+ The total size of the plaintext of session policies exceeds 2048 characters.
+ The total packed size of the combined session policies and tags is too large. If the operation fails, the error message shows how close the policies and tags combined come to the upper size limit, by percentage.

## Things to know about session tags
<a name="id_session-tags_know"></a>

Before you use session tags, review the following details about sessions and tags.
+ When using session tags, trust policies for all roles connected to the identity provider (IdP) passing tags must have the [`sts:TagSession`](#id_session-tags_permissions-required) permission. For roles without this permission in the trust policy, the `AssumeRole` operation fails.
+ When you request a session, you can specify principal tags as the session tags. The tags apply to requests that you make using the session's credentials.
+ Session tags use key-value pairs. For example, to add contact information to a session, you can add the session tag key `email` and the tag value `johndoe@example.com`.
+ Session tags must follow the [rules for naming tags in IAM and AWS STS](id_tags.md#id_tags_rules_creating). This topic includes information about case sensitivity and restricted prefixes that apply to your session tags.
+ New session tags override existing assumed role or federated user session tags with the same tag key, regardless of character case.
+ You cannot pass session tags using the AWS Management Console.
+ Session tags are valid only for the current session. 
+ Session tags support [role chaining](id_roles.md#iam-term-role-chaining). By default, AWS STS does not pass tags to subsequent role sessions. However, you can set session tags as transitive. Transitive tags persist during role chaining and replace matching `ResourceTag` values after the evaluation of the role trust policy. For more information, see [Chaining roles with session tags](#id_session-tags_role-chaining).
+ You can use session tags to control access to resources or to control what tags can be passed into a subsequent session. For more information, see [IAM tutorial: Use SAML session tags for ABAC](tutorial_abac-saml.md).
+ You can view the principal tags for your session, including the session tags, in the AWS CloudTrail logs. For more information, see [Viewing session tags in CloudTrail](#id_session-tags_ctlogs).
+ You must pass a single value for each session tag. AWS STS does not support multi-valued session tags. 
+ You can pass a maximum of 50 session tags. The number and size of IAM resources in an AWS account are limited. For more information, see [IAM and AWS STS quotas](reference_iam-quotas.md).
+ An AWS conversion compresses the passed session policies and session tags combined into a packed binary format with a separate limit. If you exceed this limit, the AWS CLI or AWS API error message shows how close the policies and tags combined come to the upper size limit, by percentage.

## Permissions required to add session tags
<a name="id_session-tags_permissions-required"></a>

In addition to the action that matches the API operation, you must have the following permissions-only action in your policy:

```
sts:TagSession
```

**Important**  
When using session tags, the role trust policies for all roles connected to an identity provider (IdP) must have the `sts:TagSession` permission. The `AssumeRole` operation fails for any role connected to an IdP passing session tags without this permission. If you don't want to update the role trust policy for each role, you can use a separate IdP instance for passing session tags. Then, add the `sts:TagSession` permission to only the roles connected to the separate IdP.

You can use the `sts:TagSession` action with the following condition keys.
+ `aws:PrincipalTag` – Compares the tag attached to the principal making the request with the tag you specified in the policy. For example, you can allow a principal to pass session tags only if the principal making the request has the specified tags.
+ `aws:RequestTag` – Compares the tag key-value pair passed in the request with the tag pair you specified in the policy. For example, you can allow the principal to pass the specified session tags, but only with the specified values.
+ `aws:ResourceTag` – Compares the tag key-value pair you specified in the policy with the key-value pair attached to the resource. For example, you can allow the principal to pass session tags only if the role they assume includes the specified tags.
+ `aws:TagKeys` – Compares the tag keys in a request with the keys you specified in the policy. For example, you can allow the principal to pass only session tags with the specified tag keys. This condition key limits the maximum set of session tags that can be passed.
+ `sts:TransitiveTagKeys` - Compares the transitive session tag keys in the request with those specified in the policy. For example, you can write a policy to allow a principal to set only specific tags as transitive. Transitive tags persist during role chaining. For more information, see [Chaining roles with session tags](#id_session-tags_role-chaining).

For example, the following [role trust policy](id_roles.md#term_trust-policy) allows the `test-session-tags` user to assume the role with the attached policy. When that user assumes the role, they must use the AWS CLI or AWS API to pass the three required session tags and the required [external ID](id_roles_common-scenarios_third-party.md#id_roles_third-party_external-id). Additionally, the user can choose to set the `Project` and `Department` tags as transitive.

**Example role trust policy for session tags**    
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowIamUserAssumeRole",
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Principal": {"AWS": "arn:aws:iam::123456789012:user/test-session-tags"},
            "Condition": {
              "StringLike": {
                    "aws:RequestTag/Project": "*",
                    "aws:RequestTag/CostCenter": "*",
                    "aws:RequestTag/Department": "*"
                },
                "StringEquals": {"sts:ExternalId": "Example987"}
            }
        },
        {
            "Sid": "AllowPassSessionTagsAndTransitive",
            "Effect": "Allow",
            "Action": "sts:TagSession",
            "Principal": {"AWS": "arn:aws:iam::123456789012:user/test-session-tags"},
            "Condition": {
                "StringLike": {
                    "aws:RequestTag/Project": "*",
                    "aws:RequestTag/CostCenter": "*"
                },
                "StringEquals": {
                    "aws:RequestTag/Department": [
                        "Engineering",
                        "Marketing"
                    ]
                },
                "ForAllValues:StringEquals": {
                    "sts:TransitiveTagKeys": [
                        "Project",
                        "Department"
                    ]
                }
            }
        }
    ]
}
```

**What does this policy do?**
+ The `AllowIamUserAssumeRole` statement allows the `test-session-tags` user to assume the role with the attached policy. When that user assumes the role, they must pass the required session tags and [external ID](id_roles_common-scenarios_third-party.md#id_roles_third-party_external-id).
  + The first condition block of this statement requires the user to pass the `Project`, `CostCenter`, and `Department` session tags. The tag values do not matter in this statement, so you can use wildcards (\$1) for the tag values. This block ensures that user passes at least these three session tags. Otherwise, the operation fails. The user can pass additional tags.
  + The second condition block requires the user to pass an [external ID](id_roles_common-scenarios_third-party.md#id_roles_third-party_external-id) with the value `Example987`.
+ The `AllowPassSessionTagsAndTransitive` statement allows the `sts:TagSession` permissions-only action. This action must be allowed before the user can pass session tags. If your policy includes the first statement without the second statement, the user can't assume the role.
  + The first condition block of this statement allows the user to pass any value for the `CostCenter` and `Project` session tags. You do this by using wildcards (\$1) for the tag value in the policy, which requires that you use the [StringLike](reference_policies_elements_condition_operators.md#Conditions_String) condition operator.
  + The second condition block allows the user to pass only the `Engineering` or `Marketing` value for the `Department` session tag.
  + The third condition block lists the maximum set of tags you can set as transitive. The user can choose to set a subset or no tags as transitive. They cannot set additional tags as transitive. You can require that they set at least one of the tags as transitive by adding another condition block that includes `"Null":{"sts:TransitiveTagKeys":"false"}`. 

## Passing session tags using AssumeRole
<a name="id_session-tags_adding-assume-role"></a>

The `AssumeRole` operation returns a set of temporary credentials you can use to access AWS resources. You can use IAM user or role credentials to call `AssumeRole`. To pass session tags while assuming a role, use the `--tags` AWS CLI option or the `Tags` AWS API parameter. 

To set tags as transitive, use the `--transitive-tag-keys` AWS CLI option or the `TransitiveTagKeys` AWS API parameter. Transitive tags persist during role chaining. For more information, see [Chaining roles with session tags](#id_session-tags_role-chaining).

The following example shows a sample request that uses `AssumeRole`. In this example, when you assume the `my-role-example` role, you create a session named `my-session`. You add the session tag key-value pairs `Project` = `Automation`, `CostCenter` = `12345`, and `Department` = `Engineering`. You also set the `Project` and `Department` tags as transitive by specifying their keys. You must pass a single value for each session tag. AWS STS does not support multi-valued session tags.

**Example AssumeRole CLI request**  

```
aws sts assume-role \
--role-arn arn:aws:iam::123456789012:role/my-role-example \
--role-session-name my-session \
--tags Key=Project,Value=Automation Key=CostCenter,Value=12345 Key=Department,Value=Engineering \
--transitive-tag-keys Project Department \
--external-id Example987
```

## Passing session tags using AssumeRoleWithSAML
<a name="id_session-tags_adding-assume-role-saml"></a>

The `AssumeRoleWithSAML` operation authenticates with SAML-based federation. This operation returns a set of temporary credentials you can use to access AWS resources. For more information about using SAML-based federation for AWS Management Console access, see [Enabling SAML 2.0 federated principals to access the AWS Management Console](id_roles_providers_enable-console-saml.md). For details about AWS CLI or AWS API access, see [SAML 2.0 federation](id_roles_providers_saml.md). For a tutorial on configuring SAML federation for your Active Directory users, see [AWS Federated Authentication with Active Directory Federation Services (ADFS)](https://aws.amazon.com/blogs/security/aws-federated-authentication-with-active-directory-federation-services-ad-fs/) in the AWS Security Blog. 

As an administrator, you can allow members of your company directory to federate into AWS using the AWS STS `AssumeRoleWithSAML` operation. To do this, you must complete the following tasks:

1. [Configure your network as a SAML provider for AWS](id_roles_providers_saml_3rd-party.md).

1. [Create a SAML provider in IAM](id_roles_providers_create_saml.md)

1. [Create a role for SAML 2.0 federation (console)](id_roles_create_for-idp_saml.md)

1. [Finish configuring the SAML IdP and create assertions for the SAML authentication response](id_roles_providers_create_saml_assertions.md)

AWS includes identity providers with certified end-to-end experience for session tags with their identity solutions. To learn how to use these identity providers to configure session tags, see [Integrate third-party SAML solution providers with AWS](id_roles_providers_saml_3rd-party.md).

To pass SAML attributes as session tags, include the `Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/PrincipalTag:{TagKey}`. Use the `AttributeValue` element to specify the value of the tag. Include a separate `Attribute` element for each session tag.

For example, assume that you want to pass the following identity attributes as session tags:
+ `Project:Automation`
+ `CostCenter:12345`
+ `Department:Engineering`

To pass these attributes, include the following elements in your SAML assertion.

**Example snippet of a SAML assertion**  

```
<Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:Project">
  <AttributeValue>Automation</AttributeValue>
</Attribute>
<Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:CostCenter">
  <AttributeValue>12345</AttributeValue>
</Attribute>
<Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:Department">
  <AttributeValue>Engineering</AttributeValue>
</Attribute>
```

To set the preceding tags as transitive, include another `Attribute` element with the `Name` attribute set to `https://aws.amazon.com/SAML/Attributes/TransitiveTagKeys`. Transitive tags persist during role chaining. For more information, see [Chaining roles with session tags](#id_session-tags_role-chaining).

To set the `Project` and `Department` tags as transitive, use the following multi-valued attribute:

**Example snippet of a SAML assertion**  

```
<Attribute Name="https://aws.amazon.com/SAML/Attributes/TransitiveTagKeys">
  <AttributeValue>Project</AttributeValue>
  <AttributeValue>Department</AttributeValue>
</Attribute>
```

## Passing session tags using AssumeRoleWithWebIdentity
<a name="id_session-tags_adding-assume-role-idp"></a>

Use OpenID Connect (OIDC)-compliant federation to authenticate the `AssumeRoleWithWebIdentity` operation. This operation returns a set of temporary credentials you can use to access AWS resources. For more information about using web identity federation for AWS Management Console access, see [OIDC federation](id_roles_providers_oidc.md).

To pass session tags from OpenID Connect (OIDC), you must include the session tags in the JSON Web Token (JWT) when you submit the `AssumeRoleWithWebIdentity` request. To learn more about OIDC tokens and claims, see [Using Tokens with User Pools](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) in the *Amazon Cognito Developer Guide*.

AWS supports two claim formats for including session tags in the JWT: 
+ Nested claim format
+ Flattened claim format

### Nested claim format
<a name="id_session-tags_adding-assume-role-idp-nested-format"></a>

The nested claim format uses a structure within the `https://aws.amazon.com/tags` namespace in the JWT. In this format:
+ Principal tags are represented as a nested object under the `principal_tags` key.
+ Each principal tag is a single string value.
+ Transitive tag keys are represented in an array under the `transitive_tag_keys` key.
+ Both `principal_tags` and `transitive_tag_keys` are nested under the `https://aws.amazon.com/tags` namespace.

The following example demonstrates a decoded JWT using the nested object format: 

**Example decoded JSON Web Token using the nested claim format**  

```
{
    "sub": "johndoe",
    "aud": "ac_oic_client",
    "jti": "ZYUCeRMQVtqHypVPWAN3VB",
    "iss": "https://xyz.com",
    "iat": 1566583294,
    "exp": 1566583354,
    "auth_time": 1566583292,
    "https://aws.amazon.com/tags": {
        "principal_tags": {
            "Project": ["Automation"],
            "CostCenter": ["987654"],
            "Department": ["Engineering"]
        },
        "transitive_tag_keys": [
            "Project",
            "CostCenter"
        ]
    }
}
```

### Flattened claim format
<a name="id_session-tags_adding-assume-role-idp-flattened-format"></a>

The flattened claim format is compatible with identity providers that don't support nested objects in JWT claims, such as Microsoft Entra ID. In this format:
+ Principal tags are represented as separate claims with the prefix `https://aws.amazon.com/tags/principal_tags/`. 
+ Each principal tag is a single string value.
+ Transitive tag keys are represented in a single claim as an array of strings with the prefix `https://aws.amazon.com/tags/transitive_tag_keys`.

Now, let's look at how the same information is represented using the flattened claim format:

**Example decoded JSON Web Token using the flattened claim format**  

```
{
    "sub": "johndoe",
    "aud": "ac_oic_client",
    "jti": "ZYUCeRMQVtqHypVPWAN3VB",
    "iss": "https://xyz.com",
    "iat": 1566583294,
    "exp": 1566583354,
    "auth_time": 1566583292,
    "https://aws.amazon.com/tags/principal_tags/Project": "Automation",
    "https://aws.amazon.com/tags/principal_tags/CostCenter": "987654",
    "https://aws.amazon.com/tags/principal_tags/Department": "Engineering",
    "https://aws.amazon.com/tags/transitive_tag_keys": [
        "Project",
        "CostCenter"
    ]
}
```

Both decoded JWT examples show a call to `AssumeRoleWithWebIdentity` with the `Project`, `CostCenter`, and `Department` session tags. Both tokens set the `Project` and `CostCenter` tags as transitive. Transitive tags persist during role chaining. For more information, see [Chaining roles with session tags](#id_session-tags_role-chaining).

The flattened claim format achieves the same result as the nested claim format but uses a flattened structure for tags. It allows you to include session tags in environments where nested JSON objects are not supported in JWT claims. When using either format, ensure that your identity provider is configured to issue tokens with the appropriate claim structures. AWS supports both claim formats, so you can choose the one that best fits your identity provider's specific requirements.

## Passing session tags using GetFederationToken
<a name="id_session-tags_adding-getfederationtoken"></a>

The `GetFederationToken` allows you to federate your user. This operation returns a set of temporary credentials you can use to access AWS resources. To add tags to your federated user session, use the `--tags` AWS CLI option or the `Tags` AWS API parameter. You can't set session tags as transitive when you use `GetFederationToken`, because you can't use the temporary credentials to assume a role. You cannot use role chaining in this case. 

The following example shows a sample request using `GetFederationToken`. In this example, when you request the token, you create a session named `my-fed-user`. You add the session tag key-value pairs `Project` = `Automation` and `Department` = `Engineering`.

**Example GetFederationToken CLI request**  

```
aws sts get-federation-token \
--name my-fed-user \
--tags key=Project,value=Automation key=Department,value=Engineering
```

When you use the temporary credentials returned by the `GetFederationToken` operation, the session principal tags include the user tags and the passed session tags.

## Chaining roles with session tags
<a name="id_session-tags_role-chaining"></a>

You can assume one role and then use the temporary credentials to assume another role. You can continue from session to session. This is called [role chaining](id_roles.md#iam-term-role-chaining). When you pass session tags while assuming a role, you can set the keys as transitive. This ensures that those session tags pass to subsequent sessions in a role chain. You cannot set role tags as transitive. To pass these tags to subsequent sessions, specify them as session tags.

**Note**  
Transitive tags persist during role chaining and replace matching `ResourceTag` values after the evaluation of the role trust policy.

The following example shows how AWS STS passes session tags, transitive tags, and role tags into subsequent sessions in a role chain.

In this example role chaining scenario, you use an IAM user access key in the AWS CLI to assume a role named `Role1`. You then use the resulting session credentials to assume a second role named `Role2`. You can then use the second session credentials to assume a third role named `Role3`. These requests occur as three separate operations. Each role is already tagged in IAM. And during each request, you pass additional session tags.

![\[Role chaining\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/session-tags-chaining-simple.png)


When you chain roles, you can ensure that tags from an earlier session persist to the later sessions. To do this using the `assume-role` CLI command, you must pass the tag as a session tag and set the tag as transitive. You pass the tag `Star` = `1` as a session tag. The command also attaches the tag `Heart` = `1` to the role and applies as a principal tag when you use the session. However, you also want the `Heart` = `1` tag to automatically pass to the second or third session. To do that, you manually include it as a session tag. The resulting session principal tags include both of these tags, and sets them as transitive.

![\[Assuming the first role in a role chain\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/session-tags-chaining-role1.png)


You perform this request using the following AWS CLI command:

**Example AssumeRole CLI request**  

```
aws sts assume-role \
--role-arn arn:aws:iam::123456789012:role/Role1 \
--role-session-name Session1 \
--tags Key=Star,Value=1 Key=Heart,Value=1 \
--transitive-tag-keys Star Heart
```

You then use the credentials for that session to assume `Role2`. The command attaches the tag `Sun` = `2` to the second role and applies as a principal tag when you use the second session. The `Heart` and `Star` tags inherits the transitive session tags in the first session. The second session resulting principal tags are `Heart` = `1`, `Star` = `1`, and `Sun` = `2`. `Heart` and `Star` continue to be transitive. The `Sun` tag attached to `Role2` is not marked as transitive because it is not a session tag. Future sessions do not inherit this tag. 

![\[Assuming the second role in a role chain\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/session-tags-chaining-role2.png)


You perform this second request using the following AWS CLI command:

**Example AssumeRole CLI request**  

```
aws sts assume-role \
--role-arn arn:aws:iam::123456789012:role/Role2 \
--role-session-name Session2
```

You then use the second session credentials to assume `Role3`. The principal tags for the third session come from any new session tags, the inherited transitive session tags, and the role tags. The `Heart` = `1` and `Star` = `1` tags on the second session are inherited from the transitive session tag in the first session. If you try to pass the `Sun` = `2` session tag, the operation fails. The inherited `Star` = 1 session tag overrides the role `Star` = `3` tag. In role chaining, the value of a transitive tag overrides the role matching the `ResourceTag` value after the evaluation of the role trust policy. In this example, if `Role3` uses `Star` as a `ResourceTag` in the role trust policy, and sets `ResourceTag` value to the transitive tag value from the calling role session. The role `Lightning` tag also applies to the third session, and not set as transitive.

![\[Assuming the third role in a role chain\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/session-tags-chaining-role3.png)


You perform the third request using the following AWS CLI command:

**Example AssumeRole CLI request**  

```
aws sts assume-role \
--role-arn arn:aws:iam::123456789012:role/Role3 \
--role-session-name Session3
```

## Using session tags for ABAC
<a name="id_session-tags_using-abac"></a>

Attribute-based access control (ABAC) uses an authorization strategy that defines permissions based on tag attributes. 

If your company uses an OIDC or SAML-based identity provider (IdP) to manage user identities, you can configure your assertion to pass session tags to AWS. For example, with corporate user identities, when your employees federate into AWS, AWS applies their attributes to their resulting principal. You can then use ABAC to allow or deny permissions based on those attributes. For details, see [IAM tutorial: Use SAML session tags for ABAC](tutorial_abac-saml.md).

For more information about using IAM Identity Center with ABAC, see [Attributes for access control](https://docs.aws.amazon.com/singlesignon/latest/userguide/attributesforaccesscontrol.html) in the *AWS IAM Identity Center User Guide*.

## Viewing session tags in CloudTrail
<a name="id_session-tags_ctlogs"></a>

You can use AWS CloudTrail to view the requests used to assume roles or federate users. The CloudTrail log file includes information about the principal tags for the assumed-role or federated user session. For more information, see [Logging IAM and AWS STS API calls with AWS CloudTrail](cloudtrail-integration.md).

For example, assume that you make an AWS STS `AssumeRoleWithSAML` request, pass session tags, and set those tags as transitive. You can find the following information in your CloudTrail log.

**Example AssumeRoleWithSAML CloudTrail log**  

```
    "requestParameters": {
        "sAMLAssertionID": "_c0046cEXAMPLEb9d4b8eEXAMPLE2619aEXAMPLE",
        "roleSessionName": "MyRoleSessionName",
        "principalTags": {
            "CostCenter": "987654",
            "Project": "Unicorn"
        },
        "transitiveTagKeys": [
            "CostCenter",
            "Project"
        ],
        "durationSeconds": 3600,
        "roleArn": "arn:aws:iam::123456789012:role/SAMLTestRoleShibboleth",
        "principalArn": "arn:aws:iam::123456789012:saml-provider/Shibboleth"
    },
```

You can view the following example CloudTrail logs to view events that use session tags.
+ [Example AWS STS role chaining API event in CloudTrail log file](cloudtrail-integration.md#stscloudtrailexample-assumerole)
+ [Example SAML AWS STS API event in CloudTrail log file](cloudtrail-integration.md#stscloudtrailexample_saml)
+ [Example OIDC AWS STS API event in CloudTrail log file](cloudtrail-integration.md#stscloudtrailexample_web-identity)