IAM and AWS STS condition context keys

Works with ARN operators.

Specifies the ARN of the resource to which this role will be associated at the destination service. The resource usually belongs to the service to which the principal is passing the role. Sometimes, the resource might belong to a third service. For example, you might pass a role to Amazon EC2 Auto Scaling that they use on an Amazon EC2 instance. In this case, the condition would match the ARN of the Amazon EC2 instance.

This condition key applies to only the PassRole action in a policy. It can't be used to limit any other action.

Use this condition key in an identity-based policy to allow an entity to pass a role, but only if that role is associated with the specified resource. For example, you can allow an IAM user or role to pass any role to the Amazon EC2 service to be used with instances in the AWS account. The IAM user or role would not be allowed to pass roles to other services.

{
    "Effect": "Allow",
    "Action": "iam:PassRole",
    "Resource": "*",
    "Condition": {
        "StringEquals": {
            "iam:PassedToService": "ec2.amazonaws.com"
        },
        "ArnLike": {
            "iam:AssociatedResourceARN": [
                "arn:aws:ec2:*:111122223333:instance/*"
            ]
        }
    }
}

Works with string operators.

Specifies the AWS service to which this role is attached.

This condition key is supported by the CreateServiceLinkedRole API operation.

In this example, you allow an entity to create a service-linked role using the CreateServiceLinkedRole API operation if the service name is access-analyzer.amazonaws.com.

Works with string operators.

Checks the MFA device FIDO certification level at the time of registration of a FIDO security key. The device certification is retrieved from the FIDO Alliance Metadata Service (MDS). If the certification status or level of your FIDO security key changes, it will not be updated unless the device is unregistered and registered again to fetch the updated certification information.

Possible values of L1, L1plus, L2, L2plus, L3, L3plus

In this example, you register a security key and retrieve the FIDO Level 1 plus certification for your device.

Works with string operators.

Checks the MFA device FIPS-140-2 validation certification level at the time of registration of a FIDO security key. The device certification is retrieved from the FIDO Alliance Metadata Service (MDS). If the certification status or level of your FIDO security key changes, it will not be updated unless the device is unregistered and registered again to fetch the updated certification information.

Possible values of L1, L2, L3, L4

In this example, you register a security key and retrieve the FIPS-140-2 Level 2 certification for your device.

Works with string operators.

Checks the MFA device FIPS-140-3 validation certification level at the time of registration of a FIDO security key. The device certification is retrieved from the FIDO Alliance Metadata Service (MDS). If the certification status or level of your FIDO security key changes, it will not be updated unless the device is unregistered and registered again to fetch the updated certification information.

Possible values of L1, L2, L3, L4

In this example, you register a security key and retrieve the FIPS-140-3 Level 3 certification for your device.

Works with string operators.

Checks that the policy with the specified AWS Organizations ID matches the policy used in the request. To view an example IAM policy that uses this condition key, see IAM: View service last accessed information for an AWS Organizations policy.

Works with string operators.

Specifies the service principal of the service to which a role can be passed. This condition key applies to only the PassRole action in a policy. It can't be used to limit any other action.

When you use this condition key in a policy, specify the service using a service principal. A service principal is the name of a service that can be specified in the Principal element of a policy. This is the usual format: SERVICE_NAME_URL.amazonaws.com.

You can use iam:PassedToService to restrict your users so that they can pass roles only to specific services. For example, a user might create a service role that trusts CloudWatch to write log data to an Amazon S3 bucket on their behalf. Then the user must attach a permissions policy and a trust policy to the new service role. In this case, the trust policy must specify cloudwatch.amazonaws.com in the Principal element. To view a policy that allows the user to pass the role to CloudWatch, see IAM: Pass an IAM role to a specific AWS service.

By using this condition key, you can ensure that users create service roles only for the services that you specify. For example, if a user with the preceding policy attempts to create a service role for Amazon EC2, the operation will fail. The failure occurs because the user does not have permission to pass the role to Amazon EC2.

Sometimes you pass a role to a service that then passes the role to a different service. iam:PassedToService includes only the final service that assumes the role, not the intermediate service that passes the role.

Works with ARN operators.

Checks that the specified policy is attached as permissions boundary on the IAM principal resource. For more information, see Permissions boundaries for IAM entities

Works with ARN operators.

Checks the Amazon Resource Name (ARN) of a managed policy in requests that involve a managed policy. For more information, see Controlling access to policies.

Works with string operators.

Checks the current state of MFA device enablement.

Possible values of Create or Activate.

In this example, you register a security key and retrieve the FIPS-140-3 Level 1 certification for your device.

Works with string operators.

Checks that the tag attached to the identity resource (user or role) matches the specified key name and value.

You can add custom attributes to IAM resources in the form of a key-value pair. For more information about tags for IAM resources, see Tags for AWS Identity and Access Management resources. You can use ResourceTag to control access to AWS resources, including IAM resources. However, because IAM does not support tags for groups, you cannot use tags to control access to groups.

This example shows how you might create an identity-based policy that allows deleting users with the status=terminated tag. To use this policy, replace the italicized placeholder text in the example policy with your own information. Then, follow the directions in create a policy or edit a policy.

Works with numeric operators.

This condition key limits the creation of service-specific credentials based on their expiration settings. It allows you to control the maximum age, in days, of service-specific credentials that can be created.

The valid range for days is 1 to 36600 (minimum 1 day, maximum 36600 days).

This condition key is supported by the CreateServiceSpecificCredential API operation.

In this example, you allow a user to create service-specific credentials for the Amazon Bedrock service only if they expire within 90 days.

Works with string operators.

Specifies which AWS services can be used when managing service-specific credentials. This condition key allows you to restrict which AWS services are permitted when managing service-specific credentials.

This condition key is supported by the following API operations:

The following services are supported for service-specific credentials with their exact value formatting:

In this example, you allow a user to create service-specific credentials using the CreateServiceSpecificCredential API operation only for the Amazon Bedrock service.

Works with string operators.

An endpoint URL to which SAML assertions are presented. The value for this key comes from the SAML Recipient field in the assertion, not the Audience field.

Works with string operators.

This is a commonName attribute.

Works with string operators.

This is an eduOrg attribute.

Works with string operators.

This represents the principal that was used to assume the role. The format is account-ID/provider-friendly-name, such as 123456789012/SAMLProviderName. The account-ID value refers to the account that owns the SAML provider.

Works with string operators.

This is an eduPerson attribute.

Works with string operators.

This is an eduPerson attribute.

Works with string operators.

This is an eduPerson attribute.

Works with string operators.

This is an eduPerson attribute.

Works with string operators.

This is an eduPerson attribute.

Works with string operators.

This is an eduPerson attribute.

Works with string operators.

This is an eduPerson attribute.

Works with string operators.

This is an eduPerson attribute.

Works with string operators.

This is an eduPerson attribute.

Works with string operators.

This is an eduPerson attribute.

Works with string operators.

This is an eduPerson attribute.

Works with string operators.

This is an eduOrg attribute.

Works with string operators.

This is an eduOrg attribute.

Works with string operators.

This is an eduOrg attribute.

Works with string operators.

This is an eduOrg attribute.

Works with string operators.

This is an eduOrg attribute.

Works with string operators.

This is a givenName attribute.

Works with string operators.

The issuer, which is represented by a URN.

Works with string operators.

This is a mail attribute.

Works with string operators.

This is a name attribute.

Works with string operators.

A hash value based on the friendly name of the SAML provider. The value is the concatenation of the following values, in order and separated by a '/' character:

The concatenation of the account ID and friendly name of the SAML provider is available to IAM policies as the key saml:doc. For more information, see Uniquely identifying users in SAML-based federation.

Works with string operators.

This is an organizationStatus attribute.

Works with string operators.

This is a primaryGroupSID attribute.

Works with string operators.

This is the subject of the claim, which includes a value that uniquely identifies an individual user within an organization (for example, _cbb88bf52c2510eabe00c1642d4643f41430fe25e3).

Works with string operators.

This key can have the value persistent, transient, or consist of the full Format URI from the Subject and NameID elements used in your SAML assertion. A value of persistent indicates that the value in saml:sub is the same for a user between sessions. If the value is transient, the user has a different saml:sub value for each session. For information about the NameID element's Format attribute, see Configure SAML assertions for the authentication response.

Works with string operators.

This is a surnameuid attribute.

Works with string operators.

This is a uid attribute.

Works with string operators.

This is an x500UniqueIdentifier attribute.

Works with string operators.

This is the subject of the claim, which includes a value that uniquely identifies an individual user within an organization (for example, _cbb88bf52c2510eabe00c1642d4643f41430fe25e3).

Works with string operators.

Use this key to specify a service where a bearer token can be used. When you use this condition key in a policy, specify the service using a service principal. A service principal is the name of a service that can be specified in the Principal element of a policy. For example, codeartifact.amazonaws.com is the AWS CodeArtifact service principal.

Availability – This key is present in requests that get a bearer token. You cannot make a direct call to AWS STS to get a bearer token. When you perform some operations in other services, the service requests the bearer token on your behalf.

Some AWS services require that you have permission to get an AWS STS service bearer token before you can access their resources programmatically. For example, AWS CodeArtifact requires principals to use bearer tokens to perform some operations. The aws codeartifact get-authorization-token command returns a bearer token. You can then use the bearer token to perform AWS CodeArtifact operations. For more information about bearer tokens, see Service bearer tokens.

You can use this condition key to allow principals to get a bearer token for use with a specific service.

Works with numeric operators.

Use this key to specify the duration (in seconds) that a principal can use when getting an AWS STS bearer token.

Availability – This key is present in requests that get a bearer token. You cannot make a direct call to AWS STS to get a bearer token. When you perform some operations in other services, the service requests the bearer token on your behalf. The key is not present for AWS STS assume-role operations.

Some AWS services require that you have permission to get an AWS STS service bearer token before you can access their resources programmatically. For example, AWS CodeArtifact requires principals to use bearer tokens to perform some operations. The aws codeartifact get-authorization-token command returns a bearer token. You can then use the bearer token to perform AWS CodeArtifact operations. For more information about bearer tokens, see Service bearer tokens.

Works with string operators.

Use this key to require that a principal provide a specific identifier when assuming an IAM role.

Availability – This key is present in the request when the principal provides an external ID while assuming a role using the AWS CLI or AWS API.

A unique identifier that might be required when you assume a role in another account. If the administrator of the account to which the role belongs provided you with an external ID, then provide that value in the ExternalId parameter. This value can be any string, such as a passphrase or account number. The primary function of the external ID is to address and prevent the confused deputy problem. For more information about the external ID and the confused deputy problem, see Access to AWS accounts owned by third parties.

The ExternalId value must have a minimum of 2 characters and a maximum of 1,224 characters. The value must be alphanumeric without white space. It can also include the following symbols: plus (+), equal (=), comma (,), period (.), at (@), colon (:), forward slash (/), and hyphen (-).

Works with string operators.

Use this key to compare the session context key-value pairs that are embedded in the trusted token issuer signed context assertion passed in the request with the context key-values specified in the role trust policy.

Availability – This key is present in the request when a context assertion is provided in the ProvidedContexts request parameter while assuming a role using the AWS STS AssumeRole API operation.

This context key is formatted as "sts:RequestContext/context-key":"context-value" where context-key and context-value are a context key-value pair. When multiple context keys are embedded in the signed context assertion passed in the request, there is one context key for each key-value pair. You must grant permission for the sts:SetContext action in the role trust policy to allow a principal to set context keys within the resulting session token. To learn more about the supported IAM Identity Center context keys that can be used with this key, see AWS STS condition keys for IAM Identity Center in the AWS IAM Identity Center User Guide.

You can use this key in a role trust policy to enforce fine-grained access control based on the user or their attributes when they assume a role. After the role is assumed, activity appears in the AWS CloudTrail logs within the AdditionalEventData attribute, containing the session context key-value pairs that were set by the context provider in the assume role request. This makes it easier for administrators to differentiate between role sessions when a role is used by different principals. The key-value pairs are set by the specified context provider, not by AWS CloudTrail or AWS STS. This gives the context provider control over what context is included in the CloudTrail logs and session information.

Works with ARN operators.

Use this key to compare the context provider ARN in the request with the context provider ARN specified in the role trust policy.

Availability – This key is present in the request when a context assertion is provided in the ProvidedContexts request parameter while assuming a role using the AWS STS AssumeRole API operation.

The following example condition checks that the context provider ARN passed in the request matches the ARN specified in the role trust policy condition. We recommend you add a null check with ForAllValues to prevent missing context keys or context keys with empty values from evaluating to true. For details, see Condition operator to check existence of condition keys .

Works with string operators.

Use this key to compare the session name that a principal specifies when assuming a role with the value that is specified in the policy.

Availability – This key is present in the request when the principal assumes the role using the AWS Management Console, any assume-role CLI command, or any AWS STS AssumeRole API operation.

You can use this key in a role trust policy to require that your users provide a specific session name when they assume a role. For example, you can require that IAM users specify their own user name as their session name. After the IAM user assumes the role, activity appears in AWS CloudTrail logs with the session name that matches their user name. This makes it easier for administrators to differentiate between role sessions when a role is used by different principals.

The following role trust policy requires that IAM users in account 111122223333 provide their IAM user name as the session name when they assume the role. This requirement is enforced using the aws:username condition variable in the condition key. This policy allows IAM users to assume the role to which the policy is attached. This policy does not allow anyone using temporary credentials to assume the role because the username variable is present for only IAM users.

When an administrator views the AWS CloudTrail log for an action, they can compare the session name to the user names in their account. In the following example, the user named matjac performed the operation using the role named MateoRole. The administrator can then contact Mateo Jackson, who has the user named matjac.

    "assumedRoleUser": {
        "assumedRoleId": "AROACQRSTUVWRAOEXAMPLE:matjac",
        "arn": "arn:aws:sts::111122223333:assumed-role/MateoRole/matjac"
    }

If you allow cross-account access using roles, then users in one account can assume a role in another account. The ARN of the assumed role user listed in CloudTrail includes the account where the role exists. It does not include the account of the user that assumed the role. Users are unique only within an account. Therefore, we recommend that you use this method for checking CloudTrail logs only for roles that are assumed by users in accounts that you administer. Your users might use the same user name in multiple accounts.

Works with string operators.

Use this key to compare the source identity that a principal specifies when assuming a role with the value that is specified in the policy.

Availability – This key is present in the request when the principal provides a source identity while assuming a role using any AWS STS assume-role CLI command, or AWS STS AssumeRole API operation.

You can use this key in a role trust policy to require that your users set a specific source identity when they assume a role. For example, you can require your workforce or federated identities to specify a value for source identity. You can configure your identity provider (IdP) to use one of the attributes that are associated with your users, like a user name or email as the source identity. The IdP then passes the source identity as an attribute in the assertions or claims that it sends to AWS. The value of the source identity attribute identifies the user or application who is assuming the role.

After the user assumes the role, activity appears in AWS CloudTrail logs with the source identity value that was set. This makes it easier for administrators to determine who or what performed actions with a role in AWS. You must grant permissions for the sts:SetSourceIdentity action to allow an identity to set a source identity.

Unlike sts:RoleSessionName, after the source identity is set, the value cannot be changed. It is present in the request context for all actions taken with the role by the source identity. The value persists into subsequent role sessions when you use the session credentials to assume another role. Assuming one role from another is called role chaining.

You can use the aws:SourceIdentity global condition key to further control access to AWS resources based on the value of source identity in subsequent requests.

The following role trust policy allows the IAM user AdminUser to assume a role in account 111122223333. It also grants permission to the AdminUser to set a source identity, as long as the source identity set is DiegoRamirez.

To learn more about using source identity information, see Monitor and control actions taken with assumed roles.

Works with ARN operators.

Use this key to compare the policy ARN in an sts:AssumeRoot request with the policy ARN specified in the policy.

Availability – This key is present in the request when you make a request using sts:AssumeRoot.

Administrators can use this condition key in IAM policies to restrict specific roles or users within the management account or delegated administrator account from performing certain actions when assuming root credentials. For more information, see Perform a privileged task on an AWS Organizations member account.

Works with string operators.

Use this key to compare the transitive session tag keys in the request with those specified in the policy.

Availability – This key is present in the request when you make a request using temporary security credentials. These include credentials created using any assume-role operation, or the GetFederationToken operation.

When you make a request using temporary security credentials, the request context includes the aws:PrincipalTag context key. This key includes a list of session tags, transitive session tags, and role tags. Transitive session tags are tags that persist into all subsequent sessions when you use the session credentials to assume another role. Assuming one role from another is called role chaining.

You can use this condition key in a policy to require setting specific session tags as transitive when assuming a role or federating a user.