Workload Identity Federation for Google Cloud Storage integrations¶

Related topics¶

• Configure an integration for Google Cloud Storage
• CREATE STORAGE INTEGRATION
• DESCRIBE INTEGRATION
• SYSTEM$VALIDATE_STORAGE_INTEGRATION
• Workload Identity Federation for external volumes

Workload Identity Federation (WIF) lets a Google Cloud Storage (GCS) storage integration authenticate to your Cloud Storage buckets without a long-lived, shared service account credential. With WIF, Snowflake acts as an OpenID Connect (OIDC) identity provider and presents a distinct identity for each storage integration, so you can grant Cloud Storage access to an individual integration rather than to a single principal shared by your whole account.

Overview¶

A standard storage integration uses a dedicated-principal model: the cloud provider provisions one storage service account for your Snowflake account, and you grant that single service account access to every bucket the account needs to reach. For more information, see Configure an integration for Google Cloud Storage. This model has two consequences:

• No isolation between integrations. Because every integration in the account shares the same principal, any storage integration can reach any storage location that the principal can reach. You can’t restrict one integration to a subset of your buckets.
• A long-lived static credential. Access ultimately depends on a long-lived service account credential, which can be a point of friction for accounts with strict security or compliance requirements.

WIF adds a second authentication model that addresses both. Instead of a shared service account, each integration has its own federated identity, described by two values:

• Issuer: Snowflake’s OIDC issuer URL. The issuer is unique to your Snowflake account.
• Subject: an identifier that is unique to a single storage integration within that issuer.

Because the identity is per integration, you grant storage access to one integration at a time, and you no longer manage a long-lived credential for storage access.

How Workload Identity Federation works¶

With WIF, Snowflake is both the identity provider and the signer of the credentials it presents to the cloud provider. You configure a workload identity pool provider to trust Snowflake’s issuer, then grant storage access to the integration’s subject. At runtime, when a query reads from or writes to a stage backed by the integration:

1. Snowflake signs a short-lived JSON Web Token (JWT) with a per-region private key. The token carries the integration’s issuer, subject, audience, and related claims.
2. Snowflake sends the token to the cloud provider’s Security Token Service (STS) endpoint.
3. The cloud provider validates the token’s signature against Snowflake’s published public keys and the trust you configured on the workload identity pool provider, then returns short-lived credentials scoped to the requested storage path.
4. Snowflake uses those short-lived credentials to access your bucket. From the query engine’s perspective, the resulting credentials are used the same way as dedicated-principal credentials.

Token exchange happens when credentials are first needed and when they’re refreshed. There is no long-lived parent credential to store or rotate.

Access modes¶

A WIF GCS integration operates in one of two modes. The mode is determined by whether the integration sets STORAGE_GCP_SERVICE_ACCOUNT; there is no separate mode property.

• Direct mode (STORAGE_GCP_SERVICE_ACCOUNT is not set): you grant IAM roles on your Cloud Storage resources directly to the federated identity. At runtime, Snowflake exchanges its signed JWT for a Google Cloud access token and accesses storage as the federated identity.
• Service account impersonation mode (STORAGE_GCP_SERVICE_ACCOUNT is set): you grant the federated identity permission to impersonate a Cloud Storage service account, and grant that service account access to your Cloud Storage resources. At runtime, Snowflake exchanges its signed JWT for a federated token and then exchanges that token for a service account token. All storage access is performed as the service account.

The following table compares the two modes:

You can switch an existing integration between modes with ALTER STORAGE INTEGRATION by adding or removing STORAGE_GCP_SERVICE_ACCOUNT; you don’t need to re-create the integration.

Configure Workload Identity Federation for a Google Cloud Storage integration¶

Step 1: Get the Snowflake issuer URL¶

Retrieve Snowflake’s OIDC issuer URL before configuring anything on the Google Cloud side. You set this URL as the issuer when you create the Google Cloud workload identity provider in the next step.

SELECT SYSTEM$GET_WORKLOAD_IDENTITY_ISSUER_URL();

Note the returned issuer URL.

Step 2: Create a workload identity pool and provider in Google Cloud¶

In your Google Cloud project, create a workload identity pool and an OIDC provider that trusts the issuer URL from Step 1. After the provider is created, note its full resource name. You supply it as GCP_WORKLOAD_IDENTITY_POOL_PROVIDER in the next step. The resource name has the following form:

//iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/<pool_id>/providers/<provider_id>

Step 3: Create the storage integration¶

Create the storage integration with CREATE STORAGE INTEGRATION, setting AUTH_TYPE = WORKLOAD_IDENTITY_FEDERATION and supplying the provider resource name from Step 2 as GCP_WORKLOAD_IDENTITY_POOL_PROVIDER:

CREATE STORAGE INTEGRATION my_gcs_wif_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'GCS'
  ENABLED = TRUE
  AUTH_TYPE = WORKLOAD_IDENTITY_FEDERATION
  GCP_WORKLOAD_IDENTITY_POOL_PROVIDER = '//iam.googleapis.com/projects/286815202212/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
  STORAGE_ALLOWED_LOCATIONS = ('gcs://my-bucket/');

This example configures direct mode. To configure service account impersonation mode instead, also set STORAGE_GCP_SERVICE_ACCOUNT (see Step 6).

Step 4: Retrieve the WIF identifiers¶

Run DESCRIBE INTEGRATION to retrieve the Snowflake-generated identity claims. Confirm that WORKLOAD_IDENTITY_FEDERATION_ISSUER matches the issuer URL from Step 1.

DESCRIBE INTEGRATION my_gcs_wif_int;

Note the values for the following properties:

• WORKLOAD_IDENTITY_FEDERATION_ISSUER: Snowflake’s OIDC issuer URL.
• WORKLOAD_IDENTITY_FEDERATION_SUBJECT: the unique identifier for this integration. You use this value to grant Cloud Storage access in the next step.

Step 5: Grant access to the federated identity in Google Cloud¶

Grant the necessary IAM roles on your Cloud Storage resources to the federated identity. Use the WORKLOAD_IDENTITY_FEDERATION_SUBJECT value from Step 4 as the subject in the principal identifier:

principal://iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/<pool_id>/subject/<WORKLOAD_IDENTITY_FEDERATION_SUBJECT>

In direct mode, grant this principal a role with the permissions required for your workload (for example, reading or writing objects in the bucket). In service account impersonation mode, grant this principal permission to impersonate your service account, and grant the service account the required roles on the bucket.

Step 6: (Optional) Enable service account impersonation¶

To use service account impersonation mode, set STORAGE_GCP_SERVICE_ACCOUNT on the integration. You can do this at create time if the service account is known in advance, or later with ALTER STORAGE INTEGRATION:

ALTER STORAGE INTEGRATION my_gcs_wif_int
  SET STORAGE_GCP_SERVICE_ACCOUNT = 'my-sa@my-project.iam.gserviceaccount.com';

Step 7: Create an external stage¶

Create an external stage that references the integration, then load or unload data as usual. The stage configuration is the same regardless of the integration’s authentication model. For the stage creation steps, see Create an external stage.

SQL parameters¶

WIF GCS integrations use the following CREATE STORAGE INTEGRATION and ALTER STORAGE INTEGRATION parameters.

AUTH_TYPE = WORKLOAD_IDENTITY_FEDERATION | DEDICATED_PRINCIPAL

Declares the authentication model for the integration. Set WORKLOAD_IDENTITY_FEDERATION to use Workload Identity Federation. The default, DEDICATED_PRINCIPAL, uses the shared service account model described in Configure an integration for Google Cloud Storage.

GCP_WORKLOAD_IDENTITY_POOL_PROVIDER = '<resource_name>'

Required when AUTH_TYPE = WORKLOAD_IDENTITY_FEDERATION. The full resource name of the Google Cloud workload identity pool provider that trusts Snowflake’s issuer, in the form //iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/<pool_id>/providers/<provider_id>.

STORAGE_GCP_SERVICE_ACCOUNT = '<service_account_email>'

Optional. When set, the integration operates in service account impersonation mode and all storage access is performed as this service account. When omitted, the integration operates in direct mode. See Access modes (in this topic).

WORKLOAD_IDENTITY_FEDERATION_AUDIENCE = '<audience>'

Optional. The audience claim included in the signed JWT. When unset, the default is specific to the integration type and cloud provider. Most configurations don’t need to set this value.

DESCRIBE INTEGRATION returns the following WIF-specific properties:

WORKLOAD_IDENTITY_FEDERATION_ISSUER

Snowflake’s OIDC issuer URL for the integration. This value is unique to your Snowflake account.

WORKLOAD_IDENTITY_FEDERATION_SUBJECT

The unique identifier for the integration. Use this value as the subject when you grant Cloud Storage access in Google Cloud.

Limitations and considerations¶

• Signed URLs aren’t supported in this preview. Functions that generate signed URLs, such as GET_PRESIGNED_URL, aren’t supported for WIF GCS integrations in either access mode. In direct mode, signed URLs can’t be supported because no service account identity is available for signing.
• CREATE OR REPLACE generates a new subject. Replacing a WIF integration produces a new WORKLOAD_IDENTITY_FEDERATION_SUBJECT. After a replace, you must reconfigure the IAM bindings in Google Cloud to reference the new subject.
• Replication. The issuer and subject are copied to the secondary integration, and the issuer URL is stable across the primary and secondary regions. As a result, a single Google Cloud workload identity provider and a single set of IAM bindings cover both regions.