Requesting temporary security credentials
To request temporary security credentials, you can use AWS Security Token Service (AWS STS) operations in the AWS API. These include operations to create and provide trusted users with temporary security credentials that can control access to your AWS resources. For more information about AWS STS, see Temporary security credentials in IAM. To learn about the different methods that you can use to request temporary security credentials by assuming a role, see Using IAM roles.
To call the API operations, you can use one of the AWS SDKs
The AWS STS API operations create a new session with temporary security credentials that include an access key pair and a session token. The access key pair consists of an access key ID and a secret key. Users (or an application that the user runs) can use these credentials to access your resources. You can create a role session and pass session policies and session tags programmatically using AWS STS API operations. The resulting session permissions are the intersection of the role's identity-based policies and the session policies. For more information about session policies, see Session policies. For more information about session tags, see Passing session tags in AWS STS.
Note
The size of the session token that AWS STS API operations return is not fixed. We strongly recommend that you make no assumptions about the maximum size. The typical token size is less than 4096 bytes, but that can vary.
Using AWS STS with AWS Regions
You can send AWS STS API calls either to a global endpoint or to one of the Regional endpoints. If you choose an endpoint closer to you, you can reduce latency and improve the performance of your API calls. You also can choose to direct your calls to an alternative Regional endpoint if you can no longer communicate with the original endpoint. If you are using one of the various AWS SDKs, then use that SDK method to specify a Region before you make the API call. If you manually construct HTTP API requests, then you must direct the request to the correct endpoint yourself. For more information, see the AWS STS section of Regions and Endpoints and Managing AWS STS in an AWS Region.
The following are the API operations that you can use to acquire temporary credentials for use in your AWS environment and applications.
AssumeRole—cross-account delegation and federation through a custom identity broker
The AssumeRole
API operation is useful for allowing existing IAM users to
access AWS resources that they don't already have access to. For example, the user might
need access to resources in another AWS account. It is also useful as a means to temporarily
gain privileged access—for example, to provide multi-factor authentication (MFA). You
must call this API using active credentials. To learn who can call this operation, see Comparing the AWS STS API operations. For more information, see
Creating a role to delegate permissions to an IAM
user and
Configuring MFA-protected API
access.
This call must be made using valid AWS security credentials. When you make this call, you pass the following information:
-
The Amazon Resource Name (ARN) of the role that the app should assume.
-
(Optional) Duration, which specifies the duration of the temporary security credentials. Use the
DurationSeconds
parameter to specify the duration of the role session from 900 seconds (15 minutes) up to the maximum session duration setting for the role. To learn how to view the maximum value for your role, see View the maximum session duration setting for a role. If you do not pass this parameter, the temporary credentials expire in one hour. TheDurationSeconds
parameter from this API is separate from theSessionDuration
HTTP parameter that you use to specify the duration of a console session. Use theSessionDuration
HTTP parameter in the request to the federation endpoint for a console sign-in token. For more information, see Enabling custom identity broker access to the AWS console. -
Role session name. Use this string value to identify the session when a role is used by different principals. For security purposes, administrators can view this field in AWS CloudTrail logs to help identify who performed an action in AWS. Your administrator might require that you specify your IAM user name as the session name when you assume the role. For more information, see sts:RoleSessionName.
-
(Optional) Source identity. You can require users to specify a source identity when they assume a role. After the source identity is set, the value cannot be changed. It is present in the request for all actions that are taken during the role session. The source identity value persists across chained role sessions. You can use source identity information in AWS CloudTrail logs to determine who took actions with a role. For more information about using source identity, see Monitor and control actions taken with assumed roles.
-
(Optional) Inline or managed session policies. These policies limit the permissions from the role's identity-based policy that are assigned to the role session. The resulting session's permissions are the intersection of the role's identity-based policies and the session policies. Session policies cannot be used to grant more permissions than those allowed by the identity-based policy of the role that is being assumed. For more information about role session permissions, see Session policies.
-
(Optional) Session tags. You can assume a role and then use the temporary credentials to make a request. When you do, the session's principal tags include the role's tags and the passed session tags. If you make this call using temporary credentials, the new session also inherits transitive session tags from the calling session. For more information about session tags, see Passing session tags in AWS STS.
-
(Optional) MFA information. If configured to use multi-factor authentication (MFA), then you include the identifier for an MFA device and the one-time code provided by that device.
-
(Optional)
ExternalId
value that can be used when delegating access to your account to a third party. This value helps ensure that only the specified third party can access the role. For more information, see How to use an external ID when granting access to your AWS resources to a third party.
The following example shows a sample request and response using AssumeRole
.
This example request assumes the demo
role for the specified duration with the
included session policy, session tags, external ID, and source identity. The resulting
session is named John-session
.
Example request
https://sts.amazonaws.com/ ?Version=2011-06-15 &Action=AssumeRole &RoleSessionName=John-session &RoleArn=arn:aws::iam::123456789012:role/demo &Policy=%7B%22Version%22%3A%222012-10-17%22%2C%22Statement%22%3A%5B%7B%22Sid%22%3A%20%22Stmt1%22%2C%22Effect%22%3A%20%22Allow%22%2C%22Action%22%3A%20%22s3%3A*%22%2C%22Resource%22%3A%20%22*%22%7D%5D%7D &DurationSeconds=1800 &Tags.member.1.Key=Project &Tags.member.1.Value=Pegasus &Tags.member.2.Key=Cost-Center &Tags.member.2.Value=12345 &ExternalId=123ABC &SourceIdentity=DevUser123 &AUTHPARAMS
The policy value shown in the preceding example is the URL-encoded version of the following policy:
{"Version":"2012-10-17","Statement":[{"Sid":"Stmt1","Effect":"Allow","Action":"s3:*","Resource":"*"}]}
The AUTHPARAMS
parameter in the example is a placeholder for your
signature. A signature is the authentication information that you must
include with AWS HTTP API requests. We recommend using the AWS SDKs
In addition to the temporary security credentials, the response includes the Amazon Resource Name (ARN) for the federated user and the expiration time of the credentials.
Example response
<AssumeRoleResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<AssumeRoleResult>
<SourceIdentity>DevUser123</SourceIdentity>
<Credentials>
<SessionToken>
AQoDYXdzEPT//////////wEXAMPLEtc764bNrC9SAPBSM22wDOk4x4HIZ8j4FZTwdQW
LWsKWHGBuFqwAeMicRXmxfpSPfIeoIYRqTflfKD8YUuwthAx7mSEI/qkPpKPi/kMcGd
QrmGdeehM4IC1NtBmUpp2wUE8phUZampKsburEDy0KPkyQDYwT7WZ0wq5VSXDvp75YU
9HFvlRd8Tx6q6fE8YQcHNVXAkiY9q6d+xo0rKwT38xVqr7ZD0u0iPPkUL64lIZbqBAz
+scqKmlzm8FDrypNC9Yjc8fPOLn9FX9KSYvKTr4rvx3iSIlTJabIQwj2ICCR/oLxBA==
</SessionToken>
<SecretAccessKey>
wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY
</SecretAccessKey>
<Expiration>2019-07-15T23:28:33.359Z</Expiration>
<AccessKeyId>AKIAIOSFODNN7EXAMPLE</AccessKeyId>
</Credentials>
<AssumedRoleUser>
<Arn>arn:aws:sts::123456789012:assumed-role/demo/John</Arn>
<AssumedRoleId>ARO123EXAMPLE123:John</AssumedRoleId>
</AssumedRoleUser>
<PackedPolicySize>8</PackedPolicySize>
</AssumeRoleResult>
<ResponseMetadata>
<RequestId>c6104cbe-af31-11e0-8154-cbc7ccf896c7</RequestId>
</ResponseMetadata>
</AssumeRoleResponse>
Note
An AWS conversion compresses the passed session policies and session tags into a
packed binary format that has a separate limit. Your request can fail for this limit even if
your plaintext meets the other requirements. The PackedPolicySize
response
element indicates by percentage how close the policies and tags for your request are to the
upper size limit.
AssumeRoleWithWebIdentity—federation through a web-based identity provider
The AssumeRoleWithWebIdentity
API operation returns a set of temporary
security credentials for federated users who are authenticated through a public identity
provider. Examples of public identity providers include Login with Amazon, Facebook, Google,
or any OpenID Connect (OIDC)-compatible identity provider. This operation is useful for
creating mobile applications or client-based web applications that require access to AWS.
Using this operation means that your users do not need their own AWS or IAM identities.
For more information, see OIDC federation.
Instead of directly calling AssumeRoleWithWebIdentity
, we recommend that you
use Amazon Cognito and the Amazon Cognito credentials provider with the AWS SDKs for mobile development. For
more information, see Authentication with Amplify
If you are not using Amazon Cognito, you call the AssumeRoleWithWebIdentity
action of
AWS STS. This is an unsigned call, meaning that the app does not need to have access to any
AWS security credentials to make the call. When you make this call, you pass the following
information:
-
The Amazon Resource Name (ARN) of the role that the app should assume. If your app supports multiple ways for users to sign in, you must define multiple roles, one per identity provider. The call to
AssumeRoleWithWebIdentity
should include the ARN of the role that is specific to the provider through which the user signed in. -
The token that the app gets from the IdP after the app authenticates the user.
-
You can configure your IdP to pass attributes into your token as session tags.
-
(Optional) Duration, which specifies the duration of the temporary security credentials. Use the
DurationSeconds
parameter to specify the duration of the role session from 900 seconds (15 minutes) up to the maximum session duration setting for the role. To learn how to view the maximum value for your role, see View the maximum session duration setting for a role. If you do not pass this parameter, the temporary credentials expire in one hour. TheDurationSeconds
parameter from this API is separate from theSessionDuration
HTTP parameter that you use to specify the duration of a console session. Use theSessionDuration
HTTP parameter in the request to the federation endpoint for a console sign-in token. For more information, see Enabling custom identity broker access to the AWS console. -
Role session name. Use this string value to identify the session when a role is used by different principals. For security purposes, administrators can view this field in AWS CloudTrail logs to learn who performed an action in AWS. Your administrator might require that you provide a specific value for the session name when you assume the role. For more information, see sts:RoleSessionName.
-
(Optional) Source identity. You can require federated users to specify a source identity when they assume a role. After the source identity is set, the value cannot be changed. It is present in the request for all actions that are taken during the role session. The source identity value persists across chained role sessions. You can use source identity information in AWS CloudTrail logs to determine who took actions with a role. For more information about using source identity, see Monitor and control actions taken with assumed roles.
-
(Optional) Inline or managed session policies. These policies limit the permissions from the role's identity-based policy that are assigned to the role session. The resulting session's permissions are the intersection of the role's identity-based policies and the session policies. Session policies cannot be used to grant more permissions than those allowed by the identity-based policy of the role that is being assumed. For more information about role session permissions, see Session policies.
Note
A call to
AssumeRoleWithWebIdentity
is not signed (encrypted). Therefore, you should only include optional session policies if the request is transmitted through a trusted intermediary. In this case, someone could alter the policy to remove the restrictions.
When you call AssumeRoleWithWebIdentity
, AWS verifies the authenticity of
the token. For example, depending on the provider, AWS might make a call to the provider and
include the token that the app has passed. Assuming that the identity provider validates the
token, AWS returns the following information to you:
-
A set of temporary security credentials. These consist of an access key ID, a secret access key, and a session token.
-
The role ID and the ARN of the assumed role.
-
A
SubjectFromWebIdentityToken
value that contains the unique user ID.
When you have the temporary security credentials, you can use them to make AWS API calls. This is the same process as making an AWS API call with long-term security credentials. The difference is that you must include the session token, which lets AWS verify that the temporary security credentials are valid.
Your app should cache the credentials. As noted, by default the credentials expire after
an hour. If you don't use the AmazonSTSCredentialsProviderAssumeRoleWithWebIdentity
again. Call this operation to get a new set
of temporary security credentials before the old ones expire.
AssumeRoleWithSAML—federation through an enterprise Identity Provider compatible with SAML 2.0
The AssumeRoleWithSAML
API operation returns a set of temporary security
credentials for federated users who are authenticated by your organization's existing identity
system. The users must also use SAML
Note
A call to AssumeRoleWithSAML
is not signed (encrypted). Therefore, you
should only include optional session policies if the request is transmitted through a
trusted intermediary. In this case, someone could alter the policy to remove the
restrictions.
This is an unsigned call, which means that the app does not need to have access to any AWS security credentials in order to make the call. When you make this call, you pass the following information:
-
The Amazon Resource Name (ARN) of the role that the app should assume.
-
The ARN of the SAML provider created in IAM that describes the identity provider.
-
The SAML assertion, encoded in base64, that was provided by the SAML identity provider in its authentication response to the sign-in request from your app.
-
You can configure your IdP to pass attributes into your SAML assertion as session tags.
-
(Optional) Duration, which specifies the duration of the temporary security credentials. Use the
DurationSeconds
parameter to specify the duration of the role session from 900 seconds (15 minutes) up to the maximum session duration setting for the role. To learn how to view the maximum value for your role, see View the maximum session duration setting for a role. If you do not pass this parameter, the temporary credentials expire in one hour. TheDurationSeconds
parameter from this API is separate from theSessionDuration
HTTP parameter that you use to specify the duration of a console session. Use theSessionDuration
HTTP parameter in the request to the federation endpoint for a console sign-in token. For more information, see Enabling custom identity broker access to the AWS console. -
(Optional) Inline or managed session policies. These policies limit the permissions from the role's identity-based policy that are assigned to the role session. The resulting session's permissions are the intersection of the role's identity-based policies and the session policies. Session policies cannot be used to grant more permissions than those allowed by the identity-based policy of the role that is being assumed. For more information about role session permissions, see Session policies.
-
Role session name. Use this string value to identify the session when a role is used by different principals. For security purposes, administrators can view this field in AWS CloudTrail logs to learn who performed an action in AWS. Your administrator might require that you provide a specific value for the session name when you assume the role. For more information, see sts:RoleSessionName.
-
(Optional) Source identity. You can require federated users to specify a source identity when they assume a role. After the source identity is set, the value cannot be changed. It is present in the request for all actions that are taken during the role session. The source identity value persists across chained role sessions. You can use source identity information in AWS CloudTrail logs to determine who took actions with a role. For more information about using source identity, see Monitor and control actions taken with assumed roles.
When you call AssumeRoleWithSAML
, AWS verifies the authenticity of the SAML
assertion. Assuming that the identity provider validates the assertion, AWS returns the
following information to you:
-
A set of temporary security credentials. These consist of an access key ID, a secret access key, and a session token.
-
The role ID and the ARN of the assumed role.
-
An
Audience
value that contains the value of theRecipient
attribute of theSubjectConfirmationData
element of the SAML assertion. -
An
Issuer
value that contains the value of theIssuer
element of the SAML assertion. -
A
NameQualifier
element that contains a hash value built from theIssuer
value, the AWS account ID, and the friendly name of the SAML provider. When combined with theSubject
element, they can uniquely identify the federated user. -
A
Subject
element that contains the value of theNameID
element in theSubject
element of the SAML assertion. -
A
SubjectType
element that indicates the format of theSubject
element. The value can bepersistent
,transient
, or the fullFormat
URI from theSubject
andNameID
elements used in your SAML assertion. For information about theNameID
element'sFormat
attribute, see Configure SAML assertions for the authentication response.
When you have the temporary security credentials, you can use them to make AWS API calls. This is the same process as making an AWS API call with long-term security credentials. The difference is that you must include the session token, which lets AWS verify that the temporary security credentials are valid.
Your app should cache the credentials. By default the credentials expire after an hour. If
you are not using the AmazonSTSCredentialsProviderAssumeRoleWithSAML
again. Call this operation to get a new set of
temporary security credentials before the old ones expire.
GetFederationToken—federation through a custom identity broker
The GetFederationToken
API operation returns a set of temporary security
credentials for federated users. This API differs from AssumeRole
in that the
default expiration period is substantially longer (12 hours instead of one hour).
Additionally, you can use the DurationSeconds
parameter to specify a duration for
the temporary security credentials to remain valid. The resulting credentials are valid for
the specified duration, between 900 seconds (15 minutes) to 129,600 seconds (36 hours). The
longer expiration period can help reduce the number of calls to AWS because you do not need
to get new credentials as often.
When you make this request, you use the credentials of a specific IAM user. The
permissions for the temporary security credentials are determined by the session policies that
you pass when you call GetFederationToken
. The resulting session permissions are
the intersection of the IAM user policies and the session policies that you pass. Session
policies cannot be used to grant more permissions than those allowed by the identity-based
policy of the IAM user that is requesting federation. For more information about role
session permissions, see Session policies.
When you use the temporary credentials that are returned by the
GetFederationToken
operation, the session's principal tags include the user's
tags and the passed session tags. For more information about session tags, see Passing session tags in AWS STS.
The GetFederationToken
call returns temporary security credentials that
consist of the session token, access key, secret key, and expiration. You can use
GetFederationToken
if you want to manage permissions inside your organization
(for example, using the proxy application to assign permissions).
The following example shows a sample request and response that uses
GetFederationToken
. This example request federates the calling user for the
specified duration with the session policy ARN and
session tags. The resulting session is named
Jane-session
.
Example request
https://sts.amazonaws.com/ ?Version=2011-06-15 &Action=GetFederationToken &Name=Jane-session &PolicyArns.member.1.arn==arn%3Aaws%3Aiam%3A%3A123456789012%3Apolicy%2FRole1policy &DurationSeconds=1800 &Tags.member.1.Key=Project &Tags.member.1.Value=Pegasus &Tags.member.2.Key=Cost-Center &Tags.member.2.Value=12345 &AUTHPARAMS
The policy ARN shown in the preceding example includes the following URL-encoded ARN:
arn:aws:iam::123456789012:policy/Role1policy
Also, note that the &AUTHPARAMS
parameter in the example is meant as a
placeholder for the authentication information. This is the signature,
which you must include with AWS HTTP API requests. We recommend using the AWS SDKs
In addition to the temporary security credentials, the response includes the Amazon Resource Name (ARN) for the federated user and the expiration time of the credentials.
Example response
<GetFederationTokenResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<GetFederationTokenResult>
<Credentials>
<SessionToken>
AQoDYXdzEPT//////////wEXAMPLEtc764bNrC9SAPBSM22wDOk4x4HIZ8j4FZTwdQW
LWsKWHGBuFqwAeMicRXmxfpSPfIeoIYRqTflfKD8YUuwthAx7mSEI/qkPpKPi/kMcGd
QrmGdeehM4IC1NtBmUpp2wUE8phUZampKsburEDy0KPkyQDYwT7WZ0wq5VSXDvp75YU
9HFvlRd8Tx6q6fE8YQcHNVXAkiY9q6d+xo0rKwT38xVqr7ZD0u0iPPkUL64lIZbqBAz
+scqKmlzm8FDrypNC9Yjc8fPOLn9FX9KSYvKTr4rvx3iSIlTJabIQwj2ICCEXAMPLE==
</SessionToken>
<SecretAccessKey>
wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY
</SecretAccessKey>
<Expiration>2019-04-15T23:28:33.359Z</Expiration>
<AccessKeyId>AKIAIOSFODNN7EXAMPLE;</AccessKeyId>
</Credentials>
<FederatedUser>
<Arn>arn:aws:sts::123456789012:federated-user/Jean</Arn>
<FederatedUserId>123456789012:Jean</FederatedUserId>
</FederatedUser>
<PackedPolicySize>4</PackedPolicySize>
</GetFederationTokenResult>
<ResponseMetadata>
<RequestId>c6104cbe-af31-11e0-8154-cbc7ccf896c7</RequestId>
</ResponseMetadata>
</GetFederationTokenResponse>
Note
An AWS conversion compresses the passed session policies and session tags into a
packed binary format that has a separate limit. Your request can fail for this limit even if
your plaintext meets the other requirements. The PackedPolicySize
response
element indicates by percentage how close the policies and tags for your request are to the
upper size limit.
AWS recommends that you grant permissions at the resource level (for example, you attach
a resource-based policy to an Amazon S3 bucket), you can omit the Policy
parameter.
However, if you do not include a policy for the federated user, the temporary security
credentials will not grant any permissions. In this case, you must use resource policies to grant the federated user access to your AWS
resources.
For example, assume your AWS account number is 111122223333, and you have an
Amazon S3 bucket that you want to allow Susan to access. Susan's temporary security credentials
don't include a policy for the bucket. In that case, you would need to ensure that the bucket
has a policy with an ARN that matches Susan's ARN, such as
arn:aws:sts::111122223333:federated-user/Susan
.
GetSessionToken—temporary credentials for users in untrusted environments
The GetSessionToken
API operation returns a set of temporary security
credentials to an existing IAM user. This is useful for providing enhanced security, such as
allowing AWS requests only when MFA is enabled for the IAM user. Because the credentials
are temporary, they provide enhanced security when you have an IAM user who accesses your
resources through a less secure environment. Examples of less secure environments include a
mobile device or web browser. For more information, see Requesting temporary security credentials or
GetSessionToken in the AWS Security Token Service API Reference.
By default, temporary security credentials for an IAM user are valid for a maximum of 12
hours. But you can request a duration as short as 15 minutes or as long as 36 hours using the
DurationSeconds
parameter. For security reasons, a token for an AWS account root user is
restricted to a duration of one hour.
GetSessionToken
returns temporary security credentials consisting of a
session token, an access key ID, and a secret access key. The following example shows a sample
request and response using GetSessionToken
. The response also includes the
expiration time of the temporary security credentials.
Example request
https://sts.amazonaws.com/ ?Version=2011-06-15 &Action=GetSessionToken &DurationSeconds=1800 &AUTHPARAMS
The AUTHPARAMS
parameter in the example is a placeholder for your
signature. A signature is the authentication information that you must
include with AWS HTTP API requests. We recommend using the AWS SDKs
Example response
<GetSessionTokenResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
<GetSessionTokenResult>
<Credentials>
<SessionToken>
AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/L
To6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3z
rkuWJOgQs8IZZaIv2BXIa2R4OlgkBN9bkUDNCJiBeb/AXlzBBko7b15fjrBs2+cTQtp
Z3CYWFXG8C5zqx37wnOE49mRl/+OtkIKGO7fAE
</SessionToken>
<SecretAccessKey>
wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY
</SecretAccessKey>
<Expiration>2011-07-11T19:55:29.611Z</Expiration>
<AccessKeyId>AKIAIOSFODNN7EXAMPLE</AccessKeyId>
</Credentials>
</GetSessionTokenResult>
<ResponseMetadata>
<RequestId>58c5dbae-abef-11e0-8cfe-09039844ac7d</RequestId>
</ResponseMetadata>
</GetSessionTokenResponse>
Optionally, the GetSessionToken
request can include SerialNumber
and TokenCode
values for AWS multi-factor authentication (MFA) verification. If
the provided values are valid, AWS STS provides temporary security credentials that include
the state of MFA authentication. The temporary security credentials can then be used to access
the MFA-protected API operations or AWS websites for as long as the MFA authentication is
valid.
The following example shows a GetSessionToken
request that includes an MFA
verification code and device serial number.
https://sts.amazonaws.com/ ?Version=2011-06-15 &Action=GetSessionToken &DurationSeconds=7200 &SerialNumber=YourMFADeviceSerialNumber &TokenCode=123456 &AUTHPARAMS
Note
The call to AWS STS can be to the global endpoint or to any of the Regional endpoints that you activate your AWS account. For more information, see the AWS STS section of Regions and Endpoints.
The AUTHPARAMS
parameter in the example is a placeholder for your
signature. A signature is the authentication information that you
must include with AWS HTTP API requests. We recommend using the AWS SDKs
Comparing the AWS STS API operations
The following table compares features of the API operations in AWS STS that return temporary security credentials. To learn about the different methods you can use to request temporary security credentials by assuming a role, see Using IAM roles. To learn about the different AWS STS API operations that allow you to pass session tags, see Passing session tags in AWS STS.
Comparing your API options | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
AWS STS API | Who can call | Credential lifetime (min | max | default) | MFA support¹ | Session policy support² | Restrictions on resulting temporary credentials | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AssumeRole | IAM user or IAM role with existing temporary security credentials | 15 m | Maximum session duration setting³ | 1 hr | Yes | Yes |
Cannot call |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AssumeRoleWithSAML | Any user; caller must pass a SAML authentication response that indicates authentication from a known identity provider | 15 m | Maximum session duration setting³ | 1 hr | No | Yes |
Cannot call |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AssumeRoleWithWebIdentity | Any user; caller must pass an OIDC compliant JWT token that indicates authentication from a known identity provider | 15 m | Maximum session duration setting³ | 1 hr | No | Yes |
Cannot call |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
GetFederationToken | IAM user or AWS account root user |
IAM user: 15 m | 36 hr | 12 hr Root user: 15 m | 1 hr | 1 hr |
No | Yes |
Cannot call IAM operations using the AWS CLI or AWS API. This limitation does not apply to console sessions. Cannot call AWS STS operations except
SSO to console is allowed.⁵ |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
GetSessionToken | IAM user or AWS account root user |
IAM user: 15 m | 36 hr | 12 hr Root user: 15 m | 1 hr | 1 hr |
Yes | No |
Cannot call IAM API operations unless MFA information is included with the request. Cannot call AWS STS API operations except SSO to console is not allowed.⁶ |
¹ MFA support. You can include information about a multi-factor authentication (MFA) device when you call the AssumeRole and GetSessionToken API operations. This ensures that the temporary security credentials that result from the API call can be used only by users who are authenticated with an MFA device. For more information, see Configuring MFA-protected API access.
² Session policy support. Session policies are policies that you pass as a parameter when you programmatically create a temporary session for a role or federated user. This policy limits the permissions from the role or user's identity-based policy that are assigned to the session. The resulting session's permissions are the intersection of the entity's identity-based policies and the session policies. Session policies cannot be used to grant more permissions than those allowed by the identity-based policy of the role that is being assumed. For more information about role session permissions, see Session policies.
³ Maximum session duration setting. Use the
DurationSeconds
parameter to specify the duration of your role session from 900
seconds (15 minutes) up to the maximum session duration setting for the role. To learn how to
view the maximum value for your role, see View the maximum session duration setting
for a role.
⁴ GetCallerIdentity. No permissions are required
to perform this operation. If an administrator adds a policy to your IAM user or role that
explicitly denies access to the sts:GetCallerIdentity
action, you can still
perform this operation. Permissions are not required because the same information is returned
when an IAM user or role is denied access. To view an example response, see I am not authorized to
perform: iam:DeleteVirtualMFADevice.
⁵ Single sign-on (SSO) to the console. To support
SSO, AWS lets you call a federation endpoint (https://signin.aws.amazon.com/federation
) and pass
temporary security credentials. The endpoint returns a token that you can use to construct a
URL that signs a user directly into the console without requiring a password. For more
information, see Enabling SAML 2.0 federated users to
access the AWS Management Console and How to Enable Cross-Account Access to the AWS Management Console
⁶ After you retrieve your temporary credentials, you can't access the AWS Management Console by passing the credentials to the federation single sign-on endpoint. For more information, see Enabling custom identity broker access to the AWS console.