Create a role for OpenID Connect federation (console) - 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).

Create a role for OpenID Connect federation (console)

You can use OpenID Connect (OIDC) federated identity providers instead of creating Amazon Identity and Access Management users in your Amazon Web Services account. With an identity provider (IdP), you can manage your user identities outside of Amazon and give these external user identities permissions to access Amazon resources in your account. For more information about federation and IdPs, see Identity providers and federation.

Prerequisites for creating a role for OIDC

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

To prepare to create a role for OIDC federation
  1. Sign up with one or more services offering federated OIDC identity. If you are creating an app that needs access to your Amazon resources, you also configure your app with the provider information. When you do, the provider gives you an application or audience ID that is unique to your app. (Different providers use different terminology for this process. This guide uses the term configure for the process of identifying your app with the provider.) You can configure multiple apps with each provider, or multiple providers with a single app. View information about using the identity providers as follows:

  2. After you receive the required information from the IdP, create an IdP in IAM. For more information, see Create an OpenID Connect (OIDC) identity provider in IAM.

    Important

    If you are using an OIDC IdP from Google, Facebook, or Amazon Cognito, don't create a separate IAM IdP in the Amazon Web Services Management Console. These OIDC identity providers are already built into Amazon and are available for you to use. Skip this step and create new roles using your IdP in the following step.

  3. Prepare the policies for the role that the IdP-authenticated users will assume. As with any role, a role for a mobile app includes two policies. One is the trust policy that specifies who can assume the role. The other is the permissions policy that specifies the Amazon actions and resources that the mobile app is allowed or denied access to.

    For web IdPs, we recommend that you use Amazon Cognito to manage identities. In this case, use a trust policy similar to this example.

    { "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-west-2:12345678-abcd-abcd-abcd-123456 with the identity pool ID that Amazon Cognito assigns to you.

    If you manually configure an OIDC IdP, when you create the trust policy, you must use three values that ensure that only your app can assume the role:

    • For the Action element, use the sts:AssumeRoleWithWebIdentity action.

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

      • For some common OIDC IdPs, the providerUrl is a URL. The following examples include methods to specify the principal for some common IdPs:

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

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

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

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

      • For other OIDC providers, use the Amazon Resource Name (ARN) of the OIDC IdP that you created in Step 2, such as the following example:

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

    • For the Condition element, use a StringEquals condition to limit permissions. Test the identity pool ID for Amazon Cognito) or the app ID for other providers. The identity pool ID should match the app ID that you received when you configured the app with the IdP. This match between the IDs ensures that the request comes from your app.

      Note

      IAM roles for Amazon Cognito identity pools trust the service principal cognito-identity.amazonaws.com to assume the role. Roles of this type must contain at least one condition key to limit the principals who can assume the role.

      Additional considerations apply to Amazon Cognito identity pools that assume cross-account IAM roles. The trust policies of these roles must accept the cognito-identity.amazonaws.com service principal and must contain the aud condition key to restrict role assumption to users from your intended identity pools. A policy that trusts Amazon Cognito identity pools without this condition creates a risk that a user from an unintended identity pool can assume the role. For more information, see Trust policies for IAM roles in Basic (Classic) authentication in the Amazon Cognito Developer Guide.

      Create a condition element similar to one of the following examples, depending on the IdP that you are using:

      "Condition": {"StringEquals": {"cognito-identity.amazonaws.com.cn: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": "66677788899900pro0"}}

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

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

    Note

    The values for the principal in the trust policy for the role are specific to an IdP. A role for OIDC can specify only one principal. Therefore, if the mobile app allows users to sign in from more than one IdP, create a separate role for each IdP that you want to support. Create separate trust policies for each IdP.

    If a user uses a mobile app to sign in from Login with Amazon, the following example trust policy would apply. In the example, amzn1.application-oa2-123456 represents the app ID that Amazon assigns when you configured the app using Login with Amazon.

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

    If a user uses a mobile app to sign in from Facebook, the following example trust policy would apply. In this example, 111222333444555 represents the app ID that Facebook assigns.

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

    If a user uses a mobile app to sign in from Google, the following example trust policy would apply. In this example, 666777888999000 represents the app ID that Google assigns.

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

    If a user uses a mobile app to sign in from Amazon Cognito, the following example trust policy would apply. In this example, us-east:12345678-ffff-ffff-ffff-123456 represents the identity pool ID that Amazon Cognito assigns.

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

Creating a role for OIDC

After you complete the prerequisites, you can create the role in IAM. The following procedure describes how to create the role for OIDC federation in the Amazon Web Services Management Console. To create a role from the Amazon CLI or Amazon API, see the procedures at Create a role for a third-party identity provider (federation).

Important

If you use Amazon Cognito, use the Amazon Cognito console to set up the roles. Otherwise, use the IAM console to create a role for OIDC federation.

To create an IAM role for OIDC federation
  1. Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the navigation pane, choose Roles and then choose Create role.

  3. Choose Web identity as the trusted entity type and select Next.

  4. For Identity provider, choose the IdP for your role:

    • If you want to create a role for an individual web IdP, choose Login with Amazon, Facebook, or Google.

      Note

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

    • If you want to create an advanced scenario role for Amazon Cognito, choose Amazon Cognito.

      Note

      You must manually create a role to use with Amazon Cognito only when you work on an advanced scenario. Otherwise, Amazon Cognito can create roles for you. For more information about Amazon Cognito, see Identity pools (federated identities) external identity providers in the Amazon Cognito Developer Guide.

    • If you want to create a role for GitHub Actions, you must start by adding the GitHub OIDC provider to IAM. After you've added the GitHub OIDC provider to IAM, choose token.actions.githubusercontent.com.

      Note

      For information about how to configure Amazon to trust GitHub's OIDC provider as a federated identity, see GitHub Docs - Configuring OpenID Connect in Amazon Web Services. For information about best practices for limiting access for roles associated with the IAM IdP for GitHub, see Configuring a role for GitHub OIDC identity provider on this page.

    • If you want to create a role for HashiCorp Cloud Platform (HCP) Terraform, you must start by adding the Terraform OIDC provider to IAM. After you've added the Terraform OIDC provider to IAM, choose app.terraform.io.

      Important

      IAM roles for HashiCorp Cloud Platform (HCP) Terraform OIDC provider must evaluate the IAM condition key, app.terraform.io:sub, in the role trust policy. This condition key limits which HCP Terraform organizations, projects, workspaces, or run phases are able to assume the role. Without this condition key, your trust policy grants access to your role and Amazon resources by identities outside of your organization, which does not align with the principle of least privilege.

      If you set or modify a role trust policy for a role associated with the HCP Terraform OIDC provider in your Amazon account, but do not evaluate IAM condition key app.terraform.io:sub, you will receive an error. Additionally, Amazon STS will deny authorization requests if your role trust policy doesn't evaluate this condition key.

  5. Enter the identifier for your application. The label of the identifier changes based on the provider you choose:

    • If you want to create a role for Login with Amazon, enter the app ID into the Application ID box.

    • If you want to create a role for Facebook, enter the app ID into the Application ID box.

    • If you want to create a role for Google, enter the audience name into the Audience box.

    • If you want to create a role for Amazon Cognito, enter the ID of the identity pool that you have created for your Amazon Cognito applications into the Identity Pool ID box.

    • If you want to create a role for GitHub Actions, enter the following details:

      • For Audience, choose sts.amazonaws.com.

      • For GitHub organization, enter the GitHub organization name. The GitHub organization name is required and must be alphanumeric including dashes (-). You can't use wildcard characters (* and ?) in the GitHub organization name.

      • (Optional) For GitHub repository, enter the GitHub repository name. If you don’t specify a value, it defaults to a wildcard (*).

      • (Optional) For GitHub branch, enter the GitHub branch name. If you don’t specify a value, it defaults to a wildcard (*).

    • If you want to create a role for HashiCorp Cloud Platform (HCP) Terraform, enter the following details:

      • For Audience, choose aws.workload.identity.

      • For Organization, enter the organization name. You can specify a wildcard character (*) for all organizations.

      • For Project, enter the project name. You can specify a wildcard character (*) for all projects.

      • For Workspace, enter the workspace name. You can specify a wildcard character (*) for all workspaces.

      • For Run Phase, enter the run phase name. You can specify a wildcard character (*) for all run phases.

  6. (Optional) For Condition (optional), choose Add Condition to create additional conditions that must be met before users of your application can use the permissions that the role grants. For example, you can add a condition that grants access to Amazon resources only for a specific IAM user ID. You can also add conditions to the trust policy after the role is created. For more information, see Update a role trust policy .

  7. Review your OIDC information and then choose Next.

  8. IAM includes a list of the Amazon managed and customer managed policies in your account. Select the policy to use for the permissions policy, or choose Create policy to open a new browser tab and create a new policy from scratch. For more information, see Creating IAM policies. After you create the policy, close that tab and return to your original tab. Select the checkbox next to the permissions policies that you want OIDC users to have. If you prefer, you can select no policies at this time, and then attach policies to the role later. By default, a role has no permissions.

  9. (Optional) Set a permissions boundary. This is an advanced feature.

    Open the Permissions boundary section and choose Use a permissions boundary to control the maximum role permissions. Select the policy to use for the permissions boundary.

  10. Choose Next.

  11. For Role name, enter a role name. Role names must be unique within your Amazon Web Services account. They are not case dependent. For example, you can't create roles named both PRODROLE and prodrole. Because other Amazon resources might reference the role, you can't edit the name of the role after you create it.

  12. (Optional) For Description, enter a description for the new role.

  13. To edit the use cases and permissions for the role, choose Edit in the Step 1: Select trusted entities or Step 2: Add permissions sections.

  14. (Optional) To add metadata to the role, attach tags as key–value pairs. For more information about using tags in IAM, see Tags for Amazon Identity and Access Management resources.

  15. Review the role and then choose Create role.

Configuring a role for GitHub OIDC identity provider

If you use GitHub as an OpenID Connect (OIDC) identity provider (IdP), best practice is to limit the entities that can assume the role associated with the IAM IdP. When you include a condition statement in the trust policy, you can limit the role to a specific GitHub organization, repository, or branch. You can use the condition key token.actions.githubusercontent.com:sub with string condition operators to limit access. We recommend that you limit the condition to a specific set of repositories or branches within your GitHub organization. For information about how to configure Amazon to trust GitHub's OIDC as a federated identity, see GitHub Docs - Configuring OpenID Connect in Amazon Web Services.

If you use GitHub environments in action workflows or in OIDC policies, we strongly recommend adding protection rules to the environment for additional security. Use deployment branches and tags to restrict which branches and tags can deploy to the environment. For more information on configuring environments with protection rules, see Deployment branches and tags in GitHub's Using environments for deployment article.

When GitHub's OIDC IdP is the trusted Principal for your role, IAM checks the role trust policy condition to verify that the condition key token.actions.githubusercontent.com:sub is present and that its value is not solely a wildcard character (* and ?) or null. IAM performs this check when the trust policy is created or updated. If the condition key token.actions.githubusercontent.com:sub is not present, or the key value doesn't satisfy the mentioned value criteria, the request will fail and return an error.

Important

If you do not limit the condition key token.actions.githubusercontent.com:sub to a specific organization or repository, then GitHub Actions from organizations or repositories outside of your control are able to assume roles associated with the GitHub IAM IdP in your Amazon account.

The following example trust policy limits access to the defined GitHub organization, repository, and branch. The condition key token.actions.githubusercontent.com:sub value in the following example is the default subject value format documented by GitHub.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws-cn:iam::012345678910:oidc-provider/token.actions.githubusercontent.com" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com", "token.actions.githubusercontent.com:sub": "repo:GitHubOrg/GitHubRepo:ref:refs/heads/GitHubBranch" } } } ] }

The following example condition limits access to the defined GitHub organization and repository, but grants access to any branch within the repository.

"Condition": { "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" }, "StringLike": { "token.actions.githubusercontent.com:sub": "repo:GitHubOrg/GitHubRepo:*" } }

The following example condition limits access to any repository or branch within the defined GitHub organization. We recommend that you limit the condition key token.actions.githubusercontent.com:sub to a specific value that limits access to GitHub Actions from within your GitHub organization.

"Condition": { "StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" }, "StringLike": { "token.actions.githubusercontent.com:sub": "repo:GitHubOrg/*" } }

For more information about the OIDC federation keys available for condition checks in policies, see Available keys for Amazon OIDC federation.