Configure OpenID Connect in Azure to retrieve temporary credentials All tiers All offerings
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, review Azure’s documentation on 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
, andTenant ID
. - Under
Certificates & secrets
, go toFederated 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 examplehttps://gitlab.com
or your own GitLab URL. - The
Subject identifier
defined in the Azure AD federated identity credentials, for exampleproject_path:<mygroup>/<myproject>:ref_type:branch:ref:<branch>
.- For the
gitlab-group/gitlab-project
project andmain
branch it would be:project_path:gitlab-group/gitlab-project:ref_type:branch:ref:main
. - The correct values of
mygroup
andmyproject
can be retrieved by checking the URL when accessing your GitLab project or by selecting the Clone option in the project.
- For the
- The
Audience
defined in the Azure AD federated identity credentials, for examplehttps://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
, andTenant ID
. - Under
Certificates & secrets
, go toFederated 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.