Workload Identity Federation for external volumes¶

Workload Identity Federation (WIF) lets an external volume authenticate to your cloud storage without the account-wide principal that Snowflake provisions. With WIF, Snowflake acts as an OpenID Connect (OIDC) identity provider and presents a distinct identity for each external volume, so you can grant storage access to an individual external volume rather than to a single principal shared by your whole Snowflake account.

This preview supports Amazon S3, Google Cloud Storage, and Azure external volumes. WIF is also available for storage integrations. For more information, see Workload Identity Federation for Amazon S3 Storage integrations, Workload Identity Federation for Google Cloud Storage integrations, and Workload Identity Federation for Azure Blob Storage integrations.

Overview¶

A standard external volume uses a dedicated-principal model: Snowflake provisions one cloud identity for your Snowflake account, and every external volume in the account uses it. On Amazon S3 that identity is an AWS IAM user that your own IAM role trusts; on Google Cloud Storage it’s a Cloud Storage service account; on Azure it’s a Snowflake-managed service principal that you grant access to directly. For more information, see Configure an external volume for Amazon S3, Configure an external volume for Google Cloud Storage, and Configure an external volume for Azure. This model has two consequences:

• No isolation between external volumes. Because every external volume in the account shares the same principal, any external volume can reach any storage location that the principal can reach. You can’t restrict one external volume to a subset of your buckets.
• A long-lived static credential. Access ultimately depends on a long-lived 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 principal, each external volume 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 external volume within that issuer.

Because the identity belongs to the external volume, you grant storage access to one external volume at a time, and you no longer manage a long-lived credential for storage access.

One federated identity per external volume¶

The subject identifies the external volume, not an individual storage location. An external volume that defines several storage locations has one federated identity, and that identity is used for every bucket the external volume references. The unit of isolation is therefore the external volume: to isolate buckets from each other, define separate external volumes.

Within a single external volume you can still differentiate access per storage location, because each location names its own cloud-side target: an IAM role on Amazon S3, a managed identity or app registration on Azure, or a service account on Google Cloud Storage when the location uses service account impersonation mode. The one federated identity then assumes or impersonates a different principal for each location. Direct mode on Google Cloud Storage has no equivalent lever: all such locations authenticate as the federated identity itself.

If two storage locations trust the federated identity through separate cloud-side configurations, such as two IAM roles on Amazon S3, two managed identities on Azure, or two workload identity pools on Google Cloud, authorize the external volume’s subject in each one.

Regardless of how many storage locations you define, Apache Iceberg™ tables read from and write to a single active storage location at a time.

How Workload Identity Federation works¶

With WIF, Snowflake is both the identity provider and the signer of the credentials it presents to your cloud provider. You configure your cloud provider to trust Snowflake’s issuer, then grant storage access to the external volume’s subject. At runtime, when a query reads from or writes to an Apache Iceberg™ table backed by the external volume:

1. Snowflake signs a short-lived JSON Web Token (JWT) with a per-region private key. The token carries the external volume’s issuer, subject, audience, and related claims.
2. Snowflake sends the token to your cloud provider’s token service: AWS Security Token Service (STS) for Amazon S3, Microsoft Entra ID for Azure, or Google Cloud’s Security Token Service for Google Cloud Storage.
3. Your cloud provider validates the token’s signature against Snowflake’s published public keys and the trust you configured, 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 the credentials of the account-level principal.

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

Prerequisites¶

Before you configure a WIF external volume, you need the following:

• A cloud storage bucket. To use the external volume for externally managed Apache Iceberg™ tables, all of your table data and metadata files must be located in the bucket.

• Permissions in your cloud provider to create the trust configuration and grant storage access:

  • Amazon S3: permission to create an IAM OIDC identity provider and an IAM role.
  • Google Cloud Storage: permission to create a workload identity pool and provider, and to grant IAM roles.
  • Azure: permission to create a managed identity or app registration, add a federated identity credential to it, and assign Azure RBAC roles.

  If you aren’t a cloud administrator, ask your cloud administrator to perform these tasks.

• In Snowflake, the ACCOUNTADMIN role or a role with the global CREATE EXTERNAL VOLUME privilege. Only such a role can create or alter an external volume.

Get the Snowflake issuer URL¶

Retrieve Snowflake’s OIDC issuer URL before you configure anything on the cloud side. You set this URL as the issuer when you create the trust configuration in your cloud provider.

SELECT SYSTEM$GET_WORKLOAD_IDENTITY_ISSUER_URL();

Note the returned issuer URL. Run this function in your primary account: it returns an error in a read-only secondary account.

Configure Workload Identity Federation for an Amazon S3 external volume¶

An Amazon S3 WIF storage location always authenticates by assuming an IAM role that you own. Snowflake presents its signed JWT to AWS STS through sts:AssumeRoleWithWebIdentity, and all storage access is performed as that role. There are no alternative access modes.

Step 1: Create an IAM OIDC identity provider in AWS¶

To establish trust between Snowflake and your AWS account, register Snowflake’s issuer as an OIDC identity provider.

1. In the AWS Management Console, go to IAM > Identity providers, then select Add provider.
2. For Provider type, select OpenID Connect.
3. For Provider URL, enter the Snowflake issuer URL from Get the Snowflake issuer URL.
4. For Audience, enter sts.amazonaws.com.
5. Select Add provider.

Step 2: Create an IAM role¶

Create the role that Snowflake assumes, and grant it access to your bucket.

1. From the left-hand navigation pane in the IAM dashboard, select Roles, then select Create role.

2. For Trusted entity type, select Web identity.

3. For Identity provider, select the provider you created in Step 1. For Audience, select the audience you configured on it. AWS uses these two selections to populate the role’s trust policy for you, including the Federated principal and an aud condition. You add one more condition to this same trust policy in Step 5.

4. Attach a policy that grants Snowflake the permissions it needs on your bucket.

   First, confirm the AWS Security Token Service (STS) endpoint is active in your region. In the IAM dashboard, go to Account settings, and under Security Token Service (STS) in the Endpoints list, find the region where your Snowflake account is located. If its STS status is inactive, move the toggle to Active.

   Then create a policy that grants access to your bucket. The following example grants read and write access to all objects in the specified bucket:

   Copy code

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:PutObject",
           "s3:GetObject",
           "s3:GetObjectVersion",
           "s3:DeleteObject",
           "s3:DeleteObjectVersion"
         ],
         "Resource": "arn:aws:s3:::<my_bucket>/*"
       },
       {
         "Effect": "Allow",
         "Action": [
           "s3:ListBucket",
           "s3:GetBucketLocation"
         ],
         "Resource": "arn:aws:s3:::<my_bucket>",
         "Condition": {
           "StringLike": {
             "s3:prefix": ["*"]
           }
         }
       }
     ]
   }
   

   Replace <my_bucket> with your bucket name. You can also scope access to a path inside the bucket, for example my_bucket/path; set "s3:prefix" to ["path/*"] to match. For an access-point ARN instead of a bucket ARN, see Step 1: Create an IAM policy that grants access to your S3 location.

5. On the role summary page, locate and record the Role ARN value. You reference this role when you create the external volume in the next step.

You tighten this role’s trust policy to a single external volume in Step 5, after the external volume exists and has a subject. This binds the role’s access policy to this specific external volume, rather than to every identity your Snowflake account’s issuer signs.

Step 3: Create the external volume¶

Create the external volume with CREATE EXTERNAL VOLUME. Set AUTH_TYPE = 'WORKLOAD_IDENTITY_FEDERATION' on the external volume, and set STORAGE_AWS_ROLE_ARN on each S3 storage location, using the role ARN from Step 2.

CREATE EXTERNAL VOLUME my_s3_wif_ev
  STORAGE_LOCATIONS =
    (
      (
        NAME = 's3-loc-1'
        STORAGE_PROVIDER = 'S3'
        STORAGE_BASE_URL = 's3://my-bucket/'
        STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/my-snowflake-wif-role'
      )
    )
  AUTH_TYPE = 'WORKLOAD_IDENTITY_FEDERATION';

Don’t set STORAGE_AWS_EXTERNAL_ID on a WIF storage location. OIDC trust replaces the external ID mechanism, and Snowflake rejects the property.

ALLOW_WRITES behaves the same way as it does for any external volume, and must be TRUE for Snowflake-managed Apache Iceberg™ tables. For more information, see ALLOW_WRITES = ‘{ TRUE | FALSE }’. The IAM role must hold matching write permissions on the bucket.

Step 4: Retrieve the WIF identifiers¶

Run DESCRIBE EXTERNAL VOLUME to retrieve the Snowflake-generated identity claims. Confirm that WORKLOAD_IDENTITY_FEDERATION_ISSUER matches the issuer URL from Get the Snowflake issuer URL.

DESC EXTERNAL VOLUME my_s3_wif_ev;

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 external volume. You use this value in the next step.

AUTH_TYPE, WORKLOAD_IDENTITY_FEDERATION_ISSUER, and WORKLOAD_IDENTITY_FEDERATION_SUBJECT are properties of the external volume. The WIF properties that you set on a storage location appear inside the value of the corresponding STORAGE_LOCATION_<n> property rather than as separate rows. The output doesn’t include STORAGE_AWS_IAM_USER_ARN or STORAGE_AWS_EXTERNAL_ID: a WIF external volume has no shared IAM user and no external ID.

Step 5: Restrict the IAM role to the external volume’s subject¶

If you created the role through the AWS console in Step 2, AWS already populated the role’s trust policy for you: it trusts your identity provider (the Federated principal) and restricts the aud claim to the audience you selected there. You don’t need to reconstruct any of that. The only thing missing is a condition that also restricts the sub claim, so that only this external volume, not every identity your account’s issuer signs, can assume the role.

1. In the IAM dashboard, open the role you created, select Trust relationships, then select Edit trust policy.
2. In the existing Condition > StringEquals block, add a new key with the same provider-host-and-path prefix as the aud key that’s already there, but ending in :sub instead of :aud. Copy that prefix from the existing key rather than typing it from scratch. Set the new key’s value to the WORKLOAD_IDENTITY_FEDERATION_SUBJECT value from Step 4.

After the addition, the trust policy looks like the following. The Principal and the aud condition are what AWS generated automatically in Step 2; the sub condition is the one line you add:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<aws_account_id>:oidc-provider/<issuer_host_and_path>"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "<issuer_host_and_path>:aud": "sts.amazonaws.com",
          "<issuer_host_and_path>:sub": "<workload_identity_federation_subject>"
        }
      }
    }
  ]
}

Where:

• <aws_account_id> and the <issuer_host_and_path> prefix on the aud key are already filled in from Step 2.
• <workload_identity_federation_subject> is the subject value from Step 4, for example identity_external_volume_9f86d081…b0f00a08.

Always copy the subject from the DESC EXTERNAL VOLUME output of the external volume you’re configuring. Don’t construct the value by hand, and don’t reuse a subject from a storage integration: external volume subjects begin with identity_external_volume_ while storage integration subjects begin with identity_external_stage_integration_. A condition built from the wrong subject fails silently, because AWS simply denies the token exchange.

Step 6: Verify storage access¶

Verify the external volume with SYSTEM$VERIFY_EXTERNAL_VOLUME. External volumes use this function; SYSTEM$VALIDATE_STORAGE_INTEGRATION applies to storage integrations and doesn’t apply here.

SELECT SYSTEM$VERIFY_EXTERNAL_VOLUME('my_s3_wif_ev');

If verification fails with a token exchange or permission error from AWS, check the following:

• The sub condition in the trust policy matches the WORKLOAD_IDENTITY_FEDERATION_SUBJECT value exactly, including the identity_external_volume_ prefix.
• The aud condition, the audience on the identity provider, and the audience Snowflake sends for this storage location all match. Snowflake sends sts.amazonaws.com unless the location sets WORKLOAD_IDENTITY_FEDERATION_AUDIENCE.
• The provider URL on the identity provider matches the issuer URL from Get the Snowflake issuer URL.
• The role’s permissions policy grants access to the bucket path in STORAGE_BASE_URL.

Configure Workload Identity Federation for a Google Cloud Storage external volume¶

Access modes¶

A WIF GCS storage location operates in one of two modes. The mode is determined per storage location, by whether that location 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 storage location between modes with ALTER EXTERNAL VOLUME; you don’t need to re-create the external volume. External volumes use the UPDATE STORAGE_LOCATION clause rather than SET and UNSET. For more information, see Switch between access modes (in this topic).

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

To establish trust between Snowflake and your Google Cloud environment, create a workload identity pool and an OIDC provider.

1. In the Google Cloud console, open IAM & Admin and go to the workload identity pools page.

2. Create a workload identity pool.

3. Add an OIDC provider to the pool:

   • Issuer (URL): the Snowflake issuer URL from Get the Snowflake issuer URL.
   • Audience: select Default audience.

4. Record the provider’s full resource name. It uses the following pattern:

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

You supply this resource name as GCP_WORKLOAD_IDENTITY_POOL_PROVIDER in the next step. Snowflake validates its format, so note the following requirements:

• <project_number> is the numeric Google Cloud project number, not the project ID.
• <pool_id> and <provider_id> are each 4 to 32 characters, and can contain only lowercase letters, digits, and hyphens.

For more information, see Configure workload identity federation in the Google Cloud documentation.

Step 2: Create the external volume¶

Create the external volume with CREATE EXTERNAL VOLUME. Set AUTH_TYPE = 'WORKLOAD_IDENTITY_FEDERATION' on the external volume, and set GCP_WORKLOAD_IDENTITY_POOL_PROVIDER on each GCS storage location, using the provider resource name from Step 1.

The following example configures service account impersonation mode:

CREATE EXTERNAL VOLUME my_gcs_wif_ev
  STORAGE_LOCATIONS =
    (
      (
        NAME = 'gcs-loc-1'
        STORAGE_PROVIDER = 'GCS'
        STORAGE_BASE_URL = 'gcs://my-bucket/'
        GCP_WORKLOAD_IDENTITY_POOL_PROVIDER = '//iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        STORAGE_GCP_SERVICE_ACCOUNT = 'snowflake-impersonator@my-project.iam.gserviceaccount.com'
      )
    )
  AUTH_TYPE = 'WORKLOAD_IDENTITY_FEDERATION';

To configure direct mode instead, omit STORAGE_GCP_SERVICE_ACCOUNT:

CREATE EXTERNAL VOLUME my_gcs_wif_direct_ev
  STORAGE_LOCATIONS =
    (
      (
        NAME = 'gcs-loc-1'
        STORAGE_PROVIDER = 'GCS'
        STORAGE_BASE_URL = 'gcs://my-bucket/'
        GCP_WORKLOAD_IDENTITY_POOL_PROVIDER = '//iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
      )
    )
  AUTH_TYPE = 'WORKLOAD_IDENTITY_FEDERATION';

ALLOW_WRITES behaves the same way as it does for any external volume, and must be TRUE for Snowflake-managed Apache Iceberg™ tables. For more information, see ALLOW_WRITES = ‘{ TRUE | FALSE }’. Whichever principal accesses storage, the federated identity in direct mode or the impersonated service account in service account impersonation mode, must hold matching write permissions on the bucket.

Step 3: Retrieve the WIF identifiers¶

Run DESCRIBE EXTERNAL VOLUME to retrieve the Snowflake-generated identity claims. Confirm that WORKLOAD_IDENTITY_FEDERATION_ISSUER matches the issuer URL from Get the Snowflake issuer URL.

DESC EXTERNAL VOLUME my_gcs_wif_ev;

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 external volume. You use this value to grant Cloud Storage access in the next step.

AUTH_TYPE, WORKLOAD_IDENTITY_FEDERATION_ISSUER, and WORKLOAD_IDENTITY_FEDERATION_SUBJECT are properties of the external volume. The WIF properties that you set on a storage location appear inside the value of the corresponding STORAGE_LOCATION_<n> property rather than as separate rows.

Step 4: Grant access 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 3 as the subject in the principal identifier:

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

Always copy the subject from the DESC EXTERNAL VOLUME output of the external volume you’re configuring. Don’t construct the value by hand, and don’t reuse a subject from a storage integration: external volume subjects begin with identity_external_volume_ while storage integration subjects begin with identity_external_stage_integration_. A binding built from the wrong subject fails silently, because Google Cloud simply denies the token exchange.

Service account impersonation mode¶

1. Grant this principal the Workload Identity User role (roles/iam.workloadIdentityUser) on the service account that you named in STORAGE_GCP_SERVICE_ACCOUNT.
2. Grant that service account the permissions Snowflake requires on your bucket. For the custom IAM role and the Google Cloud console steps, see Create a custom IAM role.

When you follow those steps, assign the custom role to your own service account, the one you named in STORAGE_GCP_SERVICE_ACCOUNT. Don’t assign it to the service account that Snowflake provisions for your account, and skip the step that retrieves that service account.

Direct mode¶

In direct mode there is no service account to carry bucket access, so grant the bucket permissions to the federated identity itself. Assign the same custom IAM role described in Create a custom IAM role to the principal:// identifier, at the bucket level.

Step 5: Verify storage access¶

Verify the external volume with SYSTEM$VERIFY_EXTERNAL_VOLUME. External volumes use this function; SYSTEM$VALIDATE_STORAGE_INTEGRATION applies to storage integrations and doesn’t apply here.

SELECT SYSTEM$VERIFY_EXTERNAL_VOLUME('my_gcs_wif_ev');

If verification fails with a token exchange or permission error from Google Cloud, check the following:

• The subject in your IAM binding matches the WORKLOAD_IDENTITY_FEDERATION_SUBJECT value from Step 3 exactly, including the identity_external_volume_ prefix.
• The issuer configured on your workload identity pool provider matches the URL from Get the Snowflake issuer URL.
• In service account impersonation mode, the federated identity holds roles/iam.workloadIdentityUser on the service account named in STORAGE_GCP_SERVICE_ACCOUNT.

Configure Workload Identity Federation for an Azure external volume¶

An Azure WIF storage location always authenticates as a managed identity or app registration that you own, using a federated identity credential (FIC) that trusts Snowflake’s issuer. There are no alternative access modes: Azure has no equivalent of Google Cloud Storage’s direct-versus-impersonation distinction.

Step 1: Find your Azure AD tenant ID¶

In the Azure portal, go to Azure Active Directory > Properties. The tenant ID is displayed in the Tenant ID field.

You provide this value as AZURE_TENANT_ID when you create the external volume.

Step 2: Create a managed identity¶

If you don’t already have a user-assigned managed identity for Snowflake to assume, create one in your Azure subscription.

1. In the Azure portal, go to Managed Identities and select Create.
2. Select your subscription and resource group, choose a region, and provide a name for the identity.
3. Select Review + create, then Create.
4. After creation, note the Client ID from the identity’s overview page.

You provide this value as AZURE_CLIENT_ID when you create the external volume. You configure the trust relationship itself, the federated identity credential, in Step 5 (in this topic), after the external volume exists and has a subject.

Step 3: Create the external volume in Snowflake¶

Create the external volume with CREATE EXTERNAL VOLUME. Set AUTH_TYPE = 'WORKLOAD_IDENTITY_FEDERATION' on the external volume, and set AZURE_TENANT_ID and AZURE_CLIENT_ID on each Azure storage location, using the values from Step 1 and Step 2.

CREATE EXTERNAL VOLUME my_azure_wif_ev
  STORAGE_LOCATIONS =
    (
      (
        NAME = 'azure-loc-1'
        STORAGE_PROVIDER = 'AZURE'
        STORAGE_BASE_URL = 'azure://my-account.blob.core.windows.net/my-container/'
        AZURE_TENANT_ID = '<your-azure-ad-tenant-id>'
        AZURE_CLIENT_ID = '<client-id-of-your-managed-identity>'
      )
    )
  AUTH_TYPE = 'WORKLOAD_IDENTITY_FEDERATION';

ALLOW_WRITES behaves the same way as it does for any external volume, and must be TRUE for Snowflake-managed Apache Iceberg™ tables. For more information, see ALLOW_WRITES = ‘{ TRUE | FALSE }’. The managed identity must hold matching write permissions on the storage account.

Step 4: Retrieve the WIF issuer and subject¶

Run DESCRIBE EXTERNAL VOLUME to retrieve the Snowflake-generated identity claims. Confirm that WORKLOAD_IDENTITY_FEDERATION_ISSUER matches the issuer URL from Get the Snowflake issuer URL.

DESC EXTERNAL VOLUME my_azure_wif_ev;

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 external volume. You use this value in the next step.

AUTH_TYPE, WORKLOAD_IDENTITY_FEDERATION_ISSUER, and WORKLOAD_IDENTITY_FEDERATION_SUBJECT are properties of the external volume. The WIF properties that you set on a storage location appear inside the value of the corresponding STORAGE_LOCATION_<n> property rather than as separate rows.

Step 5: Create the federated identity credential¶

To establish trust between Azure AD and Snowflake’s OIDC issuer, create a federated identity credential (FIC) on the managed identity from Step 2.

1. In the Azure portal, go to your managed identity.
2. Under Settings, select Federated credentials, then select Add Credential.
3. For Federated credential scenario, select Other issuer.
4. Fill in the following fields:
   • Issuer: the WORKLOAD_IDENTITY_FEDERATION_ISSUER value from Step 4.
   • Subject identifier: the WORKLOAD_IDENTITY_FEDERATION_SUBJECT value from Step 4.
   • Audience: api://AzureADTokenExchange, unless you set a custom WORKLOAD_IDENTITY_FEDERATION_AUDIENCE on the storage location.
   • Name: a descriptive name for the credential, for example snowflake-wif-credential.
5. Select Add.

Alternatively, use the Azure CLI:

az identity federated-credential create \
    --name snowflake-wif-credential \
    --identity-name my-snowflake-wif-identity \
    --resource-group my-resource-group \
    --issuer '<WORKLOAD_IDENTITY_FEDERATION_ISSUER value>' \
    --subject '<WORKLOAD_IDENTITY_FEDERATION_SUBJECT value>' \
    --audiences 'api://AzureADTokenExchange'

Always copy the subject from the DESC EXTERNAL VOLUME output of the external volume you’re configuring. Don’t construct the value by hand, and don’t reuse a subject from a storage integration: external volume subjects begin with identity_external_volume_ while storage integration subjects begin with identity_external_stage_integration_. A federated identity credential built from the wrong subject fails silently, because Azure AD simply denies the token exchange.

Step 6: Assign RBAC roles to the managed identity¶

Grant the managed identity access to your storage account. Two role assignments are required:

• Storage Blob Data Contributor, scoped to the container. Grants read and write access to blob data.
• Storage Blob Delegator, scoped to the storage account. Required because Snowflake uses User Delegation SAS tokens, which call the storage-account-level Get User Delegation Key API.

To assign the roles in the Azure portal:

1. Go to your storage account, select Access Control (IAM), then Add role assignment.
2. Search for and select Storage Blob Delegator, then select Next.
3. Under Members, select Managed identity, then select your managed identity.
4. Select Review + assign.
5. Repeat for Storage Blob Data Contributor, this time scoped to the specific container: go to Containers > your container > Access Control (IAM), then add the role assignment there.

Alternatively, use the Azure CLI:

# Storage Blob Delegator at the storage account scope
az role assignment create \
    --assignee-object-id "$(az identity show --name my-snowflake-wif-identity --resource-group my-resource-group --query principalId -o tsv)" \
    --assignee-principal-type ServicePrincipal \
    --role "Storage Blob Delegator" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>"

# Storage Blob Data Contributor at the container scope
az role assignment create \
    --assignee-object-id "$(az identity show --name my-snowflake-wif-identity --resource-group my-resource-group --query principalId -o tsv)" \
    --assignee-principal-type ServicePrincipal \
    --role "Storage Blob Data Contributor" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/blobServices/default/containers/<container>"

Step 7: Verify storage access¶

Verify the external volume with SYSTEM$VERIFY_EXTERNAL_VOLUME. External volumes use this function; SYSTEM$VALIDATE_STORAGE_INTEGRATION applies to storage integrations and doesn’t apply here.

SELECT SYSTEM$VERIFY_EXTERNAL_VOLUME('my_azure_wif_ev');

If verification fails with a token exchange or permission error from Azure, check the following:

• The subject in the federated identity credential matches the WORKLOAD_IDENTITY_FEDERATION_SUBJECT value from Step 4 exactly, including the identity_external_volume_ prefix.
• The issuer configured on the federated identity credential matches the URL from Get the Snowflake issuer URL.
• The audience configured on the federated identity credential matches the audience Snowflake sends for this storage location. Snowflake sends api://AzureADTokenExchange unless the location sets WORKLOAD_IDENTITY_FEDERATION_AUDIENCE.
• The managed identity holds both Storage Blob Data Contributor (container scope) and Storage Blob Delegator (storage account scope).

Create an Apache Iceberg™ table¶

Create an Apache Iceberg™ table that references the external volume by name. Table creation is the same regardless of the external volume’s cloud provider or authentication model:

CREATE ICEBERG TABLE my_wif_table (id INT, name STRING)
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_s3_wif_ev'
  BASE_LOCATION = 'my_wif_table/';

For more information, including options for externally managed tables, see Create an Apache Iceberg™ table in Snowflake and Configure a catalog integration.

Modify properties of a WIF external volume¶

You may want to update a WIF external volume after you create it, for example to change the audience, switch a Google Cloud Storage location between access modes, or rotate a role or identity. Make these changes with the UPDATE STORAGE_LOCATION clause of ALTER EXTERNAL VOLUME. External volumes don’t support UNSET; assign NULL to a property instead to clear it.

Update the audience¶

ALTER EXTERNAL VOLUME my_s3_wif_ev
  UPDATE STORAGE_LOCATION = 's3-loc-1'
  WORKLOAD_IDENTITY_FEDERATION_AUDIENCE = 'my-custom-audience';

When the audience isn’t set, it defaults to a value that depends on the storage provider:

• Amazon S3: sts.amazonaws.com.
• Azure: api://AzureADTokenExchange.
• Google Cloud Storage: the value of GCP_WORKLOAD_IDENTITY_POOL_PROVIDER for the same storage location, which is what a provider configured with Default audience expects.

Most configurations don’t need to set this value. To return to the default, assign NULL:

ALTER EXTERNAL VOLUME my_s3_wif_ev
  UPDATE STORAGE_LOCATION = 's3-loc-1'
  WORKLOAD_IDENTITY_FEDERATION_AUDIENCE = NULL;

Switch between access modes (Google Cloud Storage)¶

To move a storage location from direct mode to service account impersonation mode, set STORAGE_GCP_SERVICE_ACCOUNT:

ALTER EXTERNAL VOLUME my_gcs_wif_ev
  UPDATE STORAGE_LOCATION = 'gcs-loc-1'
  STORAGE_GCP_SERVICE_ACCOUNT = 'snowflake-impersonator@my-project.iam.gserviceaccount.com';

To move a storage location from service account impersonation mode to direct mode, assign NULL:

ALTER EXTERNAL VOLUME my_gcs_wif_ev
  UPDATE STORAGE_LOCATION = 'gcs-loc-1'
  STORAGE_GCP_SERVICE_ACCOUNT = NULL;

You don’t need to re-create the external volume. The federated identity doesn’t change, so the subject and the trust you configured on the workload identity pool provider remain valid. Before you switch a storage location to direct mode, grant the federated identity the bucket permissions described in Direct mode (in this topic).

Amazon S3 and Azure storage locations have no equivalent: an Amazon S3 location always authenticates by assuming the IAM role named in STORAGE_AWS_ROLE_ARN, and an Azure location always authenticates as the managed identity or app registration named in AZURE_CLIENT_ID.

Add a storage location¶

You can add a WIF storage location to an existing WIF external volume. Each storage location carries its own cloud-side target and its own optional audience.

For Amazon S3:

ALTER EXTERNAL VOLUME my_s3_wif_ev
  ADD STORAGE_LOCATION =
    (
      NAME = 's3-loc-2'
      STORAGE_PROVIDER = 'S3'
      STORAGE_BASE_URL = 's3://my-second-bucket/'
      STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/my-second-wif-role'
    );

For Azure:

ALTER EXTERNAL VOLUME my_azure_wif_ev
  ADD STORAGE_LOCATION =
    (
      NAME = 'azure-loc-2'
      STORAGE_PROVIDER = 'AZURE'
      STORAGE_BASE_URL = 'azure://my-account.blob.core.windows.net/my-second-container/'
      AZURE_TENANT_ID = '<your-azure-ad-tenant-id>'
      AZURE_CLIENT_ID = '<client-id-of-your-second-managed-identity>'
    );

For Google Cloud Storage:

ALTER EXTERNAL VOLUME my_gcs_wif_ev
  ADD STORAGE_LOCATION =
    (
      NAME = 'gcs-loc-2'
      STORAGE_PROVIDER = 'GCS'
      STORAGE_BASE_URL = 'gcs://my-second-bucket/'
      GCP_WORKLOAD_IDENTITY_POOL_PROVIDER = '//iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/my-second-pool/providers/my-second-provider'
      STORAGE_GCP_SERVICE_ACCOUNT = 'second-impersonator@my-project.iam.gserviceaccount.com'
    );

The external volume still has a single subject. Authorize that subject on every cloud-side target it needs to use: each IAM role’s trust policy on Amazon S3, each federated identity credential on Azure, and each service account and workload identity pool on Google Cloud. For more information, see One federated identity per external volume (in this topic).

All storage locations on a WIF external volume must be in the same cloud. For more information, see Limitations and considerations (in this topic).

Rotate the Amazon S3 role or Azure identity¶

STORAGE_AWS_ROLE_ARN, AZURE_TENANT_ID, and AZURE_CLIENT_ID can’t be updated in place, and you can’t remove a storage location while it’s the external volume’s active storage location. For a single-location external volume, that location is always active, so there’s currently no way to rotate its role or identity: create a new external volume with the new value, and move your Apache Iceberg™ tables to it.

If the location isn’t active, for example on a multi-location external volume, remove it and add it back with the new value:

ALTER EXTERNAL VOLUME my_s3_wif_ev REMOVE STORAGE_LOCATION 's3-loc-2';

ALTER EXTERNAL VOLUME my_s3_wif_ev
  ADD STORAGE_LOCATION =
    (
      NAME = 's3-loc-2'
      STORAGE_PROVIDER = 'S3'
      STORAGE_BASE_URL = 's3://my-second-bucket/'
      STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/my-rotated-wif-role'
    );

The same pattern works for Azure, using AZURE_TENANT_ID and AZURE_CLIENT_ID instead of STORAGE_AWS_ROLE_ARN.

The external volume’s subject doesn’t change, so configure the new value’s trust with that same subject: the new role’s trust policy, following Restrict the IAM role to the external volume’s subject (Amazon S3), or the new managed identity’s federated identity credential, following Create the federated identity credential (Azure).

Properties you cannot change¶

• AUTH_TYPE is immutable. You can’t change the authentication model of an external volume after you create it. ALTER EXTERNAL VOLUME ... SET AUTH_TYPE is rejected. To move existing data to WIF, create a new external volume.
• STORAGE_AWS_ROLE_ARN, AZURE_TENANT_ID, and AZURE_CLIENT_ID can’t be altered. Use REMOVE STORAGE_LOCATION and ADD STORAGE_LOCATION instead. For more information, see Rotate the Amazon S3 role or Azure identity (in this topic).
• GCP_WORKLOAD_IDENTITY_POOL_PROVIDER can’t be cleared. Every WIF GCS storage location requires a pool provider, so assigning NULL is rejected. You can replace the value with a different provider resource name.
• UNSET isn’t supported for external volumes. ALTER EXTERNAL VOLUME ... UNSET returns an error for any property. Assign NULL instead.

SQL parameters¶

WIF external volumes use the following CREATE EXTERNAL VOLUME and ALTER EXTERNAL VOLUME parameters.

Parameters for all cloud providers¶

AUTH_TYPE = 'WORKLOAD_IDENTITY_FEDERATION'

Set on the external volume, not on a storage location. Declares that the external volume uses Workload Identity Federation. When you omit AUTH_TYPE, the external volume uses the account-level principal model described in Configure an external volume for Amazon S3, Configure an external volume for Google Cloud Storage, and Configure an external volume for Azure. This property is immutable after creation. For more information, see Properties you cannot change (in this topic).

WORKLOAD_IDENTITY_FEDERATION_AUDIENCE = '<audience>'

Optional, per storage location. The audience claim included in the signed JWT. When unset, the audience defaults to sts.amazonaws.com for an Amazon S3 storage location, api://AzureADTokenExchange for an Azure storage location, or the value of GCP_WORKLOAD_IDENTITY_POOL_PROVIDER for a Google Cloud Storage storage location. Most configurations don’t need to set this value. This property can be cleared with NULL.

Parameters for Amazon S3¶

STORAGE_AWS_ROLE_ARN = '<role_arn>'

Required for each S3 storage location when the external volume sets AUTH_TYPE = 'WORKLOAD_IDENTITY_FEDERATION'. The ARN of the IAM role that Snowflake assumes through sts:AssumeRoleWithWebIdentity. The ARN must name a role rather than an IAM user, and its partition must match the storage location’s partition.

This property can’t be altered in place. For more information, see Rotate the Amazon S3 role or Azure identity (in this topic).

STORAGE_AWS_EXTERNAL_ID isn’t supported on a WIF storage location: OIDC trust replaces the external ID mechanism. Snowflake also doesn’t provision a shared IAM user for a WIF external volume, so DESC EXTERNAL VOLUME returns no STORAGE_AWS_IAM_USER_ARN.

Parameters for Google Cloud Storage¶

GCP_WORKLOAD_IDENTITY_POOL_PROVIDER = '<resource_name>'

Required for each GCS storage location when the external volume sets 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>, where <project_number> is the numeric project number, and <pool_id> and <provider_id> are each 4 to 32 characters of lowercase letters, digits, and hyphens. This property can’t be cleared with NULL, and Snowflake rejects it on a storage location that isn’t a GCS location.

STORAGE_GCP_SERVICE_ACCOUNT = '<service_account_email>'

Optional, per storage location. When set, the storage location operates in service account impersonation mode, and all storage access for that location is performed as this service account. When omitted, the storage location operates in direct mode. For more information, see Access modes (in this topic).

On a standard (non-WIF) GCS external volume, this same property name is output only, and reports the service account that Snowflake provisions for your account. On a WIF external volume it’s an input that names a service account in your own project.

This property can be cleared with NULL.

Parameters for Azure¶

AZURE_TENANT_ID = '<tenant_id>'

Required for each Azure storage location, whether or not the external volume uses WIF. Your Azure AD directory (tenant) ID. Find this value in the Azure portal under Azure Active Directory > Properties. This property can’t be altered. For more information, see Rotate the Amazon S3 role or Azure identity (in this topic).

AZURE_CLIENT_ID = '<client_id>'

Required for each Azure storage location when the external volume sets AUTH_TYPE = 'WORKLOAD_IDENTITY_FEDERATION'. The client ID of the managed identity or app registration that carries the federated identity credential. Set only per storage location: unlike STORAGE_GCP_SERVICE_ACCOUNT, there’s no integration-level fallback for external volumes. This property can’t be altered. For more information, see Rotate the Amazon S3 role or Azure identity (in this topic).

DESCRIBE EXTERNAL VOLUME output¶

DESCRIBE EXTERNAL VOLUME returns the following WIF-specific properties for the external volume:

AUTH_TYPE

The authentication model that the external volume uses.

WORKLOAD_IDENTITY_FEDERATION_ISSUER

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

WORKLOAD_IDENTITY_FEDERATION_SUBJECT

The unique identifier for the external volume. External volume subjects begin with identity_external_volume_. Use this value as the subject when you grant storage access in your cloud provider.

The per-location properties STORAGE_AWS_ROLE_ARN, AZURE_TENANT_ID, AZURE_CLIENT_ID, GCP_WORKLOAD_IDENTITY_POOL_PROVIDER, WORKLOAD_IDENTITY_FEDERATION_AUDIENCE, and STORAGE_GCP_SERVICE_ACCOUNT appear inside the value of the corresponding STORAGE_LOCATION_<n> property rather than as separate rows.

Limitations and considerations¶

This preview supports Workload Identity Federation for external volumes on Amazon S3, Google Cloud Storage, and Azure Blob Storage. The following limitations apply across all three clouds unless noted otherwise.

• You can’t migrate an existing external volume to WIF in place, or back. AUTH_TYPE is immutable. To move existing data to or from WIF, create a new external volume. For more information, see Properties you cannot change (in this topic).
• CREATE OR REPLACE regenerates the subject. Recreating a WIF external volume with CREATE OR REPLACE EXTERNAL VOLUME mints a new federated identity with a new subject. The old subject’s cloud-side trust, such as an IAM role’s trust policy on Amazon S3, a federated identity credential on Azure, or an IAM binding on Google Cloud, no longer matches anything and must be reconfigured for the new subject.
• One federated identity per external volume. The federated identity belongs to the external volume, not to an individual storage location, so the unit of isolation is the external volume. For more information, see One federated identity per external volume (in this topic).
• A single external volume can’t span clouds. All of a WIF external volume’s storage locations must be in the same cloud. To use more than one of Amazon S3, Google Cloud Storage, and Azure Blob Storage, define separate external volumes. This restriction is specific to WIF: a standard (non-WIF) external volume can mix storage providers across locations.
• Cross-cloud and cross-partition configurations aren’t supported. This preview is validated with the Snowflake account and the storage in the same cloud. Other combinations aren’t supported yet.
• Not available in sovereign or federated cloud deployments.
• WIF external volumes aren’t replicated. A WIF external volume named explicitly in a replication group is rejected, and one that would otherwise be included by ALLOWED_EXTERNAL_VOLUMES = ALL is silently excluded. Use a standard external volume for data you need to replicate.
• Commercial AWS regions only. Buckets in the AWS GovCloud (aws-us-gov) and China (aws-cn) partitions aren’t supported for WIF external volumes.
• Microsoft Fabric OneLake isn’t supported. A WIF Azure storage location that points at a Microsoft Fabric OneLake endpoint is rejected, both when you create the external volume and when you add the storage location to an existing one.