Monitor and control actions taken with assumed roles
An IAM role is an object in IAM that is assigned permissions. When you assume that role using an IAM identity or an identity from outside of Amazon, you receive a session with the permissions that are assigned to the role.
When you perform actions in Amazon, the information about your session can be logged to Amazon CloudTrail for your account administrator to monitor. Administrators can configure roles to require identities to pass a custom string that identifies the person or application that is performing actions in Amazon. This identity information is stored as the source identity in Amazon CloudTrail. When the administrator reviews activity in CloudTrail, they can view the source identity information to determine who or what performed actions with assumed role sessions.
After a source identity is set, it is present in requests for any Amazon action taken during the role session. The value that is set persists when a role is used to assume another role through the Amazon CLI or Amazon API, known as role chaining. The value that is set cannot be changed during the role session. Administrators can configure granular permissions based on the presence or value of the source identity to further control Amazon actions that are taken with shared roles. You can decide whether the source identity attribute can be used, whether it is required, and what value can be used.
The way that you use source identity differs from role session name and session tags in an important way. The source identity value can't be changed after it is set, and it persists for any additional actions that are taken with the role session. Here's how you can use session tags and role session name:
-
Session tags – You can pass session tags when you assume a role or federate a user. Session tags are present when a role is assumed. You can define policies that use tag condition keys to grant permissions to your principals based on their tags. Then you can use CloudTrail to view the requests made to assume roles or federate users. To learn more about session tags, see Pass session tags in Amazon STS.
-
Role session name – You can use the
sts:RoleSessionName
condition key in a role trust policy to require that your users provide a specific session name when they assume a role. Role session name can be used to differentiate role sessions when a role is used by different principals. To learn more about role session name, see sts:RoleSessionName.
We recommend that you use source identity when you want to control the identity that assumes a role. Source identity is also useful for mining CloudTrail logs to determine who used the role to perform actions.
Topics
- Setting up to use source identity
- Things to know about source identity
- Permissions required to set source identity
- Specifying a source identity when assuming a role
- Using source identity with AssumeRole
- Using source identity with AssumeRoleWithSAML
- Using source identity with AssumeRoleWithWebIdentity
- Control access using source identity information
- Viewing source identity in CloudTrail
Setting up to use source identity
The way that you set up to use source identity depends on the method used when your
roles are assumed. For example, your IAM users might assume roles directly using the
AssumeRole
operation. If you have enterprise identities, also known as
workforce identities, they might access your Amazon resources using
AssumeRoleWithSAML
. If end users access your mobile or web
applications, they might do so using AssumeRoleWithWebIdentity
. The
following is a high-level workflow overview to help you understand how you can set up to
utilize source identity information in your existing environment.
-
Configure test users and roles – Using a preproduction environment, configure test users and roles and configure their policies to allow setting a source identity.
If you use an identity provider (IdP) for your federated identities, configure your IdP to pass a user attribute of your choice for source identity in the assertion or token.
-
Assume the role – Test assuming roles and passing a source identity with the users and roles that you set up for testing.
-
Review CloudTrail – Review the source identity information for your test roles in your CloudTrail logs.
-
Train your users – After you've tested in your preproduction environment, ensure that your users know how to pass in the source identity information, if necessary. Set a deadline for when you will require your users to provide a source identity in your production environment.
-
Configure production policies – Configure your policies for your production environment, and then add them to your production users and roles.
-
Monitor activity – Monitor your production role activity using CloudTrail logs.
Things to know about source identity
Keep the following in mind when working with source identity.
-
Trust policies for all roles connected to an identity provider (IdP) must have the
sts:SetSourceIdentity
permission. For roles that don't have this permission in the role trust policy, theAssumeRole*
operation will fail. If you don't want to update the role trust policy for each role, you can use a separate IdP instance for passing source identity. Then add thests:SetSourceIdentity
permission to only the roles that are connected to the separate IdP. -
When an identity sets a source identity, the
sts:SourceIdentity
key is present in the request. For subsequent actions taken during the role session, theaws:SourceIdentity
key is present in the request. Amazon doesn’t control the value of the source identity in either thests:SourceIdentity
oraws:SourceIdentity
keys. If you choose to require a source identity, you must choose an attribute that you want your users or IdP to provide. For security purposes, you must ensure that you can control how those values are provided. -
The value of source identity must be between 2 and 64 characters long, can contain only alphanumeric characters, underscores, and the following characters: . , + = @ - (hyphen). You cannot use a value that begins with the text
aws:
. This prefix is reserved for Amazon internal use. -
The source identity information is not captured by CloudTrail when an Amazon service or service-linked role carries out an action on behalf of a federated or workforce identity.
Important
You cannot switch to a role in the Amazon Web Services Management Console that requires a source identity to be
set when the role is assumed. To assume such a role, you can use the Amazon CLI or Amazon
API to call the AssumeRole
operation and specify the source identity
parameter.
Permissions required to set source identity
In addition to the action that matches the API operation, you must have the following permissions-only action in your policy:
sts:SetSourceIdentity
-
To specify a source identity, principals (IAM users and roles) must have permissions to
sts:SetSourceIdentity
. As the administrator, you can configure this in the role trust policy and in the principal’s permissions policy. -
When you assume a role with another role, called role chaining, permissions for
sts:SetSourceIdentity
are required in both the permissions policy of the principal who is assuming the role and in the role trust policy of the target role. Otherwise, the assume role operation will fail. -
When using source identity, the role trust policies for all roles connected to an IdP must have the
sts:SetSourceIdentity
permission. TheAssumeRole*
operation will fail for any role connected to an IdP 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 source identity and add thests:SetSourceIdentity
permission to only the roles that are connected to the separate IdP. -
To set a source identity across account boundaries, you must include the
sts:SetSourceIdentity
permission in two places. It must be in the permissions policy of the principal in the originating account and in the role trust policy of the role in the target account. You might need to do this, for example, when a role is used to assume a role in another account with role chaining.
As the account administrator, imagine that you want to allow the IAM user
DevUser
in your account to assume the Developer_Role
in
the same account. But you want to allow this action only if the user has set the source
identity to their IAM user name. You can attach the following policy to the IAM
user.
Example identity-based policy attached to DevUser
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AssumeRole", "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws-cn:iam::
123456789012
:role/Developer_Role
" }, { "Sid": "SetAwsUserNameAsSourceIdentity", "Effect": "Allow", "Action": "sts:SetSourceIdentity", "Resource": "arn:aws-cn:iam::123456789012
:role/Developer_Role
", "Condition": { "StringLike": { "sts:SourceIdentity": "${aws:username}" } } } ] }
To enforce the acceptable source identity values, you can configure the following role
trust policy. The policy gives the IAM user DevUser
permissions to assume
the role and set a source identity. The sts:SourceIdentity
condition key
defines the acceptable source identity value.
Example role trust policy for source identity
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowDevUserAssumeRole", "Effect": "Allow", "Principal": { "AWS": "arn:aws-cn:iam::
123456789012
:user/DevUser
" }, "Action": [ "sts:AssumeRole", "sts:SetSourceIdentity" ], "Condition": { "StringEquals": { "sts:SourceIdentity": "DevUser
" } } } ] }
Using the credentials for the IAM user DevUser
, the user attempts to
assume the DeveloperRole
using the following Amazon CLI request.
Example AssumeRole CLI request
aws sts assume-role \ --role-arn arn:aws-cn:iam::123456789012:role/Developer_Role \ --role-session-name Dev-project \ --source-identity DevUser \
When Amazon evaluates the request, the request context contains the
sts:SourceIdentity
of DevUser
.
Specifying a source identity when assuming a role
You can specify a source identity when you use one of the Amazon STS
AssumeRole*
API operations to get temporary security credentials for a
role. The API operation that you use differs depending on your use case. For example, if
you use IAM roles to give IAM users access to Amazon resources that they don’t
normally have access to, you might use the AssumeRole
operation. If you use
enterprise identity federation to manage your workforce users, you might use the
AssumeRoleWithSAML
operation. If you use OIDC federation to
allow end users to access your mobile or web applications, you might use the
AssumeRoleWithWebIdentity
operation. The following sections explain how
to use source identity with each operation. To learn more about common scenarios for
temporary credentials, see Common scenarios for temporary credentials.
Using source identity with AssumeRole
The AssumeRole
operation returns a set of temporary credentials that you
can use to access Amazon resources. You can use IAM user or role credentials to call
AssumeRole
. To pass source identity while assuming a role, use the
-–source-identity
Amazon CLI option or the SourceIdentity
Amazon
API parameter. The following example shows how to specify the source identity using the
Amazon CLI.
Example AssumeRole CLI request
aws sts assume-role \ --role-arn arn:aws-cn:iam::123456789012:role/developer \ --role-session-name Audit \ --source-identity Admin \
Using source identity with AssumeRoleWithSAML
The principal calling the AssumeRoleWithSAML
operation is authenticated
using SAML-based federation. This operation returns a set of temporary credentials that
you can use to access Amazon resources. For more information about using SAML-based
federation for Amazon Web Services Management Console access, see Enabling SAML 2.0 federated users to
access the Amazon Web Services Management Console. For details about Amazon CLI or
Amazon API access, see SAML 2.0 federation. For a tutorial of setting up SAML
federation for your Active Directory users, see Amazon Federated Authentication with Active Directory Federation Services
(ADFS)
As an administrator, you can allow members of your company directory to federate into
Amazon using the Amazon STS AssumeRoleWithSAML
operation. To do this, you must
complete the following tasks:
To set a SAML attribute for source identity, include the Attribute
element with the Name
attribute set to
https://aws.amazon.com/SAML/Attributes/SourceIdentity
. Use the
AttributeValue
element to specify the value of the source identity. For
example, assume that you want to pass the following identity attribute as the source
identity.
SourceIdentity:DiegoRamirez
To pass this attribute, include the following element in your SAML assertion.
Example snippet of a SAML assertion
<Attribute Name="http://www.amazonaws.cn/SAML/Attributes/SourceIdentity"> <AttributeValue>DiegoRamirez</AttributeValue> </Attribute>
Using source identity with AssumeRoleWithWebIdentity
The principal calling the AssumeRoleWithWebIdentity
operation is
authenticated using OpenID Connect (OIDC)-compliant federation. This
operation returns a set of temporary credentials that you can use to access Amazon
resources. For more information about using OIDC federation for Amazon Web Services Management Console
access, see OIDC federation.
To pass source identity from OpenID Connect (OIDC), you must include the source
identity in the JSON Web Token (JWT). Include source identity in the https://aws.amazon.com/
namespace in the token
when you submit the AssumeRoleWithWebIdentity
request. To learn more about
OIDC tokens and claims, see Using Tokens with User Pools in the Amazon Cognito
Developer Guide.
For example, the following decoded JWT is a token that is used to call
AssumeRoleWithWebIdentity
with the Admin
source
identity.
Example decoded JSON Web Token
{ "sub": "johndoe", "aud": "ac_oic_client", "jti": "ZYUCeRMQVtqHypVPWAN3VB", "iss": "https://xyz.com", "iat": 1566583294, "exp": 1566583354, "auth_time": 1566583292, "https://aws.amazon.com/source_identity":"Admin" }
Control access using source identity information
When a source identity is initially set, the sts:SourceIdentity key is present in the request. After a source identity is set, the aws:SourceIdentity key is present in all subsequent requests made during the role session. As the administrator, you can write policies that grant conditional authorization to perform Amazon actions based on the existence or value of the source identity attribute.
Imagine that you want to require your developers to set a source identity to assume a
critical role that has permission to write to a production critical Amazon resource. Also
imagine that you grant Amazon access to your workforce identities using
AssumeRoleWithSAML
. You only want senior developers Saanvi and Diego to
have access to the role, so you create the following trust policy for the role.
Example role trust policy for source identity (SAML)
{ "Version": "2012-10-17", "Statement": [ { "Sid": "SAMLProviderAssumeRoleWithSAML", "Effect": "Allow", "Principal": { "Federated": "arn:aws-cn:iam::
111122223333
:saml-provider/name-of-identity-provider" }, "Action": [ "sts:AssumeRoleWithSAML" ], "Condition": { "StringEquals": { "SAML:aud": "https://signin.aws.amazon.com/saml" } } }, { "Sid": "SetSourceIdentitySrEngs", "Effect": "Allow", "Principal": { "Federated": "arn:aws-cn:iam::111122223333
:saml-provider/name-of-identity-provider" }, "Action": [ "sts:SetSourceIdentity" ], "Condition": { "StringLike": { "sts:SourceIdentity": [ "Saanvi", "Diego" ] } } } ] }
The trust policy contains a condition for sts:SourceIdentity
that
requires a source identity of Saanvi or Diego to assume the critical role.
Alternatively, if you use an OIDC provider for federation and users are
authenticated with AssumeRoleWithWebIdentity
, your role trust policy might
look as follows.
Example role trust policy for source identity (OIDC provider)
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws-cn:iam::
111122223333
:oidc-provider/server.example.com
" }, "Action": [ "sts:AssumeRoleWithWebIdentity", "sts:SetSourceIdentity" ], "Condition": { "StringEquals": { "server.example.com
:aud": "oidc-audience-id
" }, "StringLike": { "sts:SourceIdentity": [ "Saanvi", "Diego" ] } } } ] }
Role chaining and cross-account requirements
Imagine that you want to allow users who have assumed CriticalRole
to
assume a CriticalRole_2
in another account. The role session
credentials that were obtained to assume CriticalRole
are used to role chain to a second role,
CriticalRole_2
, in a different account. The role is being assumed
across an account boundary. Therefore, the sts:SetSourceIdentity
permission must be granted in both the permissions policy on
CriticalRole
and in the role trust policy on
CriticalRole_2
.
Example permissions policy on CriticalRole
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AssumeRoleAndSetSourceIdentity", "Effect": "Allow", "Action": [ "sts:AssumeRole", "sts:SetSourceIdentity" ], "Resource": "arn:aws-cn:iam::
222222222222
:role/CriticalRole_2" } ] }
To secure setting source identity across the account boundary, the following role
trust policy trusts only the role principal for CriticalRole
to set the
source identity.
Example role trust policy on CriticalRole_2
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws-cn:iam::
111111111111
:role/CriticalRole" }, "Action": [ "sts:AssumeRole", "sts:SetSourceIdentity" ], "Condition": { "StringLike": { "aws:SourceIdentity": ["Saanvi","Diego"] } } } ] }
The user makes the following call using role session credentials obtained from
assuming CriticalRole. The source identity was set during the assumption of
CriticalRole, so it does not need to be explicitly set again. If the user attempts
to set a source identity that is different from the value set when
CriticalRole
was assumed, the assume role request will be
denied.
Example AssumeRole CLI request
aws sts assume-role \ --role-arn arn:aws-cn:iam::
222222222222
:role/CriticalRole_2 \ --role-session-name Audit \
When the calling principal assumes the role, the source identity in the request
persists from the first assumed role session. Therefore, both the
aws:SourceIdentity
and sts:SourceIdentity
keys are
present in the request context.
Viewing source identity in CloudTrail
You can use CloudTrail to view the requests made to assume roles or federate users. You can also view the role or user requests to take actions in Amazon. The CloudTrail log file includes information about the source identity set for the assumed-role or federated user session. For more information, see Logging IAM and Amazon STS API calls with Amazon CloudTrail
For example, assume that a user makes an Amazon STS AssumeRole
request, and
sets a source identity. You can find the sourceIdentity
information in the
requestParameters
key in your CloudTrail log.
Example requestParameters section in an Amazon CloudTrail log
"eventVersion": "1.05", "userIdentity": { "type": "AWSAccount", "principalId": "AIDAJ45Q7YFFAREXAMPLE", "accountId": "111122223333" }, "eventTime": "2020-04-02T18:20:53Z", "eventSource": "sts.amazonaws.com", "eventName": "AssumeRole", "awsRegion": "us-east-1", "sourceIPAddress": "203.0.113.64", "userAgent": "aws-cli/1.16.96 Python/3.6.0 Windows/10 botocore/1.12.86", "requestParameters": { "roleArn": "arn:aws-cn:iam::123456789012:role/DevRole", "roleSessionName": "Dev1", "sourceIdentity": "
source-identity-value-set
" }
If the user uses the assumed role session to perform an action, the source identity
information is present in the userIdentity
key in the CloudTrail log.
Example userIdentity key in an Amazon CloudTrail log
{ "eventVersion": "1.08", "userIdentity": { "type": "AssumedRole", "principalId": "AROAJ45Q7YFFAREXAMPLE:Dev1", "arn": "arn:aws-cn:sts::123456789012:assumed-role/DevRole/Dev1", "accountId": "123456789012", "accessKeyId": "ASIAIOSFODNN7EXAMPLE", "sessionContext": { "sessionIssuer": { "type": "Role", "principalId": "AROAJ45Q7YFFAREXAMPLE", "arn": "arn:aws-cn:iam::123456789012:role/DevRole", "accountId": "123456789012", "userName": "DevRole" }, "webIdFederationData": {}, "attributes": { "mfaAuthenticated": "false", "creationDate": "2021-02-21T23:46:28Z" }, "sourceIdentity": "source-identity-value-present" } } }
To see example Amazon STS API events in CloudTrail logs, see Example IAM API events in CloudTrail log. For more details about the information contained in CloudTrail log files, see CloudTrail Event Reference in the Amazon CloudTrail User Guide.