AWS Security Token Service
Using Temporary Security Credentials (API Version 2011-06-15)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
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.

Scenarios for Granting Temporary Access

You might choose to use temporary security credentials for several reasons. This section describes the most common scenarios.

Creating a Mobile App with Third-Party Sign-In

Adele the developer is building a game for a mobile device where user data such as scores and profiles is stored using Amazon S3 and Amazon DynamoDB. Adele could also store this data locally on the device and use Amazon Cognito to keep it in sync across devices. For more information about Amazon Cognito, see Amazon Cognito She knows that for security and maintenance reasons, long-term AWS security credentials should not be distributed with the game. She also knows that the game might have a large number of users. For all of these reasons, she does not want to create new user identities in IAM for each player. Instead, she builds the game so that users can sign in using an identity that they've already established with a well-known identity provider, such as Login with Amazon, Facebook, Google, or any OpenID Connect (OIDC)-compatible identity provider. Her game can take advantage of the authentication mechanism from one of these providers to validate the user's identity.


For most mobile application scenarios, we recommend that you use Amazon Cognito. You can use this service with the AWS Mobile SDK for iOS and the AWS Mobile SDK for Android and Fire OS to create unique identities for users and authenticate them for secure access to your AWS resources. Amazon Cognito supports the same identity providers as those listed in this section, and it also supports developer authenticated identities and unauthenticated (guest) access. Amazon Cognito also provides APIs for synchronizing user data so that it is preserved as users move between devices. For more information, see Amazon Cognito and the Amazon Cognito documentation.

To enable the mobile app to access her AWS resources, Adele first registers for a developer ID with Login with Amazon, Facebook, Google, or any other OIDC-compliant identity provider. She also configures the application with each of these providers. In her AWS account that contains the Amazon S3 bucket and DynamoDB table for the game, Adele uses Amazon Cognito to create IAM roles that precisely define permissions that the game needs. If she is using an OIDC identity provider, she also creates an IAM OIDC provider entity to establish trust between her AWS account and the identity provider.

In the app's code, Adele calls the sign-in interface for the identity provider that she configured previously. The provider handles all the details of letting the user sign in, and the app gets an OAuth access token or OIDC ID token from the provider. Adele's app can trade this authentication information for a set of temporary security credentials that consist of an AWS access key ID, a secret access key, and a session token. The app can then use these credentials to access AWS services. The app is limited to the permissions that are defined in the role that it assumes.

The following figure shows a simplified flow for how this might work, using Login with Amazon as the identity provider. For Step 2, the app can also use Facebook, Google, or any OIDC-compatible identity provider, but that's not shown here.

Diagram of a mobile app that uses AWS STS web identity federation.

Using Your Organization's Authentication System to Grant Access to AWS Resources

Example Corp. has many employees who need to run internal applications that access the company's AWS resources. The employees already have identities in the company identity and authentication system, and Example Corp. doesn't want to create a separate IAM user for each company employee.

Bob is a developer at Example Corp. To enable Example Corp. internal applications to access the company's AWS resources, Bob develops a custom identity broker application. The application verifies that employees are signed into the existing Example Corp. identity and authentication system, which might use LDAP, Active Directory, or another system. The identity broker application then obtains temporary security credentials for the employees. This scenario is similar to the previous one (a mobile app that uses a custom authentication system), except that the applications that need access to AWS resources all run within the corporate network, and the company has an existing authentication system.

To get temporary security credentials, the identity broker application calls either AssumeRole or GetFederationToken to obtain temporary security credentials, depending on how Bob wants to manage the policies for users and when the temporary credentials should expire. (For more information about the differences between these APIs, see Ways to Get Temporary Security Credentials and Controlling Permissions for Temporary Security Credentials.) The call returns temporary security credentials consisting of an AWS access key ID, a secret access key, and a session token. The identity broker application makes these temporary security credentials available to the internal application. The app can then use the temporary credentials to make calls to AWS directly. The app caches the credentials until they expire, and then requests a new set of temporary credentials. The following figure illustrates this scenario.

Diagram of enterprise identity broker application interacting with AWS STS

In this scenario:

  • The identity broker application has permissions to access the AWS STS API to create temporary security credentials.

  • The identity broker application is able to verify that employees are authenticated within the existing authentication system.

  • Users are able to get a temporary URL that gives them access to the AWS Management Console (which is referred to as single sign-on).

To see a sample application similar to the identity broker application described in this scenario, go to Identity Federation Sample Application for an Active Directory Use Case at AWS Sample Code & Libraries. For information about creating temporary security credentials, see Creating Temporary Security Credentials. For more information about federated users getting access to the AWS Management Console, see Giving Federated Users Direct Access to the AWS Management Console.

Using Your Organization's Authentication System and SAML to Grant Access to AWS Resources

Clarisse is an administrator who works at an organization that uses a SAML 2.0-compliant identity provider (IdP) to implement identity federation. In Clarisse's organization, an identity provider can authenticate users against an internal identity store. The IdP can then produce SAML assertions that indicate who the user is and that include information that can be used for authorization decisions by a service provider. Clarisse configures her organization's identity provider, and configures AWS as a service provider that can trust authentication responses from her organization.

Clarisse writes an application that runs on user's computers in her organization and that stores objects in Amazon S3 buckets. The application can get user information and ask the identity provider for an authentication response (assertion). It can then call the AWS STS AssumeRoleWithSAML API, passing the assertion and additional information.

The API returns temporary security credentials, which Clarisse's application can use to make calls to AWS directly. The following figure illustrates this scenario.

Getting temporary security credentials based on a SAML assertion

This scenario is similar to the previous one (using an organization's existing identity system). However, because Clarisse's organization uses SAML 2.0, the SAML identity provider in her organization can do much of the work associated with verifying a user's identity and generating information that can be passed to service providers, using an open standard for security information. AWS supports SAML 2.0 for establishing trust and for mapping assertions to IAM roles that determine a user's permissions.

For more information, see About AWS STS SAML 2.0-based Federation.

Web-Based Single Sign-On (SSO)

Some users who are in an administrative group in your organization need to be able to go to the AWS Management Console and administer Amazon EC2 instances. You don't want to create new IAM users for each administrative user and make those users sign in again to the AWS Management Console.

Instead, you can create a SSO experience for your users. They can go to a portal in your organization, where they're already signed in. From the portal they can choose an option to go to the AWS Management Console. If they're authorized for AWS access, they're redirected to the AWS Management Console without having to sign in again. Behind the scenes, authentication information about the users is exchanged for temporary security credentials that are associated with an IAM role that determines what the users are allowed to do in AWS.

You can configure SSO in these ways:

  • If your organization has an identity system that integrates SAML 2.0 (Security Assertion Markup Language 2.0), you can set things up in your organization and in IAM so that users can seamlessly be redirected to the AWS Management Console. For details, see Giving AWS Console Access to Federated Users Using SAML.

  • For other scenarios, you can write code that creates a URL that includes identity information and that you can distribute to users and that gives them secure and direct access to the AWS Management Console. For details, see Giving AWS Console Access to Federated Users by Creating a URL.

Delegating API Access

With IAM roles, you can delegate API access to AWS services (including third-party services) so that they can access your organization's AWS resources with temporary security credentials. Authorized IAM users or services can then use the temporary security credentials to access the resources that are defined in the role.

For more information, see Delegating API Access by Using Roles in Using IAM.

Cross-Account API Access

Occasionally, your organization might have resources that users must access across multiple AWS accounts. To allow this access, you can establish trust between accounts so that users from one account can access resources in another account. Using IAM roles, you define trusted entities and the actions they are permitted to do.

For more information, see Enabling Cross-Account API Access in Using IAM.