Use Azure Key Vault secrets in GitLab CI/CD

Version history
  • Introduced in GitLab and GitLab Runner 16.3. Due to issue 424746 this feature did not work as expected.
  • Issue 424746 resolved and this feature made generally available in GitLab Runner 16.6.

You can use secrets stored in the Azure Key Vault in your GitLab CI/CD pipelines.

Prerequisites:

Use Azure Key Vault secrets in a CI/CD job

You can use a secret stored in your Azure Key Vault in a job by defining it with the azure_key_vault keyword:

job:
  id_tokens:
    AZURE_JWT:
      aud: 'https://gitlab.com'
  secrets:
    DATABASE_PASSWORD:
      token: $AZURE_JWT
      azure_key_vault:
        name: 'test'
        version: '00000000000000000000000000000000'

In this example:

  • aud is the audience, which must match the audience used when creating the federated identity credentials
  • name is the name of the secret in Azure Key Vault.
  • version is the version of the secret in Azure Key Vault. The version is a generated GUID without dashes, which can be found on the Azure Key Vault secrets page.
  • GitLab fetches the secret from Azure Key Vault and stores the value in a temporary file. The path to this file is stored in a DATABASE_PASSWORD CI/CD variable, similar to file type CI/CD variables.

Troubleshooting

Refer to OIDC for Azure troubleshooting for general problems when setting up OIDC with Azure.

JWT token is invalid or malformed message

You might receive this error when fetching secrets from Azure Key Vault:

RESPONSE 400 Bad Request
AADSTS50027: JWT token is invalid or malformed.

This occurs due to a known issue in GitLab Runner where the JWT token isn’t parsed correctly. To resolve this, upgrade to GitLab Runner 16.6 or later.

Caller is not authorized to perform action on resource message

You might receive this error when fetching secrets from Azure Key Vault:

RESPONSE 403: 403 Forbidden
ERROR CODE: Forbidden
Caller is not authorized to perform action on resource.\r\nIf role assignments, deny assignments or role definitions were changed recently, please observe propagation time.
ForbiddenByRbac

If your Azure Key Vault is using RBAC, you must add the Key Vault Secrets User role assignment to your Azure AD application.

For example:

appId=$(az ad app list --display-name gitlab-oidc --query '[0].appId' -otsv)
az role assignment create --assignee $appId --role "Key Vault Secrets User" --scope /subscriptions/<subscription-id>

You can find your subscription ID in: