Using OIDC federation API operations for mobile apps - Amazon Identity and Access Management
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).

Using OIDC federation API operations for mobile apps

For best results, use Amazon Cognito as your identity broker for almost all OIDC federation scenarios. Amazon Cognito is easy to use and provides additional capabilities like anonymous (unauthenticated) access, and synchronizing user data across devices and providers. However, if you have already created an app that uses OIDC federation by manually calling the AssumeRoleWithWebIdentity API, you can continue to use it and your apps will still work fine.

The process for using OIDC federation without Amazon Cognito follows this general outline:

  1. Sign up as a developer with the external identity provider (IdP) and configure your app with the IdP, who gives you a unique ID for your app. (Different IdPs use different terminology for this process. This outline uses the term configure for the process of identifying your app with the IdP.) Each IdP gives you an app ID that's unique to that IdP, so if you configure the same app with multiple IdPs, your app will have multiple app IDs. You can configure multiple apps with each provider.

    The following external links provide information about using some of the commonly used identity providers (IdPs):


    If you use an OIDC identity provider from Google, Facebook, or Amazon Cognito, do not create a separate IAM identity provider in the Amazon Web Services Management Console. Amazon has these OIDC identity providers built-in and available for your use. Skip the following step and move directly to creating new roles using your identity provider.

  2. If you use an IdP other than Google, Facebook or Amazon Cognito compatible with OIDC, then create an IAM identity provider entity for it.

  3. In IAM, create one or more roles. For each role, define who can assume the role (the trust policy) and what permissions the app's users have (the permissions policy). Typically, you create one role for each IdP that an app supports. For example, you might create a role assumed by an app if the user signs in through Login with Amazon, a second role for the same app if the user signs in through Facebook, and a third role for the app if the user signs in through Google. For the trust relationship, specify the IdP (like as the Principal (the trusted entity), and include a Condition that matches the IdP assigned app ID. Examples of roles for different providers are described in Creating a role for a third-party Identity Provider (federation).

  4. In your application, authenticate your users with the IdP. The specifics of how to do this vary both according to which IdP you use (Login with Amazon, Facebook, or Google) and on which platform your app runs. For example, an Android app's method of authentication can differ from that of an iOS app or a JavaScript-based web app.

    Typically, if the user is not already signed in, the IdP takes care of displaying a sign-in page. After the IdP authenticates the user, the IdP returns an authentication token with information about the user to your app. The information included depends on what the IdP exposes and what information the user is willing to share. You can use this information in your app.

  5. In your app, make an unsigned call to the AssumeRoleWithWebIdentity action to request temporary security credentials. In the request, you pass the IdP's authentication token and specify the Amazon Resource Name (ARN) for the IAM role that you created for that IdP. Amazon verifies that the token is trusted and valid and if so, returns temporary security credentials to your app that have the permissions for the role that you name in the request. The response also includes metadata about the user from the IdP, such as the unique user ID that the IdP associates with the user.

  6. Using the temporary security credentials from the AssumeRoleWithWebIdentity response, your app makes signed requests to Amazon API operations. The user ID information from the IdP can distinguish users in your app. For example, you can put objects into Amazon S3 folders that include the user ID as prefixes or suffixes. This lets you create access control policies that lock the folder so only the user with that ID can access it. For more information, see Amazon STS federated user session principals.

  7. Your app should cache the temporary security credentials so that you do not have to get new ones each time the app needs to make a request to Amazon. By default, the credentials are good for one hour. When the credentials expire (or before then), you make another call to AssumeRoleWithWebIdentity to obtain a new set of temporary security credentials. Depending on the IdP and how they manage their tokens, you might have to refresh the IdP's token before you make a new call to AssumeRoleWithWebIdentity, since the IdP's tokens also usually expire after a fixed time. If you use the Amazon SDK for iOS or the Amazon SDK for Android, you can use the AmazonSTSCredentialsProvider action, which manages the IAM temporary credentials, including refreshing them as required.