# Using web identity federation
If you are writing an application targeted at large numbers of users, you can optionally use *web identity federation* for authentication and authorization. Web identity federation removes the need for creating individual users. Instead, users can sign in to an identity provider and then obtain temporary security credentials from AWS Security Token Service (AWS STS). The app can then use these credentials to access AWS services.
Web identity federation supports the following identity providers:
+ Login with Amazon
+ Facebook
+ Google
## Additional resources for web identity federation
The following resources can help you learn more about web identity federation:
+ The post [Web Identity Federation using the AWS SDK for .NET](https://aws.amazon.com/blogs/developer/web-identity-federation-using-the-aws-sdk-for-net) on the AWS Developer blog walks through how to use web identity federation with Facebook. It includes code snippets in C\$1 that show how to assume an IAM role with web identity and how to use temporary security credentials to access an AWS resource.
+ The [AWS Mobile SDK for iOS](https://aws.amazon.com/sdkforios/) and the [AWS Mobile SDK for Android](https://aws.amazon.com/sdkforandroid/) contain sample apps. They include code that shows how to invoke the identity providers, and then how to use the information from these providers to get and use temporary security credentials.
+ The article [Web Identity Federation with Mobile Applications](https://aws.amazon.com/articles/4617974389850313) discusses web identity federation and shows an example of how to use web identity federation to access an AWS resource.
## Example policy for web identity federation
To show how you can use web identity federation with DynamoDB, revisit the *GameScores* table that was introduced in [Using IAM policy conditions for fine-grained access control](specifying-conditions.md). Here is the primary key for *GameScores*.
****
| Table Name | Primary Key Type | Partition Key Name and Type | Sort Key Name and Type |
| --- | --- | --- | --- |
| GameScores (UserId, GameTitle, ...) | Composite | Attribute Name: UserId Type: String | Attribute Name: GameTitle Type: String |
Now suppose that a mobile gaming app uses this table, and that app needs to support thousands, or even millions, of users. At this scale, it becomes very difficult to manage individual app users, and to guarantee that each user can only access their own data in the *GameScores* table. Fortunately, many users already have accounts with a third-party identity provider, such as Facebook, Google, or Login with Amazon. So it makes sense to use one of these providers for authentication tasks.
To do this using web identity federation, the app developer must register the app with an identity provider (such as Login with Amazon) and obtain a unique app ID. Next, the developer needs to create an IAM role. (For this example, this role is named *GameRole*.) The role must have an IAM policy document attached to it, specifying the conditions under which the app can access *GameScores* table.
When a user wants to play a game, they sign in to their Login with Amazon account from within the gaming app. The app then calls AWS Security Token Service (AWS STS), providing the Login with Amazon app ID and requesting membership in *GameRole*. AWS STS returns temporary AWS credentials to the app and allows it to access the *GameScores* table, subject to the *GameRole* policy document.
The following diagram shows how these pieces fit together.
![\[A gaming app’s workflow. The app uses Amazon ID and AWS STS to obtain temporary credentials for accessing a DynamoDB table.\]](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/images/wif-overview.png)
**Web identity federation overview**
1. The app calls a third-party identity provider to authenticate the user and the app. The identity provider returns a web identity token to the app.
1. The app calls AWS STS and passes the web identity token as input. AWS STS authorizes the app and gives it temporary AWS access credentials. The app is allowed to assume an IAM role (*GameRole*) and access AWS resources in accordance with the role's security policy.
1. The app calls DynamoDB to access the *GameScores* table. Because it has assumed the *GameRole*, the app is subject to the security policy associated with that role. The policy document prevents the app from accessing data that does not belong to the user.
Once again, here is the security policy for *GameRole* that was shown in [Using IAM policy conditions for fine-grained access control](specifying-conditions.md):
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"AllowAccessToOnlyItemsMatchingUserID",
"Effect":"Allow",
"Action":[
"dynamodb:GetItem",
"dynamodb:BatchGetItem",
"dynamodb:Query",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:BatchWriteItem"
],
"Resource":[
"arn:aws:dynamodb:us-west-2:123456789012:table/GameScores"
],
"Condition":{
"ForAllValues:StringEquals":{
"dynamodb:LeadingKeys":[
"${www.amazon.com:user_id}"
],
"dynamodb:Attributes":[
"UserId",
"GameTitle",
"Wins",
"Losses",
"TopScore",
"TopScoreDateTime"
]
},
"StringEqualsIfExists":{
"dynamodb:Select":"SPECIFIC_ATTRIBUTES"
}
}
}
]
}
```
------
The `Condition` clause determines which items in *GameScores* are visible to the app. It does this by comparing the Login with Amazon ID to the `UserId` partition key values in `GameScores`. Only the items belonging to the current user can be processed using one of DynamoDB actions that are listed in this policy. Other items in the table cannot be accessed. Furthermore, only the specific attributes listed in the policy can be accessed.
# Preparing to use web identity federation
If you are an application developer and want to use web identity federation for your app, follow these steps:
1. **Sign up as a developer with a third-party identity provider.** The following external links provide information about signing up with supported identity providers:
+ [Login with Amazon Developer Center](http://login.amazon.com/)
+ [Registration](https://business.facebook.com/business/loginpage) on the Facebook site
+ [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/accounts/docs/OAuth2) on the Google site
1. **Register your app with the identity provider.** When you do this, the provider gives you an ID that's unique to your app. If you want your app to work with multiple identity providers, you need to obtain an app ID from each provider.
1. **Create one or more IAM roles. **You need one role for each identity provider for each app. For example, you might create a role that can be assumed by an app where the user signed in using Login with Amazon, a second role for the same app where the user has signed in using Facebook, and a third role for the app where users sign in using Google.
As part of the role creation process, you need to attach an IAM policy to the role. Your policy document should define the DynamoDB resources required by your app, and the permissions for accessing those resources.
For more information, see [About Web Identity Federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html) in *IAM User Guide*.
**Note**
As an alternative to AWS Security Token Service, you can use Amazon Cognito. Amazon Cognito is the preferred service for managing temporary credentials for mobile apps. For more information, see [Getting credentials](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-credentials.html) in the *Amazon Cognito Developer Guide.*
## Generating an IAM policy using the DynamoDB console
The DynamoDB console can help you create an IAM policy for use with web identity federation. To do this, you choose a DynamoDB table and specify the identity provider, actions, and attributes to be included in the policy. The DynamoDB console then generates a policy that you can attach to an IAM role.
1. Sign in to the AWS Management Console and open the DynamoDB console at [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/).
1. In the navigation pane, choose **Tables**.
1. In the list of tables, choose the table for which you want to create the IAM policy.
1. Select the **Actions** button, and choose **Create Access Control Policy**.
1. Choose the identity provider, actions, and attributes for the policy.
When the settings are as you want them, choose **Generate Policy**. The generated policy appears.
1. Choose **See Documentation**, and follow the steps required to attach the generated policy to an IAM role.
# Writing your app to use web identity federation
To use web identity federation, your app must assume the IAM role that you created. From that point on, the app honors the access policy that you attached to the role.
At runtime, if your app uses web identity federation, it must follow these steps:
1. **Authenticate with a third-party identity provider.** Your app must call the identity provider using an interface that they provide. The exact way in which you authenticate the user depends on the provider and on what platform your app is running. Typically, if the user is not already signed in, the identity provider takes care of displaying a sign-in page for that provider.
After the identity provider authenticates the user, the provider returns a web identity token to your app. The format of this token depends on the provider, but is typically a very long string of characters.
1. **Obtain temporary AWS security credentials.** To do this, your app sends a `AssumeRoleWithWebIdentity` request to AWS Security Token Service (AWS STS). This request contains the following:
+ The web identity token from the previous step
+ The app ID from the identity provider
+ The Amazon Resource Name (ARN) of the IAM role that you created for this identity provider for this app
AWS STS returns a set of AWS security credentials that expire after a certain amount of time (3,600 seconds, by default).
The following is a sample request and response from a `AssumeRoleWithWebIdentity` action in AWS STS. The web identity token was obtained from the Login with Amazon identity provider.
```
GET / HTTP/1.1
Host: sts.amazonaws.com
Content-Type: application/json; charset=utf-8
URL: https://sts.amazonaws.com/?ProviderId=www.amazon.com
&DurationSeconds=900&Action=AssumeRoleWithWebIdentity
&Version=2011-06-15&RoleSessionName=web-identity-federation
&RoleArn=arn:aws:iam::123456789012:role/GameRole
&WebIdentityToken=Atza|IQEBLjAsAhQluyKqyBiYZ8-kclvGTYM81e...(remaining characters omitted)
```
```
amzn1.account.AGJZDKHJKAUUSW6C44CHPEXAMPLE
AQoDYXdzEMf//////////wEa8AP6nNDwcSLnf+cHupC...(remaining characters omitted)
8Jhi60+EWUUbbUShTEsjTxqQtM8UKvsM6XAjdA==
2013-10-01T22:14:35Z
06198791C436IEXAMPLE
arn:aws:sts::123456789012:assumed-role/GameRole/web-identity-federation
AROAJU4SA2VW5SZRF2YMG:web-identity-federation
c265ac8e-2ae4-11e3-8775-6969323a932d
```
1. **Access AWS resources.** The response from AWS STS contains information that your app requires in order to access DynamoDB resources:
+ The `AccessKeyID`, `SecretAccessKey`, and `SessionToken` fields contain security credentials that are valid for this user and this app only.
+ The `Expiration` field signifies the time limit for these credentials, after which they are no longer valid.
+ The `AssumedRoleId` field contains the name of a session-specific IAM role that has been assumed by the app. The app honors the access controls in the IAM policy document for the duration of this session.
+ The `SubjectFromWebIdentityToken` field contains the unique ID that appears in an IAM policy variable for this particular identity provider. The following are the IAM policy variables for supported providers, and some example values for them:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WIF.RunningYourApp.html)
For example IAM policies where these policy variables are used, see [Example policies: Using conditions for fine-grained access control](specifying-conditions.md#FGAC_DDB.Examples).
For more information about how AWS STS generates temporary access credentials, see [Requesting Temporary Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html) in *IAM User Guide*.