debian-mirror-gitlab/doc/ci/cloud_services/azure/index.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

158 lines
7.2 KiB
Markdown
Raw Normal View History

2022-10-11 01:57:18 +05:30
---
stage: Verify
group: Pipeline Authoring
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2022-10-11 01:57:18 +05:30
---
# Configure OpenID Connect in Azure to retrieve temporary credentials
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](../index.md).
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.
2023-01-13 00:05:48 +05:30
- A local installation of the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli).
2023-03-04 22:38:38 +05:30
Alternatively, you can follow all the steps below with the [Azure Cloud Shell](https://portal.azure.com/#cloudshell/).
2022-10-11 01:57:18 +05:30
- A GitLab project.
To complete this tutorial:
1. [Create Azure AD application and service principal](#create-azure-ad-application-and-service-principal).
1. [Create Azure AD federated identity credentials](#create-azure-ad-federated-identity-credentials).
1. [Grant permissions for the service principal](#grant-permissions-for-the-service-principal).
1. [Retrieve a temporary credential](#retrieve-a-temporary-credential).
2023-01-13 00:05:48 +05:30
For more information, review Azure's documentation on [Workload identity federation](https://learn.microsoft.com/en-us/azure/active-directory/develop/workload-identity-federation).
2022-10-11 01:57:18 +05:30
## Create Azure AD application and service principal
2023-01-13 00:05:48 +05:30
To create an [Azure AD application](https://learn.microsoft.com/en-us/cli/azure/ad/app?view=azure-cli-latest#az-ad-app-create)
2022-10-11 01:57:18 +05:30
and service principal:
1. In the Azure CLI, create the AD application:
```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.
2023-01-13 00:05:48 +05:30
1. Create a corresponding [Service Principal](https://learn.microsoft.com/en-us/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create):
2022-10-11 01:57:18 +05:30
```shell
az ad sp create --id $appId --query appId -otsv
```
2023-01-13 00:05:48 +05:30
Instead of the Azure CLI, you can [use the Azure Portal to create these resources](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal).
2022-10-11 01:57:18 +05:30
## Create Azure AD federated identity credentials
To create the federated identity credentials for the above Azure AD application:
```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](#troubleshooting) details.
Optionally, you can now verify the Azure AD application and the Azure AD federated
identity credentials from the Azure Portal:
1. Open the [Azure Active Directory App Registration](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)
view and select the appropriate app registration by searching for the display name `gitlab-oidc`.
1. On the overview page you can verify details like the `Application (client) ID`,
`Object ID`, and `Tenant ID`.
1. Under `Certificates & secrets`, go to `Federated credentials` to review your
Azure AD federated identity credentials.
## Grant permissions for the service principal
2023-01-13 00:05:48 +05:30
After you create the credentials, use [`role assignment`](https://learn.microsoft.com/en-us/cli/azure/role/assignment?view=azure-cli-latest#az-role-assignment-create)
2022-10-11 01:57:18 +05:30
to grant permissions to the above service principal to access to Azure resources:
```shell
az role assignment create --assignee $appId --role Reader --scope /subscriptions/<subscription-id>
```
You can find your subscription ID in:
2023-01-13 00:05:48 +05:30
- The [Azure Portal](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id#find-your-azure-subscription).
- The [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/manage-azure-subscriptions-azure-cli#get-the-active-subscription).
2022-10-11 01:57:18 +05:30
## Retrieve a temporary credential
After you configure the Azure AD application and federated identity credentials,
2023-01-13 00:05:48 +05:30
the CI/CD job can retrieve a temporary credential by using the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/reference-index?view=azure-cli-latest#az-login):
2022-10-11 01:57:18 +05:30
```yaml
default:
image: mcr.microsoft.com/azure-cli:latest
variables:
AZURE_CLIENT_ID: "<client-id>"
AZURE_TENANT_ID: "<tenant-id>"
auth:
script:
- az login --service-principal -u $AZURE_CLIENT_ID -t $AZURE_TENANT_ID --federated-token $CI_JOB_JWT_V2
- az account show
```
The CI/CD variables are:
- `AZURE_CLIENT_ID`: The [application client ID you saved earlier](#create-azure-ad-application-and-service-principal).
- `AZURE_TENANT_ID`: Your Azure Active Directory. You can
2023-01-13 00:05:48 +05:30
[find it by using the Azure CLI or Azure Portal](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-how-to-find-tenant).
2022-10-11 01:57:18 +05:30
- `CI_JOB_JWT_V2`: The JSON web token is a [predefined CI/CD variable](../../variables/predefined_variables.md).
## 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 by selecting the **Clone** option in the project.
- 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:
1. Open the [Azure Active Directory App Registration](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps)
view and select the appropriate app registration by searching for the display name `gitlab-oidc`.
1. On the overview page you can verify details like the `Application (client) ID`,
`Object ID`, and `Tenant ID`.
1. Under `Certificates & secrets`, go to `Federated credentials` to review your
Azure AD federated identity credentials.
Review [Connect to cloud services](../index.md) for further details.