ContextQMD
Back to Gitlabhq

Use Azure Key Vault secrets in GitLab CI/CD

doc/ci/secrets/azure_key_vault.md

18.11.25.4 KB
Original Source

{{< details >}}

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

{{< /details >}}

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

{{< /history >}}

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:

yaml
job:
  id_tokens:
    AZURE_JWT:
      aud: 'https://gitlab.com'
  secrets:
    DATABASE_PASSWORD:
      token: $AZURE_JWT
      azure_key_vault:
        name: 'DATABASE-PASSWORD'
        version: '00000000000000000000000000000000'

To use multiple secrets from Azure Key Vault in the same job, define each secret under the secrets keyword:

yaml
job:
  id_tokens:
    AZURE_JWT:
      aud: 'https://gitlab.com'
  secrets:
    REDIS_PASSWORD:
      token: $AZURE_JWT
      azure_key_vault:
        name: 'REDIS-PASSWORD'
        version: '00000000000000000000000000000000'
    DATABASE_PASSWORD:
      token: $AZURE_JWT
      azure_key_vault:
        name: 'DATABASE-PASSWORD'
        version: '00000000000000000000000000000000'

In these examples:

  • 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 CI/CD variable with the name you defined under secrets (such as DATABASE_PASSWORD or REDIS_PASSWORD), 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:

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

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

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

The secrets provider can not be found. Check your CI/CD variables and try again. message

You might receive this error when attempting to start a job configured to access Azure Key Vault:

plaintext
The secrets provider can not be found. Check your CI/CD variables and try again.

The job can't be created because one or more of the required variables are not defined:

  • AZURE_KEY_VAULT_SERVER_URL
  • AZURE_CLIENT_ID
  • AZURE_TENANT_ID