Menu
AWS Identity and Access Management
User Guide

Creating a Role for Web Identity or OpenID Connect Federation (AWS Management Console)

Before you can create a role for web identity federation, you must first complete the following prerequisite steps.

To prepare to create a role for web identity federation

  1. Begin by signing up as a developer with an IdP (or more than one). You also configure your app with the provider; when you do, the provider gives you an application or audience ID that's unique to your app. (Providers use different terminology for this process. This guide uses the term configure for the process of identifying your app with the provider.) Each provider gives you an app ID that's unique to that provider, so if you configure the same app with multiple providers, your app will have multiple app IDs. You can configure multiple apps with each provider. The following external links provide information about using one of the identity providers:

  2. After getting the required information from the identity provider, you can create an identity provider in IAM. For more information, see Creating OpenID Connect (OIDC) Identity Providers.

  3. Prepare the policies for the role that the IdP-authenticated users will assume. As with any role, a role for the mobile app contains two policies. One is the trust policy that specifies who can assume the role (the trusted entity or principal). The other policy (the access policy) specifies the actual AWS actions and resources that the mobile app is allowed or denied access to (similar to user or resource policies).

    For web identity providers, we recommend that you use Amazon Cognito to manage identities. In that case, the trust policy for the role must include a Statement similar to the following:

    Copy
    { "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Principal": {"Federated": "cognito-identity.amazonaws.com"}, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": {"cognito-identity.amazonaws.com:aud": "us-east-2:12345678-abcd-abcd-abcd-123456"}, "ForAnyValue:StringLike": {"cognito-identity.amazonaws.com:amr": "unauthenticated"} } } }

    Replace us-east-2:12345678-abcd-abcd-abcd-123456 with the actual identity pool ID that Amazon Cognito assigned to you.

    If you manually configure a web identity IdP, then the trust policy must grant an Allow effect for the sts:AssumeRoleWithWebIdentity action. In this role, you use two values that ensure that only your application can assume the role:

    • For the Principal element, use the string {"Federated":providerUrl/providerArn}.

      • For some common OpenID Connect (OIDC) IdPs, the providerUrl is the fully qualified URL. The following are acceptable ways to specify the principal for some common IdPs:

        "Principal":{"Federated":"cognito-identity.amazonaws.com"}

        "Principal":{"Federated":"www.amazon.com"}

        "Principal":{"Federated":"graph.facebook.com"}

        "Principal":{"Federated":"accounts.google.com"}

      • For other OIDC providers, use the ARN of the OIDC identity provicer you created in Step 2, like the following example:

        "Principal":{"Federated":"arn:aws:iam::123456789012:oidc-provider/server.example.com"}

    • In the Condition element, use a StringEquals condition to test whether the identity pool ID (for Amazon Cognito) or the app ID—also known as the client ID or audience—(for other providers) in the request matches the app ID that you got when you configured the app with the IdP. This ensures the request is coming from your app. In the Condition element of the policy, you can test the app ID you have against the following policy variables; which one you use depends on the IdP you are using:

      "Condition": {"StringEquals": {"cognito-identity.amazonaws.com:aud": "us-east:12345678-ffff-ffff-ffff-123456"}}

      "Condition": {"StringEquals": {"www.amazon.com:app_id": "amzn1.application-oa2-123456"}}

      "Condition": {"StringEquals": {"graph.facebook.com:app_id": "111222333444555"}}

      "Condition": {"StringEquals": {"accounts.google.com:aud": "666777888999000"}}

      For OIDC providers, use the fully qualified URL of the OIDC IdP with the aud context key, like the following example:

      "Condition": {"StringEquals": {"server.example.com:aud": "appid_from_oidc_idp"}}

    Notice that the values for the principal in the role are specific to an IdP. A role can specify only one principal. Therefore, if the mobile app allows users to sign in from more than one IdP, you must create a role for each IdP that you want to support.

    Note

    Because the policy for the trusted entity uses policy variables that represent the IdP and the app ID, you must set the policy's Version element to 2012-10-17 or a later supported version.

    The following example shows a trust policy for a role designed for a mobile app if the user signs in from Login with Amazon. In the example, amzn1.application-oa2-123456 represents the app ID that Amazon assigned when you configured the app using Login with Amazon.

    Copy
    { "Version": "2012-10-17", "Id": "RoleForLoginWithAmazon", "Statement": [{ "Effect": "Allow", "Principal": {"Federated": "www.amazon.com"}, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": {"StringEquals": {"www.amazon.com:app_id": "amzn1.application-oa2-123456"}} }] }

    The following example shows a policy for a role that the mobile app could assume if the user has signed in from Facebook. In this example, 111222333444555 represents the app ID assigned by Facebook.

    Copy
    { "Version": "2012-10-17", "Id": "RoleForFacebook", "Statement": [{ "Effect": "Allow", "Principal": {"Federated": "graph.facebook.com"}, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": {"StringEquals": {"graph.facebook.com:app_id": "111222333444555"}} }] }

    The following example shows a policy for a role that the mobile app could assume if the user has signed in from Google. In this example, 666777888999000 represents the app ID assigned by Google.

    Copy
    { "Version": "2012-10-17", "Id": "RoleForGoogle", "Statement": [{ "Effect": "Allow", "Principal": {"Federated": "accounts.google.com"}, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": {"StringEquals": {"accounts.google.com:aud": "666777888999000"}} }] }

    The following example shows a policy for a role that the mobile app could assume if the application is using Amazon Cognito. In this example, us-east:12345678-ffff-ffff-ffff-123456 represents the identity pool ID assigned by Amazon Cognito.

    Copy
    { "Version": "2012-10-17", "Id": "RoleForCognito", "Statement": [{ "Effect": "Allow", "Principal": {"Federated": "cognito-identity.amazonaws.com"}, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": {"StringEquals": {"cognito-identity.amazonaws.com:aud": "us-east:12345678-ffff-ffff-ffff-123456"}} }] }

    After you complete the prerequisites, you can create the role itself. The following procedure describes how to create the role for web identity/OIDC federation in the AWS Management Console. To create a role using the AWS CLI, Tools for Windows PowerShell, or AWS API, see the procedures at Creating a Role for a Third-Party Identity Provider (Federation).

To create an IAM role for web identity federation (IAM console)

If you are using Amazon Cognito, you should use the Amazon Cognito console to set up the roles. Otherwise, use the IAM console to create a role for web identity federation.

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, click Roles and then click Create New Role.

  3. For Role Name, type a role name that can help you identify the purpose of this role. Role names must be unique within your AWS account. Because various entities might reference the role, you cannot edit the name of the role after you create it. After you type the name, click Next Step at the bottom of the page.

    Important

    Role names must be unique within an account. They are not distinguished by case, for example, you cannot create roles named both "PRODROLE" and "prodrole".

  4. Select Role for Identity Provider Access and then click the Select button for Grant access to web identity providers.

  5. In the Identity Provider list, select the identity provider that you're creating the role for:

    • Select Amazon Cognito if you're creating a role for Amazon Cognito.

      Note

      You only need to manually create a role for use with Amazon Cognito when you are working on an advanced scenario. Otherwise, Amazon Cognito can create roles for you for standard scenarios. For more information about Amazon Cognito, see Amazon Cognito Identity in the AWS Mobile SDK for iOS Developer Guide and Amazon Cognito Identity in the AWS Mobile SDK for Android Developer Guide.

    • If you're creating a role for an individual web identity provider, select the name of the provider.

      Note

      You must create a separate role for each identity provider that you want to support.

  6. Enter the application ID that identifies your application. The name of the box for the ID changes depending on which provider you select.

    • If you're creating a role for Amazon Cognito, enter the ID of the identity pool you have created for your Amazon Cognito applications into the Identity Pool ID box.

    • If you're creating a role for an individual web identity provider, enter or select the client ID that the provider gave you when you registered your application with the provider.

  7. (Optional) Click Add Conditions to create additional conditions that must be met before users of your application can use the permissions granted by the role. For example, you can add a condition that grants access to AWS resources only for a specific user ID.

  8. Click Next Step to review the role's Trust Policy Document and then click Next Step.

  9. Select the managed policy that assigns the permissions that you want the federated users to have, and then click Next Step.

  10. Review the role and then click Create Role.