/github-terraform-oidc-ci-cd

A sample showing how to configure GitHub OIDC connection to Azure with Terraform and then use that configuration to deploy resources with Terraform.

Primary LanguageHCLMIT LicenseMIT

page_type languages name description products urlFragment
sample
terraform
hcl
yaml
Using GitHub Actions OpenID Connect (OIDC) with Azure for Terraform Deployments
A sample showing how to configure GitHub OpenID Connect (OIDC) connection to Azure with Terraform and then use that configuration to deploy resources with Terraform.
azure
github
github-terraform-oidc-ci-cd

Using OIDC to Authenticate from GitHub Actions to Azure for Terraform Deployments

This is a two part sample. The first part demonstrates how to configure Azure and GitHub for OIDC ready for Terraform deployments. The second part demonstrates an end to end Continuous Delivery Pipeline for Terraform.

Content

File/folder Description
terraform-example-deploy Some Terraform with Azure Resources for the demo to deploy.
terraform-oidc-config The Terraform to configure Azure and GitHub ready for OIDC authenticaton.
.gitignore Define what to ignore at commit time.
CHANGELOG.md List of changes to the sample.
CONTRIBUTING.md Guidelines for contributing to the sample.
README.md This README file.
LICENSE.md The license for the sample.

Features

This sample includes the following features:

  • Option 1: Setup 3 Azure User Assigned Managed Identities with Federation ready for GitHub OIDC.
  • Option 2: Setup 3 Azure App Registrations (Service Principals) with Federation ready for GitHub OIDC.
  • Setup an Azure Storage Account for State file management.
  • Setup GitHub repository and environments ready to deploy Terraform with OIDC.
  • Run a Continuous Delivery pipeline for Terraform using OIDC auth for state and deploying resources to Azure.
  • Run a Pull Request workflow with some basic static analysis.

Service Principal or Managed Identity

There are two approaches shown in the code for federating GitHub and Azure. The preferred method is to use a User Assigned Managed Identity since this does not require elevated permissions in Azure Active Directory and has a longer token timeout. However the code also shows the Service Principal approach for those that prefer that method. If you choose the Service Principal approach then the account creating the infrastructure will need permission to create Applications in Azure Active Directory.

Getting Started

Prerequisites

Installation

  • Clone the repository locally and then follow the Demo / Lab.

Quickstart

The instructions for this sample are in the form of a Lab. Follow along with them to get up and running.

Demo / Lab

Generate a PAT (Personal Access Token) in GitHub

  1. Navigate to github.com.
  2. Login and select the account icon in the top right and then Settings.
  3. Click Developer settings.
  4. Click Personal access tokens and select Tokens (classic).
  5. Click Generate new token and select the classic option.
  6. Type Demo_OIDC into the Note field.
  7. Check these scopes:
    1. repo
    2. delete_repo
  8. Click Generate token

  9. IMPORTANT: Copy the token and save it somewhere.

Clone the repo and setup your variables

  1. Clone this repository to your local machine.
  2. Open the repo in Visual Studio Code. (Hint: In a terminal you can open Visual Studio Code by navigating to the folder and running code .).
  3. Navigate to the terraform-oidc-config folder and create a new file called terraform.tfvars.
  4. In the config file add the following:
prefix = "<your_initials>-<date_as_YYYYMMDD>"
github_organisation_target = "<your_github_organisation_name>"

e.g.

prefix = "JFH-20221208"
github_organisation_target = "my-organization"

NOTE if you wish to use the Azure Active Directory Service Principal approach rather than a User Assigned Managed Identity, then also add this setting to terraform.tfvars:

use_managed_identity = false

Apply the Terraform

  1. Open the Visual Studio Code Terminal and navigate the terraform-oidc-config folder.
  2. Run az login and follow the prompts to login to Azure with your Global Administrator account.
  3. Run terraform apply.
  4. You'll be prompted for the variable var.github_token. Paste in the PAT you generated earlier and hit enter.
  5. The plan will complete. Review the plan and see what is going to be created.
  6. Type yes and hit enter once you have reviewed the plan.
  7. Wait for the apply to complete.

NOTE: If you are a Microsoft employee you may get a 403 error here due to the way GitHub accesses the template. If so, you need to grant your PAT SSO access to any Microsoft organisation you are a member of (e.g. Azure, Microsoft, Azure-Samples, etc). This does not affect non-Microsoft users.

Check what has been created

Managed Identity or Service Principal

When deploying the example you will have selected to use the default Managed Identity approach or the Service Principal approach choose the relevant option below.

Option 1: Managed Identity
  1. Login to the Azure Portal with your Global Administrator account.
  2. Navigate to your Subscription and select Resource groups.
  3. Click the resource group post-fixed identity (e.g. JFH-20221208-dev).
  4. Look for a Managed Identity resource post-fixed with dev and click it.
  5. Click on Federated Credentials.
  6. There should only be one credential in the list, select that and take a look at the configuration.
  7. Examine the Subject identifier and ensure you understand how it is built up.
Option 2: Service Principal
  1. Login to the Azure Portal with your Global Administrator account.
  2. Navigate to Azure Active Directory and select App registrations.
  3. Select All applications, then find the one you just created post-fixed with dev (e.g. JFH-20221208-dev).
  4. Select Certificate & secrets, then Federated credentials.
  5. There should only be one credential in the list, select that and take a look at the configuration.
  6. Examine the Subject identifier and ensure you understand how it is built up.

Resource Group and permissions

  1. Navigate to your Subscription and select Resource groups.
  2. You should see four newly created resource groups.
  3. Click the resource group post-fixed dev (e.g. JFH-20221208-dev).
  4. Select Access control (IAM) and select Role assignments.
  5. Under the Contributor role, you should see that your dev Service Principal has been granted access directly to the resource group.

State storage account

  1. Navigate to your Subscription and select Resource groups.
  2. Click the resource group post-fixed state (e.g. JFH-20221208-dev).
  3. You should see a single storage account in there, click on it.
  4. Select Containers. You should see a dev, test and prod container.
  5. Select the dev container.
  6. Click Access Control (IAM) and select Role assignments.
  7. Scroll down to Storage Blob Data Contributor. You should see your dev Service Principal has been assigned that role.

GitHub environments

  1. Open github.com (login if you need to).
  2. Navigate to your organisation and select Repositories.
  3. You should see a newly created repository in there (e.g. JFH-20221208-wild-dog). Click on it.
  4. You should see some files under source control.
  5. Navigate to Settings, then select Environments.
  6. You should see 3 environments called dev, test and prod.
  7. Click on the dev environment.
  8. You should see that the environment has 7 Environment secrets. These secrets are all used in the Action for deploying Terraform.

GitHub Action

  1. Navigate to Code.
  2. Select .github, workflows and open the main.yml file.
  3. Examine the file and ensure you understand all the steps in there.

Run the Action

  1. Select Actions, then click on the Run Terraform with OpenID Connect action in the left menu.
  2. Click the Run workflow drop-down and hit the Run workflow button.
  3. Wait for the run to appear or refresh the screen, then click on the run to see the details.
  4. You will see each environment being deployed one after the other. In a real world scenarios you may want to have a manual intervention on the environment for an approval to promote to the next stage.
  5. You will also note that the Analyse the Terraform step was skipped.
  6. Drill into the log for one of the environments and look at the Terraform Apply step. You should see the output of the plan and apply.
  7. Run the workflow again and take a look at the log to compare what happens on the Day 2 run.

Submit a PR

  1. Clone your new repository and open it in Visual Studio Code.
  2. Create a new branch, call it whatever you want.
  3. Open the terraform-example-deploy/virtual-machine.tf file.
  4. Rename the virtual machine to example-machine-pr.
  5. Commit and push the change.
  6. Raise a pull request.
  7. You'll see the GitHub Action running in the pull request.
  8. The Terraform Fmt step will fail for main.tf. Fix it, commit and push your change.
  9. Wait for the Action to run again.
  10. Look for the Pull Request comment that was added for the plan. Expand the Show Plan section and review.
  11. Merge the Pull Request.
  12. Navigate to Actions and watch the run.

Resources