HashiCorp Cloud Platform
Federate workload identity with Azure
This page describes how to set up workload identity federation to authenticate from Azure VM workloads using managed identity. Authenticated workloads can interact with HCP services without storing any HCP service principal keys.
Prerequisites
You must complete the following steps before configuring a workload identity provider for Azure:
- You must have the
Admin
role on the HCP project. - Create a service principal in the desired project and grant it access to the HCP resources your workload requires.
- Have access to the Azure account to federate access to HCP from.
- Install the HCP CLI or use the HCP Terraform Provider based on your desired configuration workflow.
Azure configuration prerequisites
To federate workload identity with Azure, you need to create and configure a new Azure AD application in your Azure AD tenant. After you configure the workload identity provider to trust the application, Azure workloads can retrieve access tokens for this application and exchange them for HCP access tokens.
Complete the following steps to prepare your Azure environment for workload identity federation:
- Register a Microsoft Entra app and create a service principal. You can use the default Application (client) ID or specify a custom URI, but make note of Application ID URI. You need this value when you configure the workload identity provider.
- Create a managed identity. Note its Object ID. You can use this value when you configure the conditional access statement.
- Assign the managed identity. You can assign it to a virtual machine or another resource where your application is running.
Configure an external workload identity provider for Azure
To create an HCP workload identity provider for Azure, you must provide the following configuration values:
- Your Azure AD Tenant ID (GUID).
- The Application ID URI of the application you registered in Azure AD.
- A conditional access statement.
Conditional access statement
When federating workload identity, one of the requirements is a conditional access statement. This statement is a boolean expression that has access to the identity claims and restricts which external identities are allowed.
When exchanging an Azure token for access to HCP, the conditional access statement has access to all the claims in the token with the jwt_claims.
prefix. For most scenarios, we recommend using the sub
claim that matches the Object ID
of the managed identity attached to the workload. For more information, refer to the access token claim reference in the Azure documentation.
The following example conditional access statement restricts access to HCP services to Azure workloads assigned the managed role whose Object ID
is d4766c62-e179-49f9-b3a8-3a8c6720aa96
.
`jwt_claims.sub == "d4766c62-e179-49f9-b3a8-3a8c6720aa96"`
For a complete list of claims you can reference, complete the following steps:
SSH to the VM.
Obtain an access token using the IMDS endpoint. Replace the
APP_ID
with the Application ID from the Azure AD application or the custom URI described in the Azure configuration prerequisites.curl "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID&api-version=2018-02-01" \ -H "Metadata: true" | jq -r .access_token
To view the claims, copy the access token and paste it into a browser-based token decoder. The claims listed are values available when creating the conditional access statement.
Create the workload identity provider
After you gather the information you need, create the workload identity provider for Azure.
Use the hcp iam workload-identity-providers create-oidc
command.
$ hcp iam workload-identity-providers create-oidc <PROVIDER_NAME> \
--service-principal=<SP_RESOURCE_NAME> \
--issuer=https://sts.windows.net/<TENANT_ID>/ \
--allowed-audience=<APP_ID> \
--conditional-access=<CONDITION> \
--description=<DESCRIPTION>
This command requires the following information that is specific to your HCP and Azure accounts:
<PROVIDER_NAME>
: The name of workload identity provider to create.<SP_RESOURCE_NAME>
:The service principal’s resource name, in the formatiam/project/<PROJECT_ID>/service-principal/<NAME>
.<TENANT_ID>
: The Azure AD Tenant ID (GUID) you want to allow federation from. Sometimes this ID is formatted ashttps://sts.windows.net/<TENANT_ID>/
.<APP_ID>
: TheApplication ID
from the Azure AD Application, or the custom URI used.<CONDITION>
: The conditional access statement that restricts access to the specified Azure workload.<DESCRIPTION>
: An optional description for the provider.
The following example creates a workload identity provider named azure-example
. This provider configures HCP to restrict access to external workloads by requiring that their JWT token have d4766c62-e179-49f9-b3a8-3a8c6720aa96
as a sub
claim. Workloads that are granted access to HCP services use the my-app-runtime
service principal.
$ hcp iam workload-identity-providers create-oidc azure-example \
--service-principal=iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-app-runtime \
--issuer=https://sts.windows.net/60a0d497-45cd-413d-95ca-e154bbb9129b/ \
--allowed-audience=d821efa3-8cd7-4977-bdf7-bd6e44b1dc46 \
--conditional-access='jwt_claims.sub == "d4766c62-e179-49f9-b3a8-3a8c6720aa96"' \
--description="Allow my-app-role on Azure to act as my-app-runtime service principal"
Authenticate the workload's credentials
You can use the HCP CLI, HCP Terraform Provider, or HCP Go SDK to automatically retrieve external credentials and exchange them for an HCP access token. This process uses a credential file that contains the information required to obtain external credentials and the workload identity provider to exchange them with.
For more information, refer to credential files.
Create the credential file for Azure
Use the hcp iam workload-identity-providers create-cred-file command
.
$ hcp iam workload-identity-providers create-cred-file <PROVIDER_NAME> \
--azure \
--azure-resource=<APP_ID> \
--output-file=credentials.json
This command requires the following information that is specific to your HCP and Azure accounts:
<PROVIDER_NAME>
: The name of Workload Identity Provider to exchange credentials with, in the formatiam/project/<PROJECT_ID>/service-principal/<SP_NAME>/workload-identity-provider/<PROVIDER_NAME>
.<APP_ID>
: TheApplication ID
from the Azure AD Application, or the custom URI used.
The following example creates a credentials.json
file using the azure-example
provider, which is associated with the my-app-runtime
service principal.
$ hcp iam workload-identity-providers create-cred-file \
iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-app-runtime/workload-identity-provider/azure-example \
--azure \
--azure-resource=d821efa3-8cd7-4977-bdf7-bd6e44b1dc46 \
--output-file=credentials.json
Ensure the credential file exists in the runtime environment. Because the credential file contains no secret values, you can store the credential file in the VM image. Alternatively, you can generate it at runtime.
To use the credential file to authenticate, you can use the HCP CLI, the HCP Terraform provider, or the HCP Go SDK. Refer to use a credential file to authenticate for more information.