Category: Cloud Identity

AssumeRole

Also known as: AWS STS AssumeRole, sts:AssumeRole, assume-role

Simply put

AssumeRole is an AWS Security Token Service (STS) API call that lets a user, service, or external identity temporarily take on the permissions of an IAM role. Instead of using long-lived credentials, the caller receives a set of temporary security credentials that expire after a defined period. This lets one entity act with a different, typically scoped-down or scoped-up, set of permissions for a limited time.

Formal definition

AssumeRole is an AWS STS API action (sts:AssumeRole) that returns a set of temporary security credentials, consisting of an access key ID, a secret access key, and a session token, associated with a specified IAM role. A principal (such as an IAM user, an AWS service, or an external identity) that is authorized to assume the role uses these temporary credentials to make subsequent AWS API calls under the assumed role's permissions. This is a runtime authorization and credential-issuance mechanism: the caller must already be authenticated as a principal, and the role's trust policy plus the caller's permissions determine whether the assumption is allowed. The returned credentials are short-lived and expire, in contrast to long-lived static credentials. Note that AssumeRole is distinct from PassRole; based on the evidence provided, exact credential lifetime bounds and other configuration-dependent limits are out of scope for this entry.

Why it matters

AssumeRole is central to how AWS environments avoid distributing long-lived static credentials. Because the call returns short-lived temporary credentials that expire, it limits the window in which leaked or misused credentials remain valid, which is a meaningful advantage over embedding permanent access keys in code, configuration, or CI/CD systems. In most deployments this makes AssumeRole a foundational building block for cross-account access, federated access from external identity providers, and workload-to-service access patterns.

The mechanism also enforces a clear separation between who a caller is and what they are permitted to become. A principal must already be authenticated before it can call sts:AssumeRole, and whether the assumption succeeds depends on both the target role's trust policy and the caller's own permissions. This dual-gate design means that misconfigurations, such as an overly broad trust policy that permits assumption from unintended principals, can create privilege escalation paths. For security architects, reasoning about who can assume which roles, and under what conditions, is often as important as reasoning about the permissions attached to the roles themselves.

Because AssumeRole issues credentials at runtime, it belongs to the enforcement side of an identity program rather than the governance side. It does not, on its own, provide access certification, periodic review, or segregation-of-duties analysis over which principals hold assumption rights. Organizations typically need separate governance processes to review and attest to role trust relationships over time, since a permissive trust policy will keep granting temporary credentials until it is changed.

Who it's relevant to

Security architects

Architects designing cross-account and federated access patterns rely on AssumeRole to avoid long-lived credentials. They must reason carefully about role trust policies, since these determine which principals can obtain temporary credentials and can, if too permissive, open privilege escalation paths.

IAM and cloud engineers

Engineers implement AssumeRole in application code, service configurations, and CI/CD pipelines to obtain scoped temporary credentials at runtime. They also need to distinguish AssumeRole from PassRole, since the two actions address different needs and are frequently confused.

Identity governance leads

Because AssumeRole is a runtime enforcement mechanism rather than a lifecycle control, governance leads typically need separate processes to review and certify who holds role-assumption rights and to attest to trust policy configurations over time.

Compliance and audit teams

Auditors examining AWS access controls benefit from understanding that AssumeRole issues short-lived credentials whose validity is bounded by expiration. Assessing exposure requires reviewing both who can assume roles and the permissions those roles carry, rather than only inventorying static credentials.

Inside AssumeRole

Role ARN

The Amazon Resource Name identifying the IAM role a principal wishes to assume. This is the authorization target whose permissions policy defines what the resulting session may do, distinct from the identity of the calling principal.

Trust policy (assume-role policy document)

The policy attached to the role that specifies which principals are permitted to assume it. This governs the authorization to call AssumeRole and is evaluated separately from the role's own permissions policy that governs what actions the session can perform.

Temporary security credentials

The output of a successful AssumeRole call, typically consisting of an access key ID, a secret access key, and a session token. These are short-lived credentials scoped to the assumed role's permissions and expire after the session duration.

Session duration

The lifetime of the returned credentials, configurable within the bounds allowed by the role's maximum session setting. Depending on configuration, this typically ranges within limits defined per role rather than being indefinite.

Session name (RoleSessionName)

An identifier attached to the assumed-role session, commonly used for traceability in audit logs so that actions taken under the temporary credentials can be attributed back to the originating request.

External ID and session policies

Optional parameters that further constrain assumption: an external ID mitigates confused-deputy scenarios in cross-account trust, while inline session policies can narrow the effective permissions of the resulting session below those granted by the role's permissions policy.

Common questions

Answers to the questions practitioners most commonly ask about AssumeRole.

Does AssumeRole authenticate the calling principal?

No. AssumeRole does not perform authentication of who the caller is; the calling principal must already be authenticated (for example, via existing credentials or a federated identity) before the call. AssumeRole is an authorization mechanism that, once the caller's identity is established and the trust policy permits it, issues temporary credentials scoped to the target role's permissions. Keep the identification and authentication of the caller separate from the authorization decision that AssumeRole represents.

Do the permissions attached to a role directly determine what an assumed session can do?

Not by themselves. Two distinct policy evaluations are involved: the role's trust policy governs which principals are permitted to assume the role, while the role's permissions (identity) policies govern what the resulting session may do. The effective permissions of an assumed session can also be further constrained, depending on configuration, by session policies passed at assume time, permissions boundaries, and organization-level controls. The role's attached permissions describe the maximum grantable scope, not necessarily the final effective scope.

How do you scope down the permissions of an assumed session below what the role allows?

In most deployments you can pass an inline or managed session policy at the time of the AssumeRole call, which intersects with the role's permissions so the session receives no more than both allow. Permissions boundaries and, where applicable, organizational controls can further constrain the result. This is commonly used to grant a narrowly tailored session for a specific task while reusing a broader role definition.

How is the trust policy configured to control who may assume a role?

The trust policy is attached to the role itself and specifies the principals permitted to assume it, along with the applicable action and any conditions. Depending on the use case, principals may be specific accounts, IAM users or roles, or federated identity providers. Conditions can restrict assumption based on context such as source identity, external identifiers, or other request attributes, depending on what the configuration supports.

What credentials result from a successful AssumeRole call, and how long do they last?

A successful call returns temporary security credentials, typically consisting of an access key, a secret key, and a session token, which the caller uses for subsequent requests under the assumed role. These credentials are time-limited; the session duration is bounded by configuration and the role's maximum session setting. When they expire the principal must assume the role again to obtain fresh credentials, which supports short-lived access rather than long-standing static credentials.

How can assumed-role sessions be attributed to the originating identity for audit purposes?

Because a role can be assumed by many principals, sessions benefit from additional attribution to preserve accountability. Depending on configuration, a session name and, where supported, a propagated source identity can be set at assume time and surfaced in logs, helping tie actions taken under the role back to the original caller during access reviews and investigations. Confirm which attribution attributes your deployment records, as available fields vary by configuration.

Common misconceptions

AssumeRole authenticates the user or proves who they are.

AssumeRole is an authorization mechanism that grants a set of temporary permissions, not an authentication step. The calling principal must already be identified and authenticated before the call; AssumeRole then determines what that principal may do by issuing scoped credentials, keeping identification, authentication, and authorization as distinct steps.

The credentials returned by AssumeRole are long-lived like static access keys.

The returned credentials are temporary and expire after the configured session duration. This is a runtime enforcement characteristic and differs from static, persistent credentials; applications must handle expiration and, depending on configuration, re-request credentials.

Attaching a broad permissions policy to a role is enough to control who can assume it.

Two separate policies apply: the trust policy controls which principals may assume the role, and the permissions policy controls what the resulting session may do. A permissive permissions policy without a properly scoped trust policy can allow unintended principals to obtain those permissions.

Best practices

Scope the role's trust policy to only the specific principals that legitimately need to assume it, rather than relying on the permissions policy alone to limit exposure.

Use an external ID for cross-account role assumption to reduce the risk of confused-deputy attacks, where deployment context involves third parties.

Set session durations to the minimum practical for the workload so temporary credentials expire promptly, and design applications to handle credential expiry and renewal.

Apply session policies to further narrow effective permissions below the role's permissions policy when a session needs only a subset of the role's access.

Provide meaningful session names so that actions performed under assumed-role credentials can be attributed and traced in audit logs.

Keep the permissions policy least-privilege and review it alongside the trust policy, since the two govern separate concerns and must be evaluated together.