diff options
Diffstat (limited to 'doc/ci/cloud_services/azure/index.md')
-rw-r--r-- | doc/ci/cloud_services/azure/index.md | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/doc/ci/cloud_services/azure/index.md b/doc/ci/cloud_services/azure/index.md new file mode 100644 index 00000000000..901b36afde6 --- /dev/null +++ b/doc/ci/cloud_services/azure/index.md @@ -0,0 +1,157 @@ +--- +stage: Verify +group: Pipeline Authoring +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# 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. +- A local installation of the [Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli). + Alternatively, you can follow all the steps below with the [Azure Cloud Shell](https://shell.azure.com/). +- 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). + +For more information, review Azure's documentation on [Workload identity federation](https://docs.microsoft.com/azure/active-directory/develop/workload-identity-federation). + +## Create Azure AD application and service principal + +To create an [Azure AD application](https://docs.microsoft.com/cli/azure/ad/app?view=azure-cli-latest#az-ad-app-create) +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. + +1. Create a corresponding [Service Principal](https://docs.microsoft.com/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create): + + ```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](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal). + +## 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 + +After you create the credentials, use [`role assignment`](https://docs.microsoft.com/cli/azure/role/assignment?view=azure-cli-latest#az-role-assignment-create) +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: + +- The [Azure Portal](https://docs.microsoft.com/azure/azure-portal/get-subscription-tenant-id#find-your-azure-subscription). +- The [Azure CLI](https://docs.microsoft.com/cli/azure/manage-azure-subscriptions-azure-cli#get-the-active-subscription). + +## 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](https://docs.microsoft.com/cli/azure/reference-index?view=azure-cli-latest#az-login): + +```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 + [find it by using the Azure CLI or Azure Portal](https://docs.microsoft.com/azure/active-directory/fundamentals/active-directory-how-to-find-tenant). +- `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. |