AWS Security Token Service
Using Temporary Security Credentials (API Version 2011-06-15)
Next »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

What Is AWS Security Token Service?

Introduction

With the AWS Security Token Service ( AWS STS ) you can provide a trusted user with temporary, limited access to your Amazon Web Services (AWS) resources. Here are some are examples of when temporary access is useful:

  • Federation. By using federation in AWS, you can grant temporary access to people in a corporate network without having to define individual IAM identities for each corporate user. For example, you can let these federated users sign in to the AWS Management Console without having to be defined as IAM users. We refer to this as single sign-on (SSO). AWS STS supports open standards like SAML 2.0 (Security Assertion Markup Language 2.0), or you can manage your own solution for federating user identities.

  • Federation for mobile apps. You can grant access to a user who logs in to a mobile application using Login with Amazon, Amazon Cognito, Facebook, or Google. Users don't have to have IAM identities. (We refer to this as web identity federation.)

  • Cross-account access. This lets IAM users in one account access resources in another account. (We refer to this as cross-account API access.)

  • Security management for applications running on Amazon EC2 instances that need access to AWS resources. (We refer to this as delegating API access by using roles.)

  • Security management to scope down permissions at run time. This is useful for IAM users who are using multi-factor authentication (MFA).

You can use temporary security credentials to access most AWS services. For a list of the services that accept temporary security credentials, see AWS Services that Support AWS Security Token Service (AWS STS).

Ways to Get Temporary Security Credentials

To request temporary security credentials using the AWS STS, you can call the API actions listed in the following table. The table lists typical scenarios for using each API.

You can call the APIs using one of the AWS SDKs, which are available in a variety of programming languages, including Java, .NET, Python, Ruby, Android, and iOS. The SDKs take care of tasks such as cryptographically signing your service requests, retrying requests if necessary, and handling error responses. You can also use the AWS STS Query API, which is described in the AWS Security Token Service API Reference.

For information about functional differences among these APIs, see Comparing Features of AWS STS APIs.

AWS Security Token Service API Actions

Action (API)Description
AssumeRole

Returns a set of temporary security credentials. You call this API by using the credentials of an existing IAM user. This API is useful for granting AWS access to users who do not have an IAM identity (that is, to federated users). It is also useful for allowing existing IAM users to access AWS resources that they don't already have access to, such as resources in another AWS account. For more information, see Creating Temporary Security Credentials for Delegating API Access.

AssumeRoleWithWebIdentity

Returns a set of temporary security credentials for federated users who are authenticated using a public identity provider such as Login with Amazon, Amazon Cognito, Facebook, or Google. This API is useful for creating mobile applications or client-based web applications that require access to AWS, in which users do not have their own AWS or IAM identities. For more information, see Creating a Role to Allow AWS Access for the Mobile App.

Note

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 the following:

AssumeRoleWithSAML

Returns a set of temporary security credentials for federated users who are authenticated in your organization and who pass authentication and authorization information to AWS using SAML 2.0. (Security Assertion Markup Language). This API is useful in organizations that have integrated their identity systems (such as Windows Active Directory) with software that can produce SAML assertions to provide information about user identity and permissions. For more information, see Creating Temporary Security Credentials for SAML Federation.

GetFederationToken

Returns a set of temporary security credentials for federated users. This API differs from AssumeRole in that the default expiration period is substantially longer (up to 36 hours instead of up to 1 hour). The longer expiration period can help reduce the number of calls to AWS because you do not need to get new credentials as often. For more information, see Creating Temporary Security Credentials to Enable Access for Federated Users.

GetSessionToken

Returns a set of temporary security credentials to an existing IAM user. This API is useful for providing enhanced security, for example, making AWS requests when MFA is enabled for the IAM user. For more information, see Creating Temporary Security Credentials to Enable Access for IAM Users.


The AWS STS API actions return temporary security credentials that consist of an access key (that is, an access key ID and a secret access key), and a session token. Users (or an application that the user is running) can use these credentials to access your resources. The credentials are associated with an IAM access control policy that limits what the user can do when using the credentials. For more information, see Requesting AWS Resources Using Temporary Security Credentials.

Important

Although temporary security credentials are short-lived, users who have temporary access can make lasting changes to your AWS resources. For example, if a user with temporary access launches an Amazon EC2 instance, the instance can continue to run and incur charges against your AWS account even after the user's temporary security credentials expire.

Comparing Features of AWS STS APIs

The following table lists features of the actions (APIs) in AWS STS that return temporary security credentials.

For general information about these APIs and their intended purposes, see Ways to Get Temporary Security Credentials.

AWS STS API Who can call Credential lifetime (min/max/default) MFA support Passed policy support Restrictions on resulting temporary credentials
AssumeRole IAM user or user with existing temporary security credentials 15m/1hr/1hr Yes Yes

Cannot call GetFederationToken or GetSessionToken.

AssumeRoleWithSAML Any user; caller must pass a SAML authentication response that indicates authentication from a known identity provider. 15m/1hr/1hrNoYes

Cannot call GetFederationToken or GetSessionToken.

AssumeRoleWithWebIdentity Any user; caller must pass a web identity token that indicates authentication from a known identity provider. 15m/1hr/1hr NoYes

Cannot call GetFederationToken or GetSessionToken.

GetFederationTokenIAM user or root account

IAM user: 15m/36hr/12hr

Root account: 15m/1hr/1hr

No Yes

Cannot call IAM APIs directly.

SSO to console is allowed.

Cannot call AWS STS APIs.

GetSessionTokenIAM user or root account

IAM user: 15m/36hr/12hr

Root account: 15m/1hr/1hr

Yes No

Cannot call IAM APIs unless MFA information is included with the request.

Cannot call AWS STS APIs except AssumeRole.

Single sign-on (SSO) to console not allowed, but any user with a password (root or IAM user) can sign into the console.


Pricing of AWS STS

AWS Security Token Service is a feature of your AWS account offered at no additional charge. You will be charged only for use of other AWS services by your AWS STS temporary security credentials. For information about the pricing of other AWS services, see the Amazon Web Services pricing page.

Advantages of Temporary Security Credentials

Using AWS Security Token Service to get temporary security credentials has the following advantages:

  • You do not have to distribute long-term AWS security credentials with an application.

  • You can provide access to your AWS resources to users without having to define an AWS identity for them.

  • The temporary security credentials have a limited lifetime, so you do not have to rotate them or explicitly revoke them when they're no longer needed. After temporary security credentials expire, they cannot be reused. You can specify how long the credentials are valid, up to a maximum limit.