Using Web Federated Identity to Authenticate Users - Amazon SDK for JavaScript
Step 1: Registering with Identity ProvidersStep 2: Creating an IAM Role for an Identity ProviderStep 3: Obtaining a Provider Access Token After LoginStep 4: Obtaining Temporary Credentials
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

We announced the upcoming end-of-support for Amazon SDK for JavaScript v2. We recommend that you migrate to Amazon SDK for JavaScript v3. For dates, additional details, and information on how to migrate, please refer to the linked announcement.

Using Web Federated Identity to Authenticate Users

You can directly configure individual identity providers to access Amazon resources using web identity federation. Amazon currently supports authenticating users using web identity federation through several identity providers:

You must first register your application with the providers that your application supports. Next, create an IAM role and set up permissions for it. The IAM role you create is then used to grant the permissions you configured for it through the respective identity provider. For example, you can set up a role that allows users who logged in through Facebook to have read access to a specific Amazon S3 bucket you control.

After you have both an IAM role with configured privileges and an application registered with your chosen identity providers, you can set up the SDK to get credentials for the IAM role using helper code, as follows:

AWS.config.credentials = new AWS.WebIdentityCredentials({
   RoleArn: 'arn:aws:iam::<AWS_ACCOUNT_ID>/:role/<WEB_IDENTITY_ROLE_NAME>',
   ProviderId: 'graph.facebook.com|www.amazon.com', // this is null for Google
   WebIdentityToken: ACCESS_TOKEN
});

The value in the ProviderId parameter depends on the specified identity provider. The value in the WebIdentityToken parameter is the access token retrieved from a successful login with the identity provider. For more information on how to configure and retrieve access tokens for each identity provider, see the documentation for the identity provider.

Step 1: Registering with Identity Providers

To begin, register an application with the identity providers you choose to support. You will be asked to provide information that identifies your application and possibly its author. This ensures that the identity providers know who is receiving their user information. In each case, the identity provider will issue an application ID that you use to configure user roles.

Step 2: Creating an IAM Role for an Identity Provider

After you obtain the application ID from an identity provider, go to the IAM console at https://console.amazonaws.cn/iam/ to create a new IAM role.

To create an IAM role for an identity provider

  1. Go to the Roles section of the console and then choose Create New Role.

  2. Type a name for the new role that helps you keep track of its use, such as facebookIdentity, and then choose Next Step.

  3. In Select Role Type, choose Role for Identity Provider Access.

  4. For Grant access to web identity providers, choose Select.

  5. From the Identity Provider list, choose the identity provider that you want to use for this IAM role.

    Selecting Role for Identity Provider Access

  6. Type the application ID provided by the identity provider in Application ID and then choose Next Step.

  7. Configure permissions for the resources you want to expose, allowing access to specific operations on specific resources. For more information about IAM permissions, see Overview of Amazon IAM Permissions in the IAM User Guide. Review and, if needed, customize the role's trust relationship, and then choose Next Step.

  8. Attach additional policies you need and then choose Next Step. For more information about IAM policies, see Overview of IAM Policies in the IAM User Guide.

  9. Review the new role and then choose Create Role.

You can provide other constraints to the role, such as scoping it to specific user IDs. If the role grants write permissions to your resources, make sure you correctly scope the role to users with the correct privileges, otherwise any user with an Amazon, Facebook, or Google identity will be able to modify resources in your application.

For more information on using web identity federation in IAM, see About Web Identity Federation in the IAM User Guide.

Step 3: Obtaining a Provider Access Token After Login

Set up the login action for your application by using the identity provider's SDK. You can download and install a JavaScript SDK from the identity provider that enables user login, using either OAuth or OpenID. For information on how to download and set up the SDK code in your application, see the SDK documentation for your identity provider:

Step 4: Obtaining Temporary Credentials

After your application, roles, and resource permissions are configured, add the code to your application to obtain temporary credentials. These credentials are provided through the Amazon Security Token Service using web identity federation. Users log in to the identity provider, which returns an access token. Set up the AWS.WebIdentityCredentials object using the ARN for the IAM role you created for this identity provider:

AWS.config.credentials = new AWS.WebIdentityCredentials({
    RoleArn: 'arn:aws:iam::<AWS_ACCOUNT_ID>:role/<WEB_IDENTITY_ROLE_NAME>',
    ProviderId: 'graph.facebook.com|www.amazon.com', // Omit this for Google
    WebIdentityToken: ACCESS_TOKEN // Access token from identity provider
});

Service objects that are created subsequently will have the proper credentials. Objects created before setting the AWS.config.credentials property won't have the current credentials.

You can also create AWS.WebIdentityCredentials before retrieving the access token. This allows you to create service objects that depend on credentials before loading the access token. To do this, create the credentials object without the WebIdentityToken parameter:

AWS.config.credentials = new AWS.WebIdentityCredentials({
  RoleArn: 'arn:aws:iam::<AWS_ACCOUNT_ID>:role/<WEB_IDENTITY_ROLE_NAME>',
  ProviderId: 'graph.facebook.com|www.amazon.com' // Omit this for Google
});

// Create a service object
var s3 = new AWS.S3;

Then set WebIdentityToken in the callback from the identity provider SDK that contains the access token:

AWS.config.credentials.params.WebIdentityToken = accessToken;