Configure OpenID Connect in Azure to retrieve temporary credentials

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

WARNING: CI_JOB_JWT_V2 was deprecated in GitLab 15.9 and is scheduled to be removed in GitLab 17.0. Use ID tokens instead.

This tutorial demonstrates how to use a JSON web token (JWT) in a GitLab CI/CD job to retrieve temporary credentials from Azure without needing to store secrets.

To get started, configure OpenID Connect (OIDC) for identity federation between GitLab and Azure. For more information on using OIDC with GitLab, read Connect to cloud services.

Azure does not support wildcard matching for subjects of a conditional role. A separate credential configuration must be created for each branch that needs to access Azure.

Prerequisites:

Access to an existing Azure Subscription with Owner access level.
Access to the corresponding Azure Active Directory Tenant with at least the Application Developer access level.
A local installation of the Azure CLI. Alternatively, you can follow all the steps below with the Azure Cloud Shell.
Your GitLab instance must be publicly accessible over the internet as Azure must to connect to the GitLab OIDC endpoint.
A GitLab project.

To complete this tutorial:

Create Azure AD application and service principal.
Create Azure AD federated identity credentials.
Grant permissions for the service principal.
Retrieve a temporary credential.

For more information about Azure identity federation, see workload identity federation.

Create Azure AD application and service principal

To create an Azure AD application and service principal:

In the Azure CLI, create the AD application:
```
appId=$(az ad app create --display-name gitlab-oidc --query appId -otsv)
```
Save the appId (Application client ID) output, as you need it later to configure your GitLab CI/CD pipeline.

Create a corresponding Service Principal:

az ad sp create --id $appId --query appId -otsv

Instead of the Azure CLI, you can use the Azure Portal to create these resources.

Create Azure AD federated identity credentials

To create the federated identity credentials for the above Azure AD application:

objectId=$(az ad app show --id $appId --query id -otsv)

cat <<EOF > body.json
{
  "name": "gitlab-federated-identity",
  "issuer": "https://gitlab.example.com",
  "subject": "project_path:<mygroup>/<myproject>:ref_type:branch:ref:<branch>",
  "description": "GitLab service account federated identity",
  "audiences": [
    "https://gitlab.example.com"
  ]
}
EOF

az rest --method POST --uri "https://graph.microsoft.com/beta/applications/$objectId/federatedIdentityCredentials" --body @body.json

For issues related to the values of issuer, subject or audiences, see the troubleshooting details.

Optionally, you can now verify the Azure AD application and the Azure AD federated identity credentials from the Azure Portal:

Open the Azure Active Directory App Registration view and select the appropriate app registration by searching for the display name gitlab-oidc.
On the overview page you can verify details like the Application (client) ID, Object ID, and Tenant ID.
Under Certificates & secrets, go to Federated credentials to review your Azure AD federated identity credentials.

Grant permissions for the service principal

After you create the credentials, use role assignment to grant permissions to the above service principal to access to Azure resources:

az role assignment create --assignee $appId --role Reader --scope /subscriptions/<subscription-id>

You can find your subscription ID in:

The Azure Portal.
The Azure CLI.

The command above grants read-only permissions to the entire subscription. For more information on applying the principle of least privilege in the context of your organization, read Best practices for Azure AD roles.

Retrieve a temporary credential

After you configure the Azure AD application and federated identity credentials, the CI/CD job can retrieve a temporary credential by using the Azure CLI:

default:
  image: mcr.microsoft.com/azure-cli:latest

variables:
  AZURE_CLIENT_ID: "<client-id>"
  AZURE_TENANT_ID: "<tenant-id>"

auth:
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.com
  script:
    - az login --service-principal -u $AZURE_CLIENT_ID -t $AZURE_TENANT_ID --federated-token $GITLAB_OIDC_TOKEN
    - az account show

The CI/CD variables are:

AZURE_CLIENT_ID: The application client ID you saved earlier.
AZURE_TENANT_ID: Your Azure Active Directory. You can find it by using the Azure CLI or Azure Portal.
GITLAB_OIDC_TOKEN: An OIDC ID token.

Troubleshooting

"No matching federated identity record found"

If you receive the error ERROR: AADSTS70021: No matching federated identity record found for presented assertion. you should verify:

The Issuer defined in the Azure AD federated identity credentials, for example https://gitlab.com or your own GitLab URL.
The Subject identifier defined in the Azure AD federated identity credentials, for example project_path:<mygroup>/<myproject>:ref_type:branch:ref:<branch>.
- For the gitlab-group/gitlab-project project and main branch it would be: project_path:gitlab-group/gitlab-project:ref_type:branch:ref:main.
- The correct values of mygroup and myproject can be retrieved by checking the URL when accessing your GitLab project or, in the upper-right corner of the project's overview page, selecting Code.
The Audience defined in the Azure AD federated identity credentials, for example https://gitlab.com or your own GitLab URL.

You can review these settings, as well as your AZURE_CLIENT_ID and AZURE_TENANT_ID CI/CD variables, from the Azure Portal:

Open the Azure Active Directory App Registration view and select the appropriate app registration by searching for the display name gitlab-oidc.
On the overview page you can verify details like the Application (client) ID, Object ID, and Tenant ID.
Under Certificates & secrets, go to Federated credentials to review your Azure AD federated identity credentials.

Review Connect to cloud services for further details.

`Request to External OIDC endpoint failed` message

If you receive the error ERROR: AADSTS501661: Request to External OIDC endpoint failed. you should verify that your GitLab instance is publicly accessible from the internet.

Azure must be able to access the following GitLab endpoints to authenticate with OIDC:

GET /.well-known/openid-configuration
GET /oauth/discovery/keys

If you update your firewall and still receive this error, clear the Redis cache and try again.

`No matching federated identity record found for presented assertion audience` message

If you receive the error ERROR: AADSTS700212: No matching federated identity record found for presented assertion audience 'https://gitlab.com' you should verify that your CI/CD job uses the correct aud value.

The aud value should match the audience used to create the federated identity credentials.