Skip to content

Security Token Service (STS)

Security Token Service (STS) is a service provided by Amazon Web Services (AWS) that enables you to grant temporary, limited-privilege credentials to users and applications. STS implements fine-grained access control and reduce the exposure of your long-term credentials. The temporary credentials, known as security tokens, can be used to access AWS services and resources based on the permissions specified in the associated policies.

LocalStack allows you to use the STS APIs in your local environment to request security tokens, manage permissions, integrate with identity providers, and more. The supported APIs are available on our API Coverage section, which provides information on the extent of STS’s integration with LocalStack.

This guide is designed for users new to STS and assumes basic knowledge of the AWS CLI and our awslocal wrapper script.

Start your LocalStack container using your preferred method. We will demonstrate how to assume an IAM Role and assume the role as well as creating an IAM user and getting using the STS with the AWS CLI.

Create an IAM User and get temporary Credentials

Section titled “Create an IAM User and get temporary Credentials”

You can create an IAM User and Role using the CreateUser API. The IAM User will be used to assume the IAM Role. Run the following command to create an IAM User, named localstack-user:

Terminal window
awslocal iam create-user \
--user-name localstack-user

You can generate long-term access keys for the IAM user using the CreateAccessKey API. Run the following command to create an access key for the IAM user:

Terminal window
awslocal iam create-access-key \
--user-name localstack-user
Output
{
"AccessKey": {
"UserName": "localstack-user",
"AccessKeyId": "ACCESS_KEY_ID",
"Status": "Active",
"SecretAccessKey": "SECRET_ACCESS_KEY",
"CreateDate": "2023-08-24T17:16:16Z"
}
}

Using STS, you can also fetch temporary credentials for this user using the GetSessionToken API. Run the following command using your long-term credentials to get your temporary credentials:

Terminal window
awslocal sts get-session-token
Output
{
"Credentials": {
"AccessKeyId": "ACCESS_KEY_ID",
"SecretAccessKey": "SECRET_ACCESS_KEY",
"SessionToken": "SESSION_TOKEN",
"Expiration": "TIMESTAMP"
}
}

You can now create an IAM Role, named localstack-role, using the CreateRole API. Run the following command to create the IAM Role:

Terminal window
awslocal iam create-role \
--role-name localstack-role \
--assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:aws:iam::000000000000:root"},"Action":"sts:AssumeRole"}]}'
Output
{
"Role": {
"Path": "/",
"RoleName": "localstack-role",
"RoleId": "AROAQAAAAAAAEDP262HSR",
"Arn": "arn:aws:iam::000000000000:role/localstack-role",
"CreateDate": "2023-08-24T17:17:13.632000Z",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::000000000000:root"
},
"Action": "sts:AssumeRole"
}
]
}
}
}

You can attach the policy to the IAM role using the AttachRolePolicy API. Run the following command to attach the policy to the IAM role:

Terminal window
awslocal iam attach-role-policy \
--role-name localstack-role \
--policy-arn arn:aws:iam::aws:policy/AdministratorAccess

You can assume an IAM Role using the AssumeRole API. Run the following command to assume the IAM Role:

Terminal window
awslocal sts assume-role \
--role-arn arn:aws:iam::000000000000:role/localstack-role \
--role-session-name localstack-session
Output
{
"Credentials": {
"AccessKeyId": "ACCESS_KEY_ID",
"SecretAccessKey": "SECRET_ACCESS_KEY",
"SessionToken": "SESSION_TOKEN",
"Expiration": "TIMESTAMP",
},
"AssumedRoleUser": {
"AssumedRoleId": "AROAQAAAAAAAEDP262HSR:localstack-session",
"Arn": "arn:aws:sts::000000000000:assumed-role/localstack-role/localstack-session"
},
"PackedPolicySize": 6
}

You can use the temporary credentials in your applications for temporary access.

You can get the caller identity to identify the principal your current credentials are valid for using the GetCallerIdentity API. Run the following command to get the caller identity for the credentials set in your environment:

Terminal window
awslocal sts get-caller-identity
Output
{
"UserId": "AKIAIOSFODNN7EXAMPLE",
"Account": "000000000000",
"Arn": "arn:aws:iam::000000000000:root"
}
OperationImplementedImage
Page 1 of 0