Accessing resources from Microsoft Azure

Beta

This feature is covered by the Pre-GA Offerings Terms of the Google Cloud Platform Terms of Service. Pre-GA features may have limited support, and changes to pre-GA features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

This document shows you how to use identity federation to access Google Cloud resources from Microsoft Azure.

Traditionally, applications running outside Google Cloud have used service account keys to access Google Cloud resources. Using identity federation, you can let a managed identity for an Azure resource impersonate a service account. This lets your workload access Google Cloud resources directly, using a short-lived access token, and eliminates the maintenance and security burden associated with service account keys.

Before you begin

1. Ensure you have the Workload Identity Pool Admin role (roles/iam.workloadIdentityPoolAdmin).

   Alternatively, the IAM Owner (roles/owner) and Editor (roles/editor) basic roles also include permissions to configure identity federation. You should not grant basic roles in a production environment, but you can grant them in a development or test environment.

2. Update the organization policy for your organization to allow federation from Azure.

3. Create a Google Cloud service account.

4. Grant the service account access to call the Google Cloud APIs required by your workload.

Creating a workload identity pool

A workload identity pool is a container for a collection of external identities. Workload identity pools are isolated from each other, but a single pool can impersonate any number of service accounts. In general, we recommend creating a new pool for each of your environments, such as development, staging, or production.

To create a new workload identity pool, you'll need to provide an ID. You can also provide an optional description and display name. The ID cannot begin with gcp-; this prefix is reserved for use by Google.

Note: The combined length of the workload identity pool ID and the workload identity pool provider ID should be no more than 20 characters. If the IDs are longer, the Azure application ID URI will exceed its maximum length.

gcloud

Execute the gcloud beta iam workload-identity-pools create command to create a workload identity pool:

gcloud beta iam workload-identity-pools create pool-id \
    --location="global" \
    --description="description" \
    --display-name="display-name"

The response looks like:

Created workload identity pool [pool-id].

REST

The projects.locations.workloadIdentityPools.create method creates a workload identity pool.

HTTP method and URL:

POST https://iam.googleapis.com/v1beta/projects/project-id/locations/global/workloadIdentityPools?workloadIdentityPoolId=pool-id

Request JSON body:

{
  "description": "description",
  "display-name": "display-name"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to your service account private key file path.

Save the request body in a file called request.json, and execute the following command:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://iam.googleapis.com/v1beta/projects/project-id/locations/global/workloadIdentityPools?workloadIdentityPoolId=pool-id

PowerShell (Windows)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to your service account private key file path.

Save the request body in a file called request.json, and execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1beta/projects/project-id/locations/global/workloadIdentityPools?workloadIdentityPoolId=pool-id" | Select-Object -Expand Content

API Explorer (browser)

Copy the request body and open the method reference page. The API Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Paste the request body in this tool, complete any other required fields, and click Execute.

The method returns a long-running Operation similar to the following:

{
  "name": "projects/project-number/locations/global/workloadIdentityPools/pool-id/operations/operation-id"
}

Adding Azure as an identity provider

To configure Azure as an identity provider for your workload identity pool, supply at least the following:

• An ID for the provider.

  Note: The combined length of the workload identity pool ID and the workload identity pool provider ID should be no more than 20 characters. If the IDs are longer, the Azure application ID URI will exceed its maximum length.

• The workload identity pool ID from the previous section in this document.

• Your Azure Tenant ID.

• A list of attribute mappings that map the claims on a token for an Azure-managed identity to the attributes on a Google token. Use assertion to refer to the Azure token, google for Google attributes, and attribute for custom attributes.

  There are two Google attributes: google.subject and google.groups. You can reference these attributes in IAM role bindings. google.subject also appears in Cloud Logging log entries.

  You must provide a mapping for google.subject. In general, we recommend mapping it to assertion.sub, which contains the object ID of a managed identity that you'll create in the next section. This provides a stable identifier for use in IAM role bindings. The mapping looks like this:

  google.subject=assertion.sub
  

  For more complex assertions, you can use the Common Expression Language. For example, if your workload identity pool contains multiple identity providers, you can append a prefix to disambiguate between them:

  google.subject="azure::" + assertion.tid + "::" + assertion.sub
  

  The google.subject field cannot exceed 127 characters.

  You can also specify custom attributes. For example, the following maps assertion.tid to attribute.tid:

  attribute.tid=assertion.tid
  

  The following example assigns a display name based on the value of assertion.oid:

  attribute.managed_identity_name={
  "8bb39bdb-1cc5-4447-b7db-a19e920eb111":"workload1",
  "55d36609-9bcf-48e0-a366-a3cf19027d2a":"workload2"
  }[assertion.oid]
  

  To obtain a complete list of claims you can reference, get an access token for an Azure VM in your workload. In your request, replace the resource parameter with the full resource name of your workload identity pool.

  Note: Before you can get an access token, you must follow the steps on this page to configure your Azure tenant for identity federation.

  For example:

  curl

  curl -s \
    'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id&object_id=managed-identity-object-id' \
    -H Metadata:true -H "Cache-Control: no-cache"
  

  PowerShell

  Invoke-WebRequest \
      -Uri 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id&object_id=managed-identity-object-id' \
      -Headers @{Metadata="true"}
  

  The response is a JSON object with an access_token field, which contains an access token for the Azure VM. To decode the access token and view the available claims, follow these steps:

  1. Copy the entire access token.
  2. In a web browser, go to https://jwt.ms/.
  3. Paste the access token into the text box.
  4. Click Claims.

  To refer to a specific part of a claim in an expression, use the CEL extract() function, which extracts a value from a claim based on a template you provide. To learn more about extract(), see Extracting values from attributes.

  To check if a credential contains an claim, use the has() function.

You can also provide several optional parameters:

• A display name and description.

• A condition specifying attributes that the principal must present. The condition can apply to claims on the Azure credential, or attributes on the Google credential. Any request that does not meet the condition is rejected.

  Conditions are formatted as a CEL expression that returns a boolean. For example, the following rejects requests from any identity that isn't a member of a specific group:

  "e968c2ef-047c-498d-8d79-16ca1b61e77e" in assertion.groups
  

  To learn more about common use cases for conditions, see the workload identity federation overview.

The following example demonstrates adding Azure as an identity provider:

gcloud

Execute the gcloud beta iam workload-identity-pools providers create-oidc command to add Azure as an identity provider:

gcloud beta iam workload-identity-pools providers create-oidc provider-id \
    --workload-identity-pool="pool-id" \
    --issuer-uri="https://sts.windows.net/azure-tenant-id" \
    --location="global" \
    --attribute-mapping="google.subject=assertion.sub"

The response looks like:

Created workload identity pool provider [provider-id].

REST

The projects.locations.workloadIdentityPools.providers.create method adds Azure as a provider.

HTTP method and URL:

POST https://iam.googleapis.com/v1beta/projects/project-id/locations/global/workloadIdentityPools/pool-id/providers?workloadIdentityPoolProviderId=provider-id

Request JSON body:

{
  "attributeMapping": {
    "google.subject": "assertion.sub"
  },
  "oidc": {
    "issuerUri": "https://sts.windows.net/azure-tenant-id"
  }
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to your service account private key file path.

Save the request body in a file called request.json, and execute the following command:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://iam.googleapis.com/v1beta/projects/project-id/locations/global/workloadIdentityPools/pool-id/providers?workloadIdentityPoolProviderId=provider-id

PowerShell (Windows)

Note: Ensure you have set the GOOGLE_APPLICATION_CREDENTIALS environment variable to your service account private key file path.

Save the request body in a file called request.json, and execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://iam.googleapis.com/v1beta/projects/project-id/locations/global/workloadIdentityPools/pool-id/providers?workloadIdentityPoolProviderId=provider-id" | Select-Object -Expand Content

API Explorer (browser)

Copy the request body and open the method reference page. The API Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Paste the request body in this tool, complete any other required fields, and click Execute.

The method returns a long-running Operation similar to the following:

{
  "name": "projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id/operations/operation-id"
}

Configuring your Azure tenant for identity federation

To prepare your Azure tenant for identity federation:

1. Create an Azure AD application and service principal, and set its Application ID URI to the full resource name of the provider you created in the previous section:

   https://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id
   

2. Create a managed identity, and take note of its object ID.

3. Assign the managed identity to a virtual machine that you want to grant access to Google Cloud resources.

Giving permission to impersonate a service account

External identities can't access most Google Cloud resources directly. Instead, you let the identities impersonate a service account by granting them the Workload Identity User role (roles/iam.workloadIdentityUser).

Note: If your organization, folder, or project restricts identities by domain, you'll need to force account access to grant this role.

To add this role binding for a specific managed identity:

gcloud iam service-accounts add-iam-policy-binding service-account-email \
    --role roles/iam.workloadIdentityUser \
    --member "principal://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/subject/managed-identity-object-id"

To add this binding for all identities in a pool:

gcloud iam service-accounts add-iam-policy-binding service-account-email \
    --role roles/iam.workloadIdentityUser \
    --member "principalSet://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/group/azure-tenant-id"

You can also grant access based on custom attributes. For example:

gcloud iam service-accounts add-iam-policy-binding service-account-email \
    --role="roles/iam.workloadIdentityUser" \
    --member="principalSet://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/attribute.custom-attribute-name/custom-attribute-value"

To revoke access, replace add-iam-policy-binding with remove-iam-policy-binding.

You can also add or revoke bindings using the REST API or client libraries. To learn more, see Granting, changing, and revoking access to resources.

Exchanging an Azure token for a Google token

Once your Azure-managed identity has the ability to impersonate a service account, you can exchange its credentials for Google credentials.

To exchange credentials:

1. Use the Azure Instance Metadata Service (IMDS) to obtain an Azure access token.

   Set the resource query parameter to the following value:

   https://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id
   

   Set the object_id query parameter to the object ID for the managed identity that you created earlier.

2. Pass the Azure access token to the Security Token Service token() method to get a federated access token:

   REST

   The token method exchanges a third-party token for a Google token.

   Before using any of the request data below, make the following replacements:

   • project-number: Your Google Cloud project number.
   • pool-id: The ID of the workload identity pool you created earlier in this tutorial.
   • provider-id: The ID of the identity provider you configured earlier in this tutorial.

   HTTP method and URL:

   POST https://sts.googleapis.com/v1beta/token

   Request JSON body:

   {
     "audience": "//iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id",
     "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
     "requestedTokenType": "urn:ietf:params:oauth:token-type:access_token",
     "scope": "https://www.googleapis.com/auth/cloud-platform",
     "subjectTokenType": "urn:ietf:params:oauth:token-type:jwt",
     "subjectToken": "azure-id-token"
   }
   

   To send your request, expand one of these options:

   curl (Linux, macOS, or Cloud Shell)

   Save the request body in a file called request.json, and execute the following command:

   curl -X POST \
   -H "Content-Type: application/json; charset=utf-8" \
   -d @request.json \
   https://sts.googleapis.com/v1beta/token

   PowerShell (Windows)

   Save the request body in a file called request.json, and execute the following command:

   $headers = @{  }
   
   Invoke-WebRequest `
     -Method POST `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -InFile request.json `
     -Uri "https://sts.googleapis.com/v1beta/token" | Select-Object -Expand Content

   API Explorer (browser)

   Copy the request body and open the method reference page. The API Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Paste the request body in this tool, complete any other required fields, and click Execute.

    

   The method returns a federated token.

3. Call generateAccessToken() to exchange the federated token for a service account access token. A limited number of Google Cloud APIs support federated tokens; all Google Cloud APIs support service account access tokens.

   REST

   The Service Account Credentials API's serviceAccounts.generateAccessToken method generates an OAuth 2.0 access token for a service account.

   Before using any of the request data below, make the following replacements:

   • project-id: Your Google Cloud project ID.
   • sa-id: The ID of your service account. This can either be the service account's email address in the form [e-mail], or the service account's unique numeric ID.
   • token: The federated access token.

   HTTP method and URL:

   POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/[e-mail]:generateAccessToken

   Request JSON body:

   {
     "scope": [
       "https://www.googleapis.com/auth/cloud-platform"
     ]
   }
   

   To send your request, expand one of these options:

   curl (Linux, macOS, or Cloud Shell)

   Save the request body in a file called request.json, and execute the following command:

   curl -X POST \
   -H "Authorization: Bearer token" \
   -H "Content-Type: application/json; charset=utf-8" \
   -d @request.json \
   https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/[e-mail]:generateAccessToken

   PowerShell (Windows)

   Save the request body in a file called request.json, and execute the following command:

   $headers = @{ "Authorization" = "Bearer token" }
   
   Invoke-WebRequest `
     -Method POST `
     -Headers $headers `
     -ContentType: "application/json; charset=utf-8" `
     -InFile request.json `
     -Uri "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/[e-mail]:generateAccessToken" | Select-Object -Expand Content

   API Explorer (browser)

   Copy the request body and open the method reference page. The API Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Paste the request body in this tool, complete any other required fields, and click Execute.

   If the generateAccessToken request was successful, the response body contains an OAuth 2.0 access token and an expiration time. The accessToken can then be used to authenticate a request on behalf of the service account until the expireTime has been reached:

   {
     "accessToken": "eyJ0eXAi...NiJ9",
     "expireTime": "2020-04-07T15:01:23.045123456Z"
   }
   

Once you have an access token for a service account, you can use it to call Google Cloud APIs by including the token in the Authorization header of your requests:

Authorization: Bearer service-account-access-token

The request is authorized as the service account.

What's next

• Use identity federation to access resources from AWS or access resources from an OIDC provider.

• Learn more about workload identity federation.