fbpx

Posted on by admin

Associate GitHub Actions to AWS activities using IAM roles

Have you ever wanted to initiate change in an Amazon Web Services (AWS) account after you update a GitHub repository, or deploy updates in an AWS application after you merge a commit, without the use of AWS Identity and Access Management (IAM) user access keys? If you configure an OpenID Connect (OIDC) identity provider (IdP) inside an AWS account, you can use IAM roles and short-term credentials, which removes the need for IAM user access keys.

 <p>In this blog post, we will walk you through the steps needed to configure a specific GitHub repo to assume an individual role in an AWS account to preform changes. You will learn how to create an OIDC-trusted connection that is scoped to an individual GitHub repository, and how to map the repository to an IAM role in your account. You will create the OIDC connection, IAM role, and trust relationship two ways: with the <a href="https://aws.amazon.com/console/" target="_blank" rel="noopener">AWS Management Console</a> and with the <a href="https://aws.amazon.com/cli/" target="_blank" rel="noopener">AWS Command Line Interface (AWS CLI)</a>.</p> <p>This post focuses on <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html" target="_blank" rel="noopener">creating an IAM OIDC identity provider</a> for GitHub and demonstrates how to authorize access into an AWS account from a specific branch and repository. You can use OIDC IdPs for workflows that support the <a href="http://openid.net/connect/" target="_blank" rel="noopener">OpenID Connect</a> standard, such as Google or Salesforce.</p> <h2>Prerequisites</h2> <p>To follow along with this blog post, you should have the following prerequisites in place:</p> <h2>Solution overview</h2> <p>GitHub is an external provider that is independent from AWS. To use GitHub as an OIDC IdP, you will need to complete four steps to access AWS resources from your GitHub repository. Then, for the fifth and final step, you will use <a href="https://aws.amazon.com/cloudtrail/" target="_blank" rel="noopener">AWS CloudTrail</a> to audit the role that you created and used in steps 1–4.</p> <ol> <li>Create an OIDC provider in your AWS account. This is a trust relationship that allows GitHub to authenticate and be authorized to perform actions in your account.</li> <li>Create an <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html" target="_blank" rel="noopener">IAM role</a> in your account. You will then scope the IAM role’s trust relationship to the intended parts of your GitHub organization, repository, and branch for GitHub to assume and perform specific actions.</li> <li>Assign a minimum level of permissions to the role.</li> <li>Create a GitHub Actions workflow file in your repository that can invoke actions in your account.</li> <li>Audit the role’s use with Amazon CloudTrail logs.</li> </ol> <h2>Step 1: Create an OIDC provider in your account</h2> <p>The first step in this process is to create an OIDC provider which you will use in the trust policy for the IAM role used in this action.</p> <h3>To create an OIDC provider for GitHub (console):</h3> <ol> <li>Open the <a href="https://console.aws.amazon.com/iam/" target="_blank" rel="noopener">IAM console</a>.</li> <li>In the left navigation menu, choose <strong>Identity providers</strong>.</li> <li>In the <strong>Identity providers</strong> pane, choose <strong>Add provider</strong>.</li> <li>For <strong>Provider type</strong>, choose <strong>OpenID Connect</strong>.</li> <li>For <strong>Provider URL</strong>, enter the URL of the GitHub OIDC IdP for this solution: <span>https://token.actions.GitHubusercontent.com.</span></li> <li>Choose <strong>Get thumbprint</strong> to verify the server certificate of your IdP. To learn more about OIDC thumbprints, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_verify-thumbprint.html" target="_blank" rel="noopener">Obtaining the thumbprint for an OpenID Connect Identity Provider</a>.</li> <li>For <strong>Audience</strong>, enter <span>sts.amazonaws.com</span>. This will allow the <a href="https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html" target="_blank" rel="noopener">AWS Security Token Service (AWS STS) API</a> to be called by this IdP.</li> <li>(Optional) For <strong>Add tags</strong>, you can add key–value pairs to help you identify and organize your IdPs. To learn more about tagging IAM OIDC IdPs, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags_idps_oidc.html" target="_blank" rel="noopener">Tagging OpenID Connect (OIDC) IdPs</a>.</li> <li>Verify the information that you entered. Your console should match the screenshot in Figure 1. After verification, choose <strong>Add provider</strong>.<br><blockquote> <p><strong>Note:</strong> Each provider is a one-to-one relationship to an external IdP. If you want to add more IdPs to your account, you can repeat this process.</p> </blockquote> <div id="attachment_29114" class="wp-caption aligncenter"> <img aria-describedby="caption-attachment-29114" src="https://www.infracom.com.sg/wp-content/uploads/2023/04/img1-2-1024x580-1.png" alt="Figure 1: Steps to configure the identity provider" width="720" class="size-large wp-image-29114"> <p id="caption-attachment-29114" class="wp-caption-text">Figure 1: Steps to configure the identity provider</p> </div> </li> <li>Once you are taken back to the <strong>Identity providers</strong> page, you will see your new IdP as shown in Figure 2. Select your provider to view its properties, and make note of the Amazon Resource Name (ARN). You will use the ARN later in this post. The ARN will look similar to the following: <p>arn:aws:iam::111122223333:oidc-provider/token.actions.GitHubusercontent.com</p> <div id="attachment_29115" class="wp-caption aligncenter"> <img aria-describedby="caption-attachment-29115" src="https://www.infracom.com.sg/wp-content/uploads/2023/04/img2-2-1024x320-1.png" alt="Figure 2: View your identity provider" width="720"> <p id="caption-attachment-29115" class="wp-caption-text">Figure 2: View your identity provider</p> </div> </li> </ol> <h3>To create an OIDC provider for GitHub (AWS CLI):</h3> <p>You can add GitHub as an IdP in your account with a single AWS CLI command. The following code will perform the previous steps outlined for the console, with the same results. For the value <span>—thumbprint-list</span>, you will use the GitHub OIDC thumbprint <span>938fd4d98bab03faadb97b34396831e3780aea1</span>.</p> <div class="hide-language"> <pre><code class="lang-text">aws iam create-open-id-connect-provider --url

“https://token.actions.GitHubusercontent.com” –thumbprint-list “6938fd4d98bab03faadb97b34396831e3780aea1” –client-id-list ‘sts.amazonaws.com’

 To learn more about the GitHub thumbprint, see <a href="https://github.blog/changelog/2022-01-13-github-actions-update-on-oidc-based-deployments-to-aws/" target="_blank" rel="noopener">GitHub Actions – Update on OIDC based deployments to AWS</a>. At the time of publication, this thumbprint is correct.</p> <p>Both of the preceding methods will add an IdP in your account. You can view the provider on the <strong>Identity providers</strong> page in the IAM console.</p> <h2>Step 2: Create an IAM role and scope the trust policy</h2> <p>You can create an IAM role with either the IAM console or the AWS CLI. If you choose to create the IAM role with the AWS CLI, you will scope the Trust Relationship Policy before you create the role.</p> <p>The procedure to create the IAM role and to scope the trust policy come from the <a href="https://docs.aws.amazon.com/iam/index.html" target="_blank" rel="noopener">AWS Identity and Access Management User Guide</a>. For detailed instructions on how to configure a role, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html#idp_oidc_Create_GitHub" target="_blank" rel="noopener">How to Configure a Role for GitHub OIDC Identity Provider</a>.</p> <h3>To create the IAM role (IAM console):</h3> <ol> <li>In the IAM console, on the <strong>Identity providers</strong> screen, choose the <strong>Assign role</strong> button for the newly created IdP. <div id="attachment_29121" class="wp-caption aligncenter"> <img aria-describedby="caption-attachment-29121" src="https://www.infracom.com.sg/wp-content/uploads/2023/04/img3-2-1024x322-1.png" alt="Figure 3: Assign a role to the identity provider" width="720" class="size-large wp-image-29121" /> <p id="caption-attachment-29121" class="wp-caption-text">Figure 3: Assign a role to the identity provider</p> </div> </li> <li>In the <strong>Assign role for</strong> box, choose <strong>Create a new role</strong>, and then choose <strong>Next</strong>, as shown in the following figure. <div id="attachment_29122" class="wp-caption aligncenter"> <img aria-describedby="caption-attachment-29122" src="https://www.infracom.com.sg/wp-content/uploads/2023/04/img4-2.png" alt="Figure 4: Create a role from the Identity provider page" width="720" class="size-full wp-image-29122" /> <p id="caption-attachment-29122" class="wp-caption-text">Figure 4: Create a role from the Identity provider page</p> </div> </li> <li>The <strong>Create role</strong> page presents you with a few options. <strong>Web identity</strong> is already selected as the trusted entity, and the <strong>Identity provider</strong> field is populated with your IdP. In the <strong>Audience</strong> list, select <strong>sts.amazonaws.com</strong>, and then choose <strong>Next</strong>.</li> <li>On the <strong>Permissions</strong> page, choose <strong>Next</strong>. For this demo, you won’t add permissions to the role. <p>If you’d like to test other actions, like <a href="https://aws.amazon.com/codebuild/" target="_blank" rel="noopener">AWS CodeBuild</a> operations, you can add permissions as outlined by these blog posts: <a href="https://aws.amazon.com/blogs/devops/complete-ci-cd-with-aws-codecommit-aws-codebuild-aws-codedeploy-and-aws-codepipeline/" target="_blank" rel="noopener">Complete CI/CD with AWS CodeCommit, AWS CodeBuild, AWS CodeDeploy, and AWS CodePipeline</a> or <a href="https://aws.amazon.com/blogs/security/techniques-for-writing-least-privilege-iam-policies/" target="_blank" rel="noopener">Techniques for writing least privilege IAM policies</a>.</p> </li> <li>(Optional) On the <strong>Tags</strong> page, add tags to this new role, and then choose <strong>Next: Review</strong>.</li> <li>On the <strong>Create role</strong> page, add a role name. For this demo, enter <span>GitHubAction-AssumeRoleWithAction</span>. Optionally add a description.</li> <li>To create the role, choose <strong>Create role</strong>.</li> </ol> <p>Next, you’ll scope the IAM role’s trust policy to a single GitHub organization, repository, and branch.</p> <h3>To scope the trust policy (IAM console)</h3> <ol> <li>In the IAM console, open the newly created role and choose <strong>Edit trust relationship</strong>.</li> <li>On the <strong>Edit trust policy</strong> page, modify the trust policy to allow your unique GitHub organization, repository, and branch to assume the role. This example trusts the GitHub organization <span></span>, the repository named <span></span>, and the branch named <span></span>. Update the Federated ARN with the GitHub IdP ARN that you copied previously. <div class="hide-language"> <pre><code class="lang-text">{"Version": "2012-10-17","Statement": [ { "Effect": "Allow", "Principal": { "Federated": "<span></span>" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "token.actions.githubusercontent.com:sub": "repo: <span></span>:ref:refs/heads/<span></span>", "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" } } }]

}

To establish a position ( AWS CLI )

Use the examples accept policy for the console shown above in the AWS CLI. This plan is intended to restrict access to a specific GitHub unit, repository, and organization.

  1. Design and save a JSON register with the lesson plan, trustpolicyforGitHubOIDC, to your local computer. json.
  2. Run the command below to start the part. 
    aws iam create-role --role-name GitHubAction-AssumeRoleWithAction --assume-role-policy-document file://C:policiestrustpolicyforGitHubOIDC.json

See Creating a Role for Federated Access( AWS CLI ) for more information on how to set up an OIDC role with the AWS SLI.

Step 3: Grant the position a required level of rights.

To show a GitHub behavior that takes on the AWS role, you will face STS GetCallerIdentity instead of adding permissions to the IAM role in this example.

You can add permissions to the role you created, GitHubAction – AssumeRoleWithAccusation, to see if you’re’re interested in carrying out additional actions in your account. Calling AWS Lambda functions and moving files to an Amazon Simple Storage Service ( Amazon S3 ) bucket are two typical workflow actions. Visit Policies and Permissions in IAM for more details on how to use it to apply for rights.

You can add permissions if you’d’d like to conduct a test by following the instructions in these blog posts: Complete CI / CD with AWS CodeCommit, AW CodeBuild, WCS CodeDeploy, and WSC CodePipeline or Techniques for Writing Less Privilege IAM Policies.

Establish a GitHub actions in part four to launch the AWS CLI.

GitHub actions are defined as methods that you can use to automate, customize, and run your software development workflows in GitHub. The GitHub action that you create will authenticate into your account as the role that was created in Step 2: Create the IAM role and scope the trust policy.

To launch the AWS CLI, produce a GitHub actions:

  1. Make a simple workflow file, like key. yml, in your repository’s.github / workflows directory. In order to perform the action aws sts have – caller identity, this sample workflow may assume the GitHubAction-AsumeRoleWithActive role. Various workflows, each carrying out a different set of tasks, are possible in your collection. You can use AWS CLI codes in your account once GitHub has authenticated the part with the process.
  2. The procedure example below should be pasted into a file. 
    # This is a basic workflow to help you get started with Actionsname:Connect to an AWS role from a GitHub repository

Controls when the action will run. Invokes the workflow on push events but only for the main branch

on: push: branches: [ main ] pull_request: branches: [ main ]env:AWS_REGION : #Change to reflect your Region

Permission can be added at job level or workflow level

permissions: id-token: write # This is required for requesting the JWT contents: read # This is required for actions/checkoutjobs: AssumeRoleAndCallIdentity: runs-on: ubuntu-latest steps: – name: Git clone the repository uses: actions/checkout@v3 – name: configure aws credentials uses: aws-actions/configure-aws-credentials@v1.7.0 with: role-to-assume: #change to reflect your IAM role’s ARN role-session-name: GitHub_to_AWS_via_FederatedOIDC aws-region: ${{ env.AWS_REGION }} # Hello from AWS: WhoAmI – name: Sts GetCallerIdentity run: | aws sts get-caller-identity

  • Change the procedure to reveal the details of your AWS account:
    • AWS_REGION: Enter the AWS Region for your AWS resources.
    • role-to-assume: Replace the ARN with the ARN of the AWS GitHubAction role that you created previously.

 

The steps that you just created will be invoked in the example process if there is a push or pull on the” important” branch of the repository.

Check 5 depicts the process procedures that GitHub uses to perform the following:

  • Using the OIDC IdP in the Region that was specified on the process document in part setup aws credentials, the IAM factor is authenticated.
  • calling aws sts get visitor – identity in the AWS step Hello. Go AWS CLI sts GetCallerIdentity to find out who I am.

    Results of the GitHub actions are shown in Check 5.

    Results of the GitHub actions are shown in Check 5.

Step 5: Perform a factor usage audit by querying CloudTrail logs.

To inspect the use of this role, the last stage is to see the AWS CloudTrail logs in your accounts.

Observe the affair files for the GitHub action by going here:

  1. Available CloudTrail in the AWS Management Console, then select Event History.
  2. Select Event resource from the Lookup capabilities list.
  3. Enter loc in the search table. amazonaws.com

    See party history in CloudTrail in Determine 6.

    See party history in CloudTrail in Determine 6.

  4. AssumeRoleWithWebIdentity occasions, as depicted in Figure 6, should be seen. The Hello from AWS ceremony is called GetCallerIdentity. enter the GitHub procedure section. This instance demonstrates the process as it calls the get-caller-identity amazon sts. The AssumeRoleWithWebIdentity event depicts GitHub assuming and authenticating your IAM role( GitHubAction ).

Additionally, you can watch one occasion at a time.

Enjoy the GetCallerIdentity event on AWS CLI:

  1. Select User name from the Lookup capabilities number.
  2. Enter the responsibility, time, and identify defined in the process file in your repository into the search bar. Since the role-session-name is defined in column 30 of the process example, this is not the IAM part title. The role-session name in the workflow example for this blog post is GitHub_ to_ AWS_ via _ FederatedOIDC.
  3. The first occasion in the CloudTrail history can now be seen.

    See the have guest identity in CloudTrail in Figure 7.

    See the have guest identity in CloudTrail in Figure 7.

To enjoy the party AssumeRoleWithWebIdentity

  1. Select User name from the Lookup capabilities number.
  2. Input the GitHub business, store, and branch that the IAM role’s’s faith policy specifies in the search bar. The user name in the previously described example is repo: aws – samples / EXAMPLE: ref: refers, heads, or main.
  3. The specific occasion in the CloudTrail evolution is immediately visible.

    See the CloudTrail suppose role call in Figure 8.

    See the CloudTrail suppose role call in Figure 8.

Conclusion

You have a reliable way to give access to your AWS resources when you use IAM functions with OIDC self providers. Temporary security credentials can be created by GitHub and some OIDC companies to update your accounts’ infrastructure and resources.

You learned how to use process steps files in a GitHub collection to instantly take on an AWS part in this post using federated access. You can start removing AWS get keys from your IAM customers and using short-term credentials once this new IdP is in place.

Following the reading of this article, we advise you to use temporary and limited-privilege program access to AWS services in accordance with the IAM order, which is referred to as the” AWS Well Architected Security Pillar.” This guide must be followed in order to issue currencies by the AWS Security Token Service if IAM federated functions are deployed in place of AW user access keys. Please post here if you have any feedback on this article and let us understand how you would like to see OIDC workflows improved to meet your IAM requirements.

Please leave feedback in the Comments section here if you have any comment on this article. Contact AWS Support if you have any doubts about this article.

Need to learn more about AWS Security? Become our Twitter follower.

 <!-- '"` -->