Security Token Service(STS)
AWS Security Token Service(STS) is a web service that enables you to request temporary, limited privilege credentials for IAM Users or Federated Users.STS is the service that is a building block of many identity processes within AWS. If you have used the IAM role, then you already use the service provided by STS without necessarily being aware of it.
- STS generates temporary IAM credentials whenever sts:AssumeRole* operation is used. Whenever you assume an IAM role, you use the sts:AssumeRole* call, and in doing that, you gain access to IAM temporary credentials, which can be used by the identity which assumes the role.
- When you perform the role switch in the UI, you are assuming the role in another AWS account and using STS to gain access to these temporary credentials. This happens behind the scenes, and you don’t get any exposure to that within UI.
- It generates ACCESS KEY and SECRET ACCESS KEY, but they will expire and don’t belong to the identity(e.g. an IAM user has access/secret key, also known as long-term credentials), which assumes the role.
- Requested credentials can be accessed by another identity that can be AWS or external identity(for e.g., Google or Facebook, also known as Web Federation Identity)
- No need to embed token in the code, which reduce the risk of your credentials being compromised
- Limited Lifetime(15min — 1 and 1/2 day(36 hours)). So you don’t have to rotate them or explicitly revoke them.
How STS Works
We start with the user who wants to assume a role, and that’s why STS is involved.
- Now around the role, we have a trust policy. A trust policy control who can assume that role. Conceptually it’s a wall that will only allow certain people to assume this role. So whatever trust policy allows, only that group of people can assume the role.
- The next step is to assume the role by calling sts:AssumeRole*. This call needs to originate from the existing identity, either AWS or an external federation.
- The next step is to read the permissions policy attached to the role. Permission policy control(controls what permission is granted when anyone assumes the role) what is allowed or denied inside AWS.
- STS uses the permission policy to generate temporary credentials. Temporary credentials can access AWS resources until expiration. Access is authorized based on the permission policy.
- Temporary credentials are generated when a role is assumed, and they are returned to an identity who assumes the role. When credentials expire, another assume role call is needed to access new credentials.
Temporary credentials include
- AccessKeyId: This is the unique id of the credentials
- Expiration: This denotes the date and time when credentials will expire
- Secret Access Key: This key is used to sign requests to AWS
- Session Token: This is a unique token that must be passed with all requests
- If you assume a role within an AWS account
- Role switch between AWS accounts using console UI. You use STS
- Cross-account access using role
At this stage, temporary credentials are generated and will be returned to the identity who assumes the role. Once the credentials expire, another sts:AssumeRole* call is needed to get access to new credentials.
NOTE: Temporary credentials can’t be canceled. You can’t manually invalidate credentials.
If you want to check these temporary credentials, log in to the EC2 instance, which assumes the IAM role s3_full_access_role, and access its metadata service(169.254.169.254) via curl command. Check this doc for more info https://docs.aws.amazon.com/neptune/latest/userguide/iam-auth-temporary-credentials.html
$ curl http://169.254.169.254/latest/meta-data/iam/security-credentials/
$ curl http://169.254.169.254/latest/meta-data/iam/security-credentials/s3_full_access_role
"Code" : "Success",
"LastUpdated" : "2022–08–16T22:57:12Z",
"Type" : "AWS-HMAC",
"AccessKeyId" : "ASIAXXXXXXXXXX",
"SecretAccessKey" : "mdsTXXXXXXXXXX",
"Token" : "IQoJbXXXXXXXX"
"Expiration" : "2022–11–19T05:32:30Z"
Now let deep dive in and see the practical demonstration and assume the IAM role on the command line
- Create an IAM user name prashant.
aws iam create-user --user-name prashant
- Create an IAM policy that grants user prashant access to assume a role. The contents of the assume-role-policy.json file are similar to this.
- To create a policy use the aws iam create-policy command
aws iam create-policy --policy-name assume-role-policy --policy-document file://assume-role-policy.json
Note down the ARN (Amazon Resource Name) of the IAM policy
- Attach this policy to user prashant
aws iam attach-user-policy --user-name prashant --policy-arn "arn:aws:iam::1234567890:policy/assume-role-policy"
- To review the policy attached to the user, run the below command
aws iam list-attached-user-policies --user-name prashant
- Create a json file assume-role-trust-policy.json that defines the trust relationship
NOTE: This trust policy allows users “arn:aws:iam::1234567890:user/prashant” to assume this role if they allow the sts:AssumeRole action in their permissions policy.
- Create the IAM role that user prashant can assume and has read-only access to the S3 bucket.
#Create an IAM Role
aws iam create-role --role-name assume-trust-role --assume-role-policy-document file://assume-role-trust-policy.json
#Attach S3 read only access policy to the role
aws iam attach-role-policy --role-name assume-trust-role --policy-arn "arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"
#List the attached role
aws iam list-attached-role-policies --role-name assume-trust-role
- Create the access key for the user
aws iam create-access-key --user-name prashant
- Configure the access key
AWS Access Key ID [****************PFEC]: XXXXXXXX
AWS Secret Access Key [****************tHBh]: pYUgRXXXXXXXX
Default region name [us-east-1]:
Default output format [json]:
- Run the aws sts get-caller-identity
aws sts get-caller-identity
- Try to list S3 bucket
aws s3 ls
An error occurred (AccessDenied) when calling the ListBuckets operation: Access Denied
- Assume the IAM role
aws sts assume-role --role-arn "arn:aws:iam::123456789012:role/assume-trust-role" --role-session-name my-demo-role
- This command will output several piece of information. You can either manually export AccessKeyId, SecretAccessKey, and SessionToken
- Use the below script to automate the process
OUT=$(aws sts assume-role --role-arn arn:aws:iam::123456789012:role/assume-trust-role --role-session-name my-demo-role);\
export AWS_ACCESS_KEY_ID=$(echo $OUT | jq -r '.Credentials''.AccessKeyId');\
export AWS_SECRET_ACCESS_KEY=$(echo $OUT | jq -r '.Credentials''.SecretAccessKey');\
export AWS_SESSION_TOKEN=$(echo $OUT | jq -r '.Credentials''.SessionToken');
- Now try to list s3 bucket
aws s3 ls
- To return to the IAM user, remove the environment variables
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN