# IAM role for GitHub OIDC

## Configuring OpenID Connect in Amazon Web Services <a href="#title-h1" id="title-h1"></a>

OpenID Connect（OIDC）是基于OAuth 2.0协议之上的一个简单身份层，它允许计算客户端基于授权服务器执行的认证来验证终端用户的身份，以及以一种可互操作和类REST的方式获取关于终端用户的基本配置文件信息。将Github与亚马逊网络服务（AWS）集成，进行认证，可以提高应用程序的安全性和效率。

We recommend using [GitHub's OIDC provider](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) to get short-lived AWS credentials needed for your actions. When using OIDC, you configure IAM to accept JWTs from GitHub's OIDC endpoint. This action will then create a JWT unique to the workflow run using the OIDC endpoint, and it will use the JWT to assume the specified role with short-term credentials.

#### 前提条件

* 有一个AWS account。
* 打开 AWS 管理控制台
* 有一个 GitHub 账户作为OIDC提供商。

**步骤1：在您的账户中创建OIDC提供程序**

* 打开IAM控制台。
* 在左侧导航菜单中，选择“Identity providers”。
* 在“Identity providers”窗格中，选择“Add provider”。
* 选择“Provider type”为OpenID Connect。
* 对于“Provider URL”，输入GitHub OIDC IdP的URL：<https://token.actions.githubusercontent.com。>
* 对于“Audience”，输入sts.amazonaws.com。
* 验证输入的信息，并选择“Add provider”。

#### Step 1: Registering Your Application with GitHub

Before AWS can delegate authentication to GitHub as your OIDC IdP, you must register your application with GitHub. This involves creating a new OAuth application in GitHub settings and obtaining the Client ID and Client Secret.

1. Navigate to GitHub and sign into your account.
2. Go to Settings > Developer settings > OAuth Apps.
3. Click on the "New OAuth App" button.
4. Fill in the application details:

   * **Application name**: Provide a name that identifies your application.
   * **Homepage URL**: This is the URL where users can learn more about your app. For testing purposes, you can use your AWS application URL.
   * **Application description** (optional): Provide a short description of your application.
   * **Authorization callback URL**: This is the URL that users are redirected to after they have authenticated with GitHub. AWS provides a specific callback URL format, which can be found in the IAM console when setting up the identity provider.

   After registering, you will receive a Client ID and Client Secret. Keep these credentials secure as they will be used to configure AWS to trust GitHub as an OpenID Connect provider.

   #### Step 2: Creating the OIDC Identity Provider in AWS

   To use GitHub for authentication in AWS, you must create an OIDC identity provider in IAM (Identity and Access Management).

   1. Log into the AWS Management Console and navigate to the IAM dashboard.
   2. In the navigation pane, select "Identity Providers," then choose "Create Provider."
   3. For **Provider Type**, select "OIDC."
   4. Enter the **Provider URL**. For GitHub, this is `https://github.com/login/oauth/authorize`.
   5. In the **Audience** field, enter the Client ID you obtained from GitHub.
   6. Follow the prompts to create the provider.

   #### Step 3: Creating IAM Roles for OIDC

   With the OIDC provider configured, the next step is to create an IAM role that specifies who can assume the role based on the identity provider's authentication.

   1. In the IAM dashboard, navigate to "Roles" and click "Create Role."
   2. Select "Web identity" as the role type and select the OIDC provider you created earlier.
   3. Choose a policy that best fits the permissions needed by your application.
   4. Set a role name, description, and create the role.

   #### Conclusion

   Integrating OpenID Connect with AWS allows you to use GitHub as an authentication provider, streamlining the login process for your users and enhancing security by relying on GitHub's robust authentication mechanisms. By following these steps, you should now have a basic setup that uses GitHub for authenticating users in your AWS application.

   For detailed information and troubleshooting, refer to the official AWS documentation and GitHub's guide on configuring OpenID Connect in Amazon Web Services.

## 参考资料

AWS - <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html#idp_oidc_Create_GitHub>

AWS - <https://github.com/aws-actions/configure-aws-credentials>

Github - [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)
