DevOps Glossary

AWS STS AssumeRole is an AWS Security Token Service API call that returns temporary security credentials for an IAM role. In practical terms, it lets a user, service, workload, or AWS account act with the permissions of another role for a limited time, without sharing long-lived access keys.

What AWS STS AssumeRole does

AssumeRole is used to get short-lived credentials that can call AWS APIs. The permissions come from the target IAM role, and the session expires automatically after a configured duration.

The returned credentials include:

• Access key ID
• Secret access key
• Session token
• Expiration time

These credentials can then be used by tools such as the AWS CLI, SDKs, Terraform, CI/CD systems, internal platforms, or Kubernetes controllers that manage AWS infrastructure.

How it works

AssumeRole depends on two main IAM controls:

• Trust policy: Defines who is allowed to assume the role. This can be an IAM user, another role, an AWS service, or a principal from another AWS account.
• Permissions policy: Defines what the role can do after it has been assumed, such as reading from S3, updating ECS services, or creating CloudWatch alarms.

A typical flow looks like this:

1. A caller sends an AssumeRole request to AWS STS.
2. STS checks whether the target role trusts that caller.
3. STS applies the role permissions, optional session policies, tags, MFA conditions, and duration limits.
4. STS returns temporary credentials.
5. The caller uses those credentials to make AWS API calls until the session expires.

Common use cases

• Cross-account access: A CI/CD role in a tooling account assumes deployment roles in dev, staging, and production accounts.
• Break-glass access: Engineers assume a tightly controlled admin role with MFA and short session duration during incidents.
• Automation: Terraform, scripts, or platform services assume roles to create and update AWS resources.
• Multi-account operations: A central observability or security account assumes roles across workload accounts to collect logs, metrics, or configuration data.
• Infrastructure controllers: Tools such as Crossplane may use AWS credentials and IAM roles when they manage AWS resources from Kubernetes.

Key concepts

• Role ARN: The Amazon Resource Name of the role being assumed, such as arn:aws:iam::123456789012:role/deploy-prod.
• Role session name: A required name for the session. It appears in CloudTrail and helps identify who or what assumed the role.
• External ID: A value often used for third-party access to reduce confused deputy risks.
• MFA condition: A trust policy condition that requires multi-factor authentication before the role can be assumed.
• Session policy: An optional inline or managed policy that further restricts the role session. It cannot grant more permissions than the role already has.
• Session tags: Key-value tags attached to the session, often used for attribute-based access control and audit context.

Benefits

• Reduces long-lived credentials: Sessions expire, which limits exposure if credentials are leaked.
• Supports least privilege: Teams can create specific roles for deployment, read-only support, incident response, or service operations.
• Improves auditability: CloudTrail records AssumeRole activity, including the role session name and source identity when configured.
• Works well with multi-account AWS setups: Teams can keep workloads isolated while allowing controlled access for shared tooling.

Tradeoffs and limitations

• Policy design can get complex: You need to manage both trust policies and permissions policies correctly.
• Session duration is limited: Roles have maximum session durations, and some chained role sessions are capped more strictly.
• Bad session names reduce traceability: Generic names like deploy or admin make audit trails harder to read.
• Overly broad trust policies are risky: Trusting an entire account or wildcard principal without conditions can grant more access than intended.

Simple example

A startup keeps CI/CD in a shared AWS account and runs production workloads in a separate production account. The CI/CD runner has permission to call sts:AssumeRole on a role named deploy-prod in the production account.

When a production deployment starts, the runner assumes deploy-prod, receives temporary credentials for 1 hour, and uses them to update services, run database migrations, or apply infrastructure changes. After the session expires, those credentials no longer work.

The same pattern can apply whether the team provisions resources with Terraform, AWS CloudFormation, or Kubernetes-based workflows such as Crossplane-managed application infrastructure.

AssumeRole vs related STS APIs

• AssumeRole: Used when an AWS principal assumes an IAM role, often for cross-account or delegated access.
• AssumeRoleWithWebIdentity: Used with web identity providers and OIDC tokens. This is common for Kubernetes service accounts in EKS.
• AssumeRoleWithSAML: Used with SAML-based identity providers, often for enterprise SSO.
• GetSessionToken: Used to get temporary credentials for an IAM user, often with MFA.

For most platform and DevOps teams, AssumeRole is a core building block for secure AWS automation, account separation, and short-lived access in deployment pipelines.