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

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 information such as scores and profiles is stored using Amazon S3 and DynamoDB. 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 create new user identities for each player. Instead, she builds the game so that users can sign in using an identity that they've already established with Amazon.com, Facebook, or Google. Her game can take advantage of the authentication mechanism from one of these providers to validate the user's identity.

To enable the mobile app to access her company's AWS resources, Adele first registers for a developer ID with Login with Amazon, Facebook, and Google. She also configures the application with each of these providers. In the AWS account that owns the Amazon S3 bucket and DynamoDB table for the game, Adele creates IAM roles that precisely define permissions that the game needs.

In the app's code, Adele calls the sign-in interface for the identity provider that the user selects. The provider handles all the details of letting the user sign in, and the app gets an OAuth access token or OpenID Connect (OIDC) ID token from the provider. Using this information, Adele's app can call the AWS Security Token Service (AWS STS) AssumeRoleWithWebIdentity action. This action returns temporary security credentials consisting of an AWS access key ID, a secret access key, and a session token. The user's instance of the app caches the temporary security credentials and uses them to access AWS services. The app is limited to the permissions defined in the role that it assumes. When the temporary credentials expire, the mobile app makes another call to AWS STS in order to get a new set of temporary security credentials.

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

The following details enable this scenario:

  • Adele the developer has registered the mobile app with different identity providers, who have assigned an app ID to the app.

  • The mobile app includes logic to invoke the appropriate identity provider (depending on which sign-in option the user chooses) and to get back a token from the provider.

  • The app can call AssumeRoleWithWebIdentity without using any AWS security credentials. The call includes the token from the provider received previously.

  • AWS STS is able to verify that the token passed from Adele's app is valid and then returns temporary security credentials to the app. The mobile app's permissions to access AWS are established by the role that the app assumes.

You can learn more about web identity federation by working with the following sample applications:

  • The Web Identity Federation Playground is an interactive website that lets you walk through the process of authenticating via Login with Amazon, Facebook, or Google, getting temporary security credentials, and then using those credentials to make a request to AWS.

  • The AWS SDK for iOS and AWS SDK for Android toolkits include a sample application that demonstrates how to access an Amazon S3 bucket.

Creating a Mobile App with Custom Authentication

A company is building a mobile app that enables the app's registered users to access the company's AWS resources on the back end. Unlike the previous scenario, users don't sign in using one of the supported web identity federation providers (Login with Amazon, Facebook, or Google). Instead, the company wants to use a custom solution for authenticating users and for managing the identity store. As in the previous scenario, the company doesn't want to distribute any AWS security credentials with the app.

Dave is the developer for this app. To enable the mobile app to access the company's AWS resources, Dave develops a custom identity broker application that runs on Amazon EC2. When the mobile app runs, it communicates with the custom identity broker. The broker application verifies that the users are authenticated and then calls an AWS STS action to get temporary security credentials. The application can call either AssumeRole or GetFederationToken to obtain the temporary credentials, depending on how Dave 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 Permissions in Temporary Security Credentials for Federated Users.)

The AWS STS API returns temporary security credentials consisting of an AWS access key ID, a secret access key, and a session token. The custom identity broker application returns these temporary security credentials to the mobile app. 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.

The following details enable this scenario:

  • The identity broker application has available a set of long-term AWS security credentials that are associated with an IAM user that it can use to call the AssumeRole or GetFederationToken action. The identity broker application runs in a server environment, where the credentials for the IAM user are not accessible to the apps running on mobile devices.

  • The identity broker application (via the security credentials it uses to make the call) has permission to access the AWS STS API to create temporary security credentials.

  • The identity broker application is able to verify that the mobile app users are authenticated.

To see a sample application similar to the application described in this scenario, go to Authenticating Users of AWS Mobile Applications with a Token Vending Machine at AWS Articles & Tutorials. For information about creating temporary security credentials, see Creating Temporary Security Credentials.

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 Permissions in Temporary Security Credentials for Federated Users.) 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.

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 Creating Temporary Security Credentials for SAML 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.