LoginSignup
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@bgcanary

SnowflakeへWorkload Identity Federation(OIDC)で認証する

Last updated at Posted at 2025-08-21

はじめに

2025年8月14日にSnowflakeに新しい認証方式「Workload Identity Federation」が追加されました。この機能により、OIDCで長期的な認証情報（パスワードやAPIキー）を管理することなく、Snowflakeに安全に接続できるようになりました。

本記事では、AWS等に依らない一般的なOIDCの設定を行ったWorkload Identity Federationで認証してSnowflakeオブジェクトを作成する方法を詳しく解説します。
本記事で使用するファイルは以下のGitHubリポジトリに配置しています。

記事を書いた理由ですが、Snowflakeのドキュメントを読んでも、OIDCによる一般的な設定方法が分かりずらかったので、GitHub ActionsとSnowflake CLIを題材に検証しました。

本当はSnowflake CLIの代わりにTerraformを使いたかったのですが、サポートされるのは2025年の終わりのようです。

Workflow Identity Federation will be supported before the end of 2025.

なお、Snowflake CLIは2025年8月21日時点でWorkload Identity Federationを未サポートですが、後述のパラメータ設定で利用できるようになります。
OIDCの設定方法が主となる記事のため、Snowflake CLIを利用していますが、実運用時は未サポートである点に注意してください。

2025年8月26日 追記

Snowflake CLI は v3.11.0 でWorkload Identity Federationをサポートしました。
GitHub Actions上のOIDCトークンを読み込む処理も組み込まれているようです。

Added snow auth OIDC command group for managing workload identity federation authentication:
snow auth oidc read-token - Reads and displays OIDC tokens from CI/CD environments
Supports GitHub Actions OIDC provider for passwordless authentication in CI/CD pipelines

Workload Identity Federationとは

Workload Identity Federationは、アプリケーション、サービス、コンテナなどのワークロードが、クラウドプロバイダーのネイティブIDシステム（AWS IAM、Microsoft Entra ID、Google Cloudサービスアカウントなど）を使用してSnowflakeに認証できるサービス間認証方式です。

主なメリット

  • セキュリティ向上: 長期的な認証情報の管理が不要
  • 運用コスト削減: 既存のIDプロバイダーを活用

OpenID Connect (OIDC) の仕組み

GitHub ActionsからSnowflakeへのWorkload Identity Federationは、OpenID Connect (OIDC) プロトコルを使用しています。OIDCにより、長期的な認証情報を保存することなく、安全にクラウドサービス間の認証が可能になります。

OIDC認証フローの概要

OIDCの主要コンポーネント

1. JWT (JSON Web Token)

GitHub Actionsが生成するデジタル署名付きトークンで、以下の重要なClaim（情報）を含みます：

  • iss (Issuer): トークン発行者

    • 値: https://token.actions.githubusercontent.com
    • 用途: Snowflakeがトークンの発行元を検証

  • sub (Subject): 認証されたユーザを一意に識別する識別子

    • 値: repo:owner/repository:ref:refs/heads/branch
    • 例: repo:bgcanary/snowflake-demo:ref:refs/heads/main
    • 用途: 特定のリポジトリ・ブランチのみアクセス許可

  • aud (Audience): トークンの受信者

    • 値: https://github.com/owner
    • 例: https://github.com/bgcanary
    • 用途: 特定のGitHub組織のみアクセス許可

2. Snowflake Workload Identity設定

SnowflakeのサービスユーザーでOIDC認証を設定する際の各パラメータ：

CREATE USER xxx
WORKLOAD_IDENTITY = (
    TYPE = OIDC                    -- OIDC認証を使用
    ISSUER = 'issuer_url'          -- JWTのissクレームと一致必須
    SUBJECT = 'subject_pattern'    -- JWTのsubクレームと一致必須  
    OIDC_AUDIENCE_LIST = ('aud')   -- JWTのaudクレームと一致必須
);

各パラメータの役割:

  • TYPE = OIDC: Workload Identity FederationでOIDCプロバイダーを使用することを指定

  • ISSUER: 信頼するOIDCプロバイダーのURL

    • GitHub Actions固定値: https://token.actions.githubusercontent.com
    • Snowflakeはこの発行者からのトークンのみ受け入れ

  • SUBJECT: 認証を許可するワークロードの識別子

    • パターン: repo:組織名/リポジトリ名:ref:refs/heads/ブランチ名
    • セキュリティ: 特定のリポジトリ・ブランチのみアクセス制限

  • OIDC_AUDIENCE_LIST: トークンの対象者リスト

    • GitHub組織URL: https://github.com/組織名
    • 複数指定可能: ('aud1', 'aud2')

事前準備

Snowflake

  • Snowflakeアカウント
  • GitHub Actions用のユーザー作成権限、ロール（SYSADMIN等）の付与権限を持ったロール（SECURITYADMIN等）

GitHub

  • GitHubアカウント
  • ローカルPC等のgit設定（任意）
  • 各ファイルのGit Clone（任意）
    git clone git@github.com:bgcanary/snowflake-wif-demo.git

設定手順

1. GitHub ActionsのOIDCトークンSubject値を確認

まず、GitHub Actionsで使用されるOIDCトークンのSubject値を確認します。この値はGitHubリポジトリとブランチの組み合わせで決まります。

Subject値の形式は以下のようになります：

  • 特定のブランチ: repo:OWNER/REPOSITORY:ref:refs/heads/BRANCH_NAME
  • mainブランチの例: repo:your-org/your-repo:ref:refs/heads/main
  • developブランチの例: repo:your-org/your-repo:ref:refs/heads/develop

2. Snowflakeでサービスユーザーを作成

次に、確認したSubject値を使用してWorkload Identity Federationを使用するサービスユーザーをSnowflakeで作成します。

-- セキュリティ管理者ロールに切り替え
USE ROLE SECURITYADMIN;

-- GitHub Actions用のサービスユーザーを作成
CREATE USER github_actions_user
WORKLOAD_IDENTITY = (
    TYPE = OIDC
    ISSUER = 'https://token.actions.githubusercontent.com'
    SUBJECT = 'repo:your-org/your-repo:ref:refs/heads/main'
    OIDC_AUDIENCE_LIST = ('https://github.com/your-org')
)
TYPE = SERVICE
DEFAULT_ROLE = SYSADMIN;

-- GitHub ActionsからSnowflakeを操作するための権限を付与
GRANT ROLE SYSADMIN TO USER github_actions_user;

重要なポイント:

  • ISSUER: GitHub ActionsのOIDCプロバイダーURL（固定値）
  • SUBJECT: リポジトリとブランチの組み合わせに変更
    • 形式: repo:組織名/リポジトリ名:ref:refs/heads/ブランチ名
    • 例: repo:mycompany/myproject:ref:refs/heads/main
  • OIDC_AUDIENCE_LIST: GitHub組織URLに変更
    • 形式: https://github.com/組織名
    • 例: https://github.com/mycompany

2. GitHub ActionsワークフローYAMLの作成

.github/workflows/snowflake-deploy.yml を作成します：

name: Snowflake Deployment with Workload Identity

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

permissions:
  id-token: write  # OIDC token取得に必要
  contents: read   # リポジトリコンテンツ読み取りに必要

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
    
    - name: Setup Snowflake CLI
      uses: snowflakedb/snowflake-cli-action@v1.5
    
    - name: Install OIDC Client from Core Package
      run: npm install @actions/core@1.6.0 @actions/http-client
    
    - name: Get OIDC Token
      uses: actions/github-script@v7
      id: get-token
      with:
        script: |
          const coredemo = require('@actions/core')
          let id_token = await coredemo.getIDToken('https://github.com/${{ github.repository_owner }}')
          coredemo.setOutput('id_token', id_token)
    
    - name: Deploy Snowflake resources
      env:
        SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
        SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
        SNOWFLAKE_AUTHENTICATOR: WORKLOAD_IDENTITY
        SNOWFLAKE_WORKLOAD_IDENTITY_PROVIDER: OIDC
        SNOWFLAKE_TOKEN: ${{ steps.get-token.outputs.id_token }}
        SF_ENABLE_EXPERIMENTAL_AUTHENTICATION: true
      run: |
        # データベースの作成
        snow sql -f sql/01_create_database.sql --temporary-connection
        
        # スキーマの作成
        snow sql -f sql/02_create_schema.sql --temporary-connection

対応するSQLファイルを sql/ ディレクトリに作成します：

sql/01_create_database.sql

CREATE OR ALTER DATABASE DEMO_DB;

sql/02_create_schema.sql

CREATE OR ALTER SCHEMA DEMO_DB.DEMO_SCHEMA;

実際は任意のSQLを実行可能です。

3. GitHub Secretsの設定

GitHub リポジトリの Settings > Secrets and variables > Actions の「Secrets」タブで以下の変数を追加：

  • SNOWFLAKE_ACCOUNT: SnowflakeアカウントID（例：abc12345.us-west-2）
  • SNOWFLAKE_USER: サービスユーザー名（例：github_actions_user）

4. GitHub リポジトリへリソースをPushし、GitHub Actionsを実行

実行結果

image.png

5. Snowflake側でリソースの作成状況を確認

Query History を確認すると、クエリが実行完了できている。

image.png

トラブルシューティング

エラーと対処法

1. Snowflake CLIの接続設定エラー 

Connection default is not configured

原因: 環境変数で接続しようとしたが、フラグが無いためconfigファイルを参照しようとしている。

解決策: --temporary-connectionフラグを追加

# 修正前
snow sql -f sql/01_create_database.sql

# 修正後
snow sql -f sql/01_create_database.sql --temporary-connection

2. Snowflake CLIでWorkload Identity Federationを使おうとした際のエラー 

Please set the 'SF_ENABLE_EXPERIMENTAL_AUTHENTICATION' environment variable true to use the 'WORKLOAD_IDENTITY' authenticator

原因: Snowflake CLIが利用するPythonのバージョンが古く、Workload Identity Federationが試験用の機能として扱われている

Snowflake CLIは2025年8月21日時点でWorkload Identity Federationを未サポート。

解決策: 環境変数を追加

env:
  SF_ENABLE_EXPERIMENTAL_AUTHENTICATION: true

3. Workload Identity認証情報エラー 

No workload identity credential was found for 'auto-detect'

原因: GitHub ActionsのOIDCトークンが正しく設定されていない

解決策: GitHub ActionsのOIDCトークン取得手順を追加

    - name: Install OIDC Client from Core Package
      run: npm install @actions/core@1.6.0 @actions/http-client
    
    - name: Get OIDC Token
      uses: actions/github-script@v7
      id: get-token
      with:
        script: |
          const coredemo = require('@actions/core')
          let id_token = await coredemo.getIDToken('https://github.com/${{ github.repository_owner }}')
          coredemo.setOutput('id_token', id_token)

Snowflake CLIがOIDC Token (id_token) を読み込めるよう、 SNOWFLAKE_TOKEN 環境変数に値を設定する。

    - name: Deploy Snowflake resources
      env:
        SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
        SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
        SNOWFLAKE_AUTHENTICATOR: WORKLOAD_IDENTITY
        SNOWFLAKE_WORKLOAD_IDENTITY_PROVIDER: OIDC
        SNOWFLAKE_TOKEN: ${{ steps.get-token.outputs.id_token }} # ← OIDCトークン用のパラメータを環境変数に設定
        SF_ENABLE_EXPERIMENTAL_AUTHENTICATION: true
      run: |
        # データベースの作成
        snow sql -f sql/01_create_database.sql --temporary-connection

4. JWT audience claim無効エラー 

JWT contains an invalid audience ("aud") claim

原因: Snowflakeサービスユーザーにaudience値が未設定

解決策: SnowflakeサービスユーザーのOIDC_AUDIENCE_LISTに値を設定

-- 修正前
OIDC_AUDIENCE_LIST = ('') -- 未設定

-- 修正後（実際のaud値を使用）
OIDC_AUDIENCE_LIST = ('https://github.com/your-org')

5. JWT subject/issuer認識エラー 

Either the JWT contained an unrecognized subject or issuer claim, or the JWTs signature could not be verified

原因: JWTトークンのsubjectまたはissuer, audience クレームがSnowflakeの設定と不一致

解決策:

  1. JWTトークンクレームをデバッグ出力で確認

    # デバッグ用コード
echo $IDTOKEN | cut -d'.' -f2 | base64 -d | jq .

    出力例

    {
 "actor": "bgcanary",
 "actor_id": "89304360",
 "aud": "https://github.com/bgcanary",
 "base_ref": "",
 "event_name": "push",
 "exp": 1755552448,
 "head_ref": "",
 "iat": 1755530848,
 "iss": "https://token.actions.githubusercontent.com",
 "job_workflow_ref": "bgcanary/snowflake-demo/.github/workflows/hoge.yml@refs/heads/main",
 "job_workflow_sha": "75a3e64e76a6571ed45cefab3a7b48c929ac899e",
 "jti": "248cd4c5-fe97-4f87-8475-e152164079b0",
 "nbf": 1755530548,
 "ref": "refs/heads/main",
 "ref_protected": "false",
 "ref_type": "branch",
 "repository": "bgcanary/snowflake-demo",
 "repository_id": "1040116597",
 "repository_owner": "bgcanary",
 "repository_owner_id": "89304360",
 "repository_visibility": "public",
 "run_attempt": "1",
 "run_id": "17045018715",
 "run_number": "9",
 "runner_environment": "github-hosted",
 "sha": "75a3e64e76a6571ed45cefab3a7b48c929ac899e",
 "sub": "repo:bgcanary/snowflake-demo:ref:refs/heads/main",
 "workflow": "Snowflake Deployment with Workload Identity",
 "workflow_ref": "bgcanary/snowflake-demo/.github/workflows/hoge.yml@refs/heads/main",
 "workflow_sha": "75a3e64e76a6571ed45cefab3a7b48c929ac899e"
}

  2. 実際のクレーム値でSnowflakeサービスユーザーを再作成

    CREATE USER github_actions_user
WORKLOAD_IDENTITY = (
    TYPE = OIDC
    ISSUER = 'https://token.actions.githubusercontent.com'  -- iss値
    SUBJECT = 'repo:your-org/your-repo:ref:refs/heads/main'  -- sub値
    OIDC_AUDIENCE_LIST = ('https://github.com/your-org')  -- aud値
)
TYPE = SERVICE
DEFAULT_ROLE = SYSADMIN;

まとめ

Workload Identity Federationを使用することで、GitHub ActionsからSnowflakeへの認証がより安全かつ管理しやすくなりました。

参考リンク

1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?