ContextQMD
Back to Gitlabhq

Configure OpenID Connect in Azure to retrieve temporary credentials

doc/ci/cloud_services/azure/_index.md

18.11.210.4 KB
Original Source

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

[!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.

Prerequisites:

  • Access to an existing Azure Subscription with Owner access level.
  • Access to the corresponding Microsoft Entra ID tenant with at least the Application Developer access level.
  • A local installation of the Azure CLI. Alternatively, you can use all the following steps 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:

  1. Create an Entra ID application and service principal.
  2. Create Entra ID federated identity credentials.
  3. Grant permissions for the service principal.
  4. Retrieve a temporary credential.

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

Create an Entra ID application and service principal

To create an Entra ID application and service principal for GitLab:

  1. In the Azure CLI, create the application for GitLab:

    shell
    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.

  2. Create a corresponding Service Principal:

    shell
    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 Entra ID federated identity credentials

To create the federated identity credentials for the previous Entra ID application for a specific branch in <mygroup>/<myproject>:

shell
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 Entra ID application and the Entra ID federated identity credentials from the Azure Portal:

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

Create credentials for any branch or any tag

To create credentials for any branch or tag (wildcard matching), you can use flexible federated identity credentials.

For all branches in <mygroup>/<myproject>:

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

cat <<EOF > body.json
{
  "name": "gitlab-federated-identity",
  "issuer": "https://gitlab.example.com",
  "subject": null,
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'project_path:<mygroup>/<myproject>:ref_type:branch:ref:*'",
    "languageVersion": 1
  },
  "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 all tags in <mygroup>/<myproject>:

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

cat <<EOF > body.json
{
  "name": "gitlab-federated-identity",
  "issuer": "https://gitlab.example.com",
  "subject": null,
  "claimsMatchingExpression": {
    "value": "claims['sub'] matches 'project_path:<mygroup>/<myproject>:ref_type:tag:ref:*'",
    "languageVersion": 1
  },
  "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

Grant permissions for the service principal

After you create the credentials, use role assignment to grant permissions to the previous service principal so it gets access to the Azure resources:

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

You can find your subscription ID in:

The previous command 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 Entra ID roles.

Retrieve a temporary credential

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

yaml
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:

Troubleshooting

Error: 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 Entra ID federated identity credentials, for example https://gitlab.com or your own GitLab URL.
  • The Subject identifier defined in the Entra ID 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 Entra ID 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:

  1. Open the Microsoft Entra ID App Registration view and select the appropriate app registration by searching for the display name gitlab-oidc.
  2. On the overview page you can verify details like the Application (client) ID, Object ID, and Tenant ID.
  3. Under Certificates & secrets, go to Federated credentials to review your Entra ID 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.