OIDC Setup

What is OIDC?

OpenID Connect (OIDC) allows your GitHub Actions workflows to access Azure resources without storing any credentials as long-lived GitHub secrets. Azure natively supports OIDC through Entra ID federated credentials. This is the most secure authentication method for production environments.

Prerequisites

Before you begin, ensure you have the following:

• Azure CLI
• An Azure subscription with permissions to create App Registrations and assign RBAC roles

Setup

1. Login to Azure CLI

   az login

2. Get your Subscription ID and Tenant ID

   az account show --query '{subscriptionId:id, tenantId:tenantId}' -o json

   Example output:

   {
     "subscriptionId": "00000000-0000-0000-0000-000000000000",
     "tenantId": "00000000-0000-0000-0000-000000000000"
   }

3. Export environment variables

   export SUBSCRIPTION_ID="<subscription-id>"
   export TENANT_ID="<tenant-id>"
   export GITHUB_ORG="<github-org-or-username>"
   export REPO_NAME="<repository-name>"

4. Create an App Registration

   az ad app create --display-name "terrateam"

   Note the appId from the output:

   {
     "appId": "00000000-0000-0000-0000-000000000000",
     ...
   }

   export CLIENT_ID="<appId>"

5. Create a Service Principal

   az ad sp create --id "$CLIENT_ID"

6. Add a Federated Credential

   Get the App Registration’s object ID (different from the client/app ID):

   APP_OBJECT_ID=$(az ad app show --id "$CLIENT_ID" --query "id" -o tsv)

   Create a flexible federated credential using the Microsoft Graph beta API. This uses claimsMatchingExpression with the matches operator and * wildcard to allow authentication from any branch, tag, or pull request in your repository:

   az rest --method POST \
     --uri "https://graph.microsoft.com/beta/applications/${APP_OBJECT_ID}/federatedIdentityCredentials" \
     --headers "Content-Type=application/json" \
     --body "{'name': 'terrateam-github', 'issuer': 'https://token.actions.githubusercontent.com', 'audiences': ['api://AzureADTokenExchange'], 'description': 'Terrateam GitHub Actions OIDC', 'claimsMatchingExpression': {'value': 'claims[\'sub\'] matches \'repo:${GITHUB_ORG}/${REPO_NAME}:*\'', 'languageVersion': 1}}"

   Note

   Replace GITHUB_ORG and REPO_NAME with your GitHub organization (or username) and repository name. These are case-sensitive.

   Verify the credential was created:

   az rest --method GET \
     --uri "https://graph.microsoft.com/beta/applications/${APP_OBJECT_ID}/federatedIdentityCredentials" \
     --query "value[].{name:name, expression:claimsMatchingExpression.value}" -o table

   Why claimsMatchingExpression?

   Terrateam runs on branches and pull requests, so the federated credential must match any ref in your repository. Azure’s standard subject field requires an exact match and does not support wildcards. The claimsMatchingExpression property with the matches operator supports * (multi-character) and ? (single-character) wildcards against the sub claim. This is a preview feature called Flexible Federated Identity Credentials.

   The expression claims['sub'] matches 'repo:org/repo:*' matches any subject starting with your repository, including all branches, tags, and pull requests.

   Other useful patterns:

   • claims['sub'] matches 'repo:org/repo:ref:refs/heads/*' - any branch only
   • claims['sub'] matches 'repo:org/repo:ref:refs/tags/*' - any tag only
   • claims['sub'] eq 'repo:org/repo:ref:refs/heads/main' - specific branch only

7. Assign RBAC Role

   Grant the service principal permissions on your subscription:

   az role assignment create \
     --assignee "$CLIENT_ID" \
     --role "Contributor" \
     --scope "/subscriptions/$SUBSCRIPTION_ID"

   Note

   Contributor is an Azure built-in role. This role grants full access to manage all resources, but does not allow you to assign roles in Azure RBAC. Choose whichever role makes the most sense for your organization.

Configure Terrateam for OIDC

After setting up Azure resources, configure Terrateam to use OIDC authentication:

1. Create Configuration File

   Create the .terrateam/config.yml configuration file at the root of your Terraform repository.

2. Add OIDC Hook

   Note

   Replace CLIENT_ID, TENANT_ID, and SUBSCRIPTION_ID with your actual values.

   hooks:
     all:
       pre:
         - type: oidc
           provider: azure
           client_id: "CLIENT_ID"
           tenant_id: "TENANT_ID"
           subscription_id: "SUBSCRIPTION_ID"

Testing Your Setup

Test that OIDC authentication is working:

1. Create a simple Terraform configuration in your repository
2. Open a pull request with the changes
3. Comment terrateam plan on the pull request
4. Terrateam should successfully authenticate using OIDC and show the plan output

How It Works

Azure OIDC with Terrateam works by:

1. Terrateam requests a GitHub OIDC token with audience api://AzureADTokenExchange
2. The token is passed directly to the Terraform AzureRM/AzAPI providers via environment variables
3. The providers exchange the token with Entra ID for Azure credentials

The following environment variables are automatically set:

Variable	Value
ARM_USE_OIDC	true
ARM_CLIENT_ID	Your App Registration client ID
ARM_TENANT_ID	Your Entra ID tenant ID
ARM_OIDC_TOKEN	The GitHub OIDC token
ARM_SUBSCRIPTION_ID	Your Azure subscription ID (if configured)

Advanced Configuration

Multiple Environments

You can use different App Registrations for different environments and operations. For example:

workflows:
  - tag_query: "dir:terraform/production/**"
    plan:
      - type: oidc
        provider: azure
        client_id: "PROD_CLIENT_ID"
        tenant_id: "TENANT_ID"
        subscription_id: "PROD_SUBSCRIPTION_ID"
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: azure
        client_id: "PROD_CLIENT_ID"
        tenant_id: "TENANT_ID"
        subscription_id: "PROD_SUBSCRIPTION_ID"
      - type: init
      - type: apply
  - tag_query: "dir:terraform/staging/**"
    plan:
      - type: oidc
        provider: azure
        client_id: "STAGING_CLIENT_ID"
        tenant_id: "TENANT_ID"
        subscription_id: "STAGING_SUBSCRIPTION_ID"
      - type: init
      - type: plan
    apply:
      - type: oidc
        provider: azure
        client_id: "STAGING_CLIENT_ID"
        tenant_id: "TENANT_ID"
        subscription_id: "STAGING_SUBSCRIPTION_ID"
      - type: init
      - type: apply

For more details, read the Cloud Credentials documentation.

Next Steps

Now that you have Azure authentication configured, you are now able to use Terrateam for plan and apply operations against Azure resources.

• Learn about advanced workflows for complex setups
• Configure multiple environments
• Set up apply requirements for additional security