認証のためのプログラム アクセス トークンの使用

プログラム アクセス トークンを使用して、以下のSnowflakeエンドポイントを認証できます。

注釈

Snowpark Container Services エンドポイントの認証にはまだプログラムによるアクセストークンは使用できません。

また、 プログラム アクセス トークンをパスワードの代わりとして 使用することもできます。

人間ユーザー（TYPE=PERSON のユーザー）だけでなく、サービスユーザー（TYPE=SERVICE のユーザー）にもプログラム アクセス トークンを生成できます。

前提条件

プログラム アクセス トークンを生成して使用するには、以下の前提条件を満たす必要があります。

ネットワークポリシー要件

デフォルトでは、プログラム・アクセス・トークンを生成または使用するには、ユーザーは1つ以上の ネットワーク・ルール を持つ ネットワークポリシー に従わなければなりません。

  • サービス・ユーザー（ユーザーに対して TYPE=SERVICE）の場合、トークンを生成または使用できるのは、そのユーザーがネットワークポリシーの対象である場合のみです。

    この前提条件は、トークンの使用を特定のアドレスセットまたはネットワーク識別子からのリクエストに制限します。

  • 人間のユーザー（ユーザーに対して TYPE=PERSON）の場合、ユーザーがネットワークポリシーの対象でなくてもトークンを生成できますが、このトークンで認証するには、ユーザーがネットワークポリシーの対象である必要があります。

    ネットワークポリシーの適用を受けない人間のユーザーが認証のためにプログラム アクセス トークンを使用する必要がある場合、ネットワークポリシーの要件を一時的にバイパスすることができますが、これはお勧めしません。 プログラム アクセス トークンの生成 をご参照ください。

    注釈

    ユーザーはネットワークポリシー自体を迂回することはできません。

ネットワークポリシーは、 アカウント内のすべてのユーザーに対して または 特定のユーザーに対して 有効にすることができます。

この要件を変更するには、プログラム アクセス トークンポリシーを指定する 認証ポリシー を作成または変更します。

CREATE AUTHENTICATION POLICY または ALTER AUTHENTICATION POLICY コマンドを実行します。PAT_POLICY 句で、 NETWORK_POLICY_EVALUATION を以下の値のいずれかにセットします。

ENFORCED_REQUIRED （デフォルトの動作）

ユーザーは、プログラムによるアクセストークンを生成および使用するためのネットワークポリシーに従う必要があります。

ユーザーがネットワークポリシーの対象である場合、認証時にネットワークポリシーが適用されます。

ENFORCED_NOT_REQUIRED

ユーザーは、プログラムによるアクセストークンを生成・使用するためにネットワークポリシーに従う必要は ありません。

ユーザーがネットワークポリシーの対象である場合、認証時にネットワークポリシーが適用されます。

NOT_ENFORCED

ユーザーは、プログラムによるアクセストークンを生成・使用するためにネットワークポリシーに従う必要は ありません。

ユーザーがネットワークポリシーの対象である場合、認証時にネットワークポリシーは適用 されません。

たとえば、ネットワークポリシーの要件を削除する認証ポリシーを作成する場合、ユーザーが適用されるネットワークポリシーはすべて適用されます。

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    NETWORK_POLICY_EVALUATION = ENFORCED_NOT_REQUIRED
  );
Copy

次に、 認証ポリシーをアカウントまたはユーザーに適用します。

別の例として、既存の認証ポリシーを変更してネットワークポリシーの要件を削除し、ユーザーが以下に適用されるネットワークポリシーの施行を防ぐこともできます。

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    NETWORK_POLICY_EVALUATION = NOT_ENFORCED
  );
Copy

認証ポリシー権限

ユーザーの認証方法を制限する 認証ポリシー がある場合、そのポリシーの AUTHENTICATION_METHODS リストに 'PROGRAMMATIC_ACCESS_TOKEN' が含まれていなければ、ユーザーはプログラム アクセス トークンを生成および使用できません。

例えば、ある認証ポリシーが、ユーザーの認証に OAuth とパスワード方式を使うことを制限しているとします。

CREATE AUTHENTICATION POLICY my_auth_policy
  ...
  AUTHENTICATION_METHODS = ('OAUTH', 'PASSWORD')
  ...
Copy

AUTHENTICATION_METHODS リストに 'PROGRAMMATIC_ACCESS_TOKEN' を追加しない限り、ユーザーはプログラム アクセス トークンを生成および使用できません。このリストを更新するには、 ALTER AUTHENTICATION POLICY コマンドを使用します。

例:

ALTER AUTHENTICATION POLICY my_auth_policy
  SET AUTHENTICATION_METHODS = ('OAUTH', 'PASSWORD', 'PROGRAMMATIC_ACCESS_TOKEN');
Copy

デフォルトおよび最大有効期限の構成

管理者 (ACCOUNTADMIN ロールを持つユーザー) は、プログラム アクセス トークンの有効期限に影響する以下の設定を構成できます。

最大有効期限のセット

デフォルトでは、トークンの有効期限は365日まで指定できます。これをより短い時間に短縮したい場合は、 認証ポリシー を作成または変更し、最大有効期限を持つプログラム アクセス トークンポリシーを指定します。

CREATE AUTHENTICATION POLICY または ALTER AUTHENTICATION POLICY コマンドを実行します。PAT_POLICY 句で、 MAX_EXPIRY_IN_DAYS を 1 から 365 までの値にセットします。

たとえば、最大日数を100日にセットする認証ポリシーを作成します。

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    MAX_EXPIRY_IN_DAYS=100
  );
Copy

次に、 認証ポリシーをアカウントまたはユーザーに適用します。

別の例として、既存の認証ポリシーを変更し、最大90日間にセットします。

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    MAX_EXPIRY_IN_DAYS=90
  );
Copy

注釈

新しい最大有効期限を超える有効期限のプログラムによるアクセストークンが存在する場合、それらのトークンによる認証は失敗します。

例えば、 my_token という名前のプログラムによるアクセストークンを7日間の有効期限で生成したとします。後ですべてのトークンの最大有効期限を2日に変更すると、トークンの有効期限が新しい最大有効期限を超えるため、 my_token での認証は失敗します。

デフォルトの有効期限のセット

デフォルトでは、プログラム アクセス トークンの有効期限は15日間です。これを変更したい場合は、 認証ポリシー を作成または変更し、デフォルトの有効期限を持つプログラム アクセス トークンポリシーを指定します。

CREATE AUTHENTICATION POLICY または ALTER AUTHENTICATION POLICY コマンドを実行します。PAT_POLICY 句で、 1 から 最大有効期限 までの値を DEFAULT_EXPIRY_IN_DAYS にセットします。

たとえば、デフォルトを 5 日に設定する認証ポリシーを作成します。

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    DEFAULT_EXPIRY_IN_DAYS=5
  );
Copy

次に、 認証ポリシーをアカウントまたはユーザーに適用します。

別の例として、既存の認証ポリシーを変更し、デフォルトを30日にセットする場合について説明します。

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    DEFAULT_EXPIRY_IN_DAYS=30
  );
Copy

プログラム・アクセス・トークンに必要な権限

プログラム アクセス トークンを作成・管理するには、以下の権限を付与されたロールを使用する必要があります。

  • 人間ユーザー（TYPE=PERSON）の場合、 自分自身のための プログラム アクセス トークンを生成、変更、削除、表示するのに、特別な権限は必要ありません。

  • 異なるユーザーまたはサービスユーザー（TYPE=SERVICE）のプログラム アクセス トークンを生成、変更、削除、または表示する場合は、そのユーザーの OWNERSHIP または MODIFY PROGRAMMATIC AUTHENTICATION METHODS 権限を持つロールを使用する必要があります。

    例えば、 my_service_owner_role カスタムロールを持つユーザーに、サービスユーザー my_service_user のプログラム アクセス トークンを生成・管理する権限を付与したいとします。 my_service_user ユーザーの MODIFY PROGRAMMATIC AUTHENTICATION METHODS 権限をロール my_service_owner_role に付与することができます。

    GRANT MODIFY PROGRAMMATIC AUTHENTICATION METHODS ON USER my_service_user
  TO ROLE my_service_owner_role;
    Copy

プログラム アクセス トークンの生成

Snowsight、または SQL コマンドを実行することで、プログラム アクセス トークンを生成できます。

  1. Snowsight にサインインします。

  2. Admin » Users & Roles を選択します。

  3. プログラム アクセス トークンを生成したいユーザーを選択します。

  4. Programmatic access tokens の下で、 Generate new token を選択します。

  5. New programmatic access token ダイアログで、以下の情報を入力します。

    1. Name フィールドに、トークンの名前を入力します。

      名前にはアルファベット、数字、アンダースコアのみを使用できます。名前はアルファベットまたはアンダースコアで始める必要があります。名前の文字は大文字として保存され、解決されます。

    2. Comment フィールドに、トークンに関する説明的なコメントを入力します。

      トークンを作成すると、このコメントが Programmatic access tokens セクションのトークンの基に表示されます。

    3. Expires in から、トークンの有効期限が切れるまでの日数を選択します。

    4. サービスのユーザーを代表してトークンを生成する場合（USER オブジェクトが TYPE=SERVICE の場合）、または実行できる演算子の範囲を制限したい場合は、 One specific role (recommended) を選択し、権限評価とオブジェクト作成に使用するロールを選択します。

      認証にこのトークンを使用すると、作成したオブジェクトはすべてこのロールが所有し、権限評価にはこのロールが使用されます。

      注釈

      ユーザーの DEFAULT_SECONDARY_ROLES が（'ALL'）に設定されていても、セカンダリロールは使用されません。

      代わりに Any of my roles を選択した場合、プライマリロールが所有するオブジェクトを作成し、権限が アクティブロール に対して評価されます。

    5. Generate を選択します。

  6. 生成されたプログラム アクセス トークンをコピーまたはダウンロードし、トークンを認証情報として使用できるようにします。

    注釈

    このメッセージボックスを閉じた後は、このトークンをコピーしたりダウンロードしたりすることはできません。

新しいトークンは Programmatic access tokens セクションにリストされています。

前述したように、プログラム・アクセス・トークンを使用するには、トークン（）に関連付けら れているユーザーがネットワークポリシー（）の対象である必要があります。ただし、この要件を変更する認証ポリシーをセットアップする場合はこの限りではありません。

ネットワークポリシーの適用を受けない人間のユーザーが認証のためにプログラム アクセス トークンを使用する必要がある場合、 その他のオプション » Bypass requirement for network policy を選択することで、ネットワークポリシーの要件を一時的に回避することができます。

注釈

Bypass requirement for network policy は、ユーザーがネットワークポリシー自体をバイパスすることを許可しません。

プログラム アクセス トークンを作成した後、有効期限を変更することはできません。トークンを取り消し、新しい有効期限で新しいトークンを生成する必要があります。

プログラム アクセス トークンにロールを指定し、そのロールがユーザーから取り消された場合、プログラム アクセス トークンはシステム PUBLIC ロールを使用します。

プログラム アクセス トークンの使用

以下のセクションでは、プログラム アクセス トークンをパスワードとして使用し、Snowflakeエンドポイントへの認証情報として使用する方法について説明します。

プログラム アクセス トークンのパスワードとしての使用

プログラム アクセス トークンをパスワードとして認証接続するには、ドライバーのセットまたはSnowflakeへの接続コールで、パスワードの値にトークンを指定します。

たとえば、Snowflake Connector for Python を使用している場合、 snowflake.connector.connect メソッドを呼び出すときに、 password 引数としてプログラム アクセス トークンを指定できます。

conn = snowflake.connector.connect(
    user=USER,
    password=<programmatic_access_token>,
    account=ACCOUNT,
    warehouse=WAREHOUSE,
    database=DATABASE,
    schema=SCHEMA
)
Copy

同様に、サードパーティのアプリケーション（Tableau や PowerBI など）でも、パスワードの代わりにプログラム アクセス トークンを使用できます。パスワードのフィールドにプログラム アクセス トークンを貼り付けます。

注釈

デフォルトでは、プログラマティック・アクセストークン を使用するには、アカウント 内のユーザーまたはすべてのユーザーに対してネットワークポリシーを有効にする必要があります。サードパーティアプリケーションでプログラム アクセス トークンを使用するには、サードパーティアプリケーションの IP アドレス範囲からのリクエストを許可するネットワークポリシーを作成する必要があります。

エンドポイントの認証にプログラム アクセス トークンを使用します。

プログラムアクセストークンで認証するには、リクエストに以下の HTTP ヘッダーをセットします。

  • Authorization: Bearer token_secret

  • X-Snowflake-Authorization-Token-Type: PROGRAMMATIC_ACCESS_TOKEN （オプション）

例えば、 cURL を使用して、 Snowflake REST API エンドポイントにリクエストを送信する場合：

curl --location 'https://myorganization-myaccount.snowflakecomputing.com/api/v2/databases' \
  --header "Authorization: Bearer <token_secret>"
Copy

別の例として、 cURL を使用して Snowflake SQL API エンドポイントにリクエストを送信する場合：

curl -si -X POST https://myorganization-myaccount.snowflakecomputing.com/api/v2/statements \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer <token_secret>" \
  --data '{"statement": "select 1"}'
Copy

リクエストが PAT_INVALID エラーで失敗した場合、エラーは以下のいずれかの理由で発生した可能性があります。

  • プログラムアクセストークンに関連付けられたユーザーが見つかりませんでした。

  • 検証に失敗しました。

  • プログラムアクセストークンに関連付けられたロールが見つかりませんでした。

  • ユーザーは指定されたプログラムアクセストークンに関連付けられていません。

プログラム アクセス トークンの管理

以下のセクションでは、プログラム・アクセス・トークンの使用、変更、リスト、ローテーション、取り消しについて説明します。

注釈

認証にプログラム アクセス トークンを使用したセッションでは、プログラム アクセス トークンの変更、名前の変更、ローテーション、取り消しはできません。

プログラム・アクセス・トークンのリスト

Snowsight または SQL コマンドを実行することで、ユーザーのプログラム アクセス トークンをリストすることができます。

  1. Snowsight にサインインします。

  2. Admin » Users & Roles を選択します。

  3. プログラム アクセス トークンを所有するユーザーを選択します。

    ユーザーのプログラム アクセス トークンは、 Programmatic access tokens にリストされています。

注釈

7日が経過すると、期限切れのプログラム・アクセス・トークンは削除され、 Snowsight にも SHOW USER PROGRAMMATIC ACCESS TOKENS コマンドの出力にも表示されなくなります。

プログラム アクセス トークンの名前の変更

プログラム アクセス トークンの名前は、 Snowsight または SQL コマンドを実行することで変更できます。

  1. Snowsight にサインインします。

  2. Admin » Users & Roles を選択します。

  3. プログラム アクセス トークンに関連付けられたユーザーを選択します。

  4. Programmatic access tokens の基になるプログラム アクセス トークンを探し、 その他のオプション » Edit を選択します。

  5. Name フィールドで、トークンの名前を変更し、 Save を選択します。

プログラム アクセス トークンのローテーション

Snowsight、または SQL コマンドを実行することで、プログラム アクセス トークンをローテーションすることができます。

トークンをローテーションすると、同じ名前で有効期限が延長された新しいトークンシークレットが返されます。トークンをローテーションすると、既存のトークンのシークレットも失効します。新しいトークンをSnowflakeの認証に使用します。

  1. Snowsight にサインインします。

  2. Admin » Users & Roles を選択します。

  3. プログラム アクセス トークンに関連付けられたユーザーを選択します。

  4. Programmatic access tokens の基になるプログラム アクセス トークンを探し、 その他のオプション » Rotate を選択します。

  5. 以前のトークンのシークレットをすぐに失効させたい場合は、 Expire current secret immediately を選択します。

  6. Rotate token を選択します。

  7. 生成されたプログラム アクセス トークンをコピーまたはダウンロードし、トークンを認証情報として使用できるようにします。

    注釈

    このメッセージボックスを閉じた後は、このトークンをコピーしたりダウンロードしたりすることはできません。

プログラム アクセス トークンの取り消し

プログラム アクセス トークンを取り消すには、 Snowsight または SQL コマンドを実行します。

  1. Snowsight にサインインします。

  2. Admin » Users & Roles を選択します。

  3. プログラム アクセス トークンに関連付けられたユーザーを選択します。

  4. Programmatic access tokens の基になるプログラム アクセス トークンを探し、 その他のオプション » Delete を選択します。

無効化されたプログラム アクセス トークンの再有効化

ユーザーのログインアクセスを無効にする場合 または Snowflake がユーザーのログインをロックアウトする場合、そのユーザーのプログラム アクセス トークンは自動的に無効になります。

注釈

プログラマティック・アクセストークンは、ユーザーが 一時的にロックアウトされた場合 (例えば、認証に 5 回以上失敗した場合など)、無効化され ません。

SHOW USER PROGRAMMATIC ACCESS TOKENS コマンドを実行すると、 status 列の値は、そのユーザーに関連付けられているトークンの DISABLED になります。

SHOW USER PROGRAMMATIC ACCESS TOKENS FOR USER example_user;
Copy
+---------------+--------------+------------------+-------------------------------+----------+---------+-------------------------------+--------------+-------------------------------------------+------------+
| name          | user_name    | role_restriction | expires_at                    | status   | comment | created_on                    | created_by   | mins_to_bypass_network_policy_requirement | rotated_to |
|---------------+--------------+------------------+-------------------------------+----------+---------+-------------------------------+--------------+-------------------------------------------+------------|
| EXAMPLE_TOKEN | EXAMPLE_USER | MY_ROLE          | 2025-04-28 12:13:46.431 -0700 | DISABLED | NULL    | 2025-04-13 12:13:46.431 -0700 | EXAMPLE_USER | NULL                                      | NULL       |
+---------------+--------------+------------------+-------------------------------+----------+---------+-------------------------------+--------------+-------------------------------------------+------------+

後でそのユーザーのログインアクセスを有効にした場合、または Snowflake がそのユーザーのログインアクセスをロック解除した場合でも、そのユーザーのプログラム アクセス トークンは無効のままです。トークンを再び有効にするには、 ALTER USER ... MODIFY PROGRAMMATIC ACCESS TOKEN (PAT) コマンドを実行し、 DISABLED を FALSE にセットします。例:

ALTER USER example_user MODIFY PROGRAMMATIC ACCESS TOKEN example_token SET DISABLED = FALSE;
Copy

シークレットからのプログラム アクセス トークンの情報取得

プログラム アクセス トークンに関する情報が必要な場合、そのトークンのシークレットが与えられたら、 SYSTEM$DECODE_PAT 関数を呼び出します。シークレットが漏洩し、トークンに関連付けられたユーザー、トークンの名前、トークンの状態を知りたい場合にこの関数を使用できます。

例:

SELECT SYSTEM$DECODE_PAT('abC...Y5Z');
Copy
+------------------------------------------------------------------------+
| SYSTEM$DECODE_PAT('☺☺☺...☺☺☺')                                         |
|------------------------------------------------------------------------|
| {"STATE":"ACTIVE","PAT_NAME":"MY_EXAMPLE_TOKEN","USER_NAME":"MY_USER"} |
+------------------------------------------------------------------------+

ベストプラクティス

  • プログラム アクセス トークンを保存する必要がある場合は、（パスワードやシークレットマネージャーを使用するなどして）安全に保存してください。

  • コード内でプログラム アクセス トークンを公開することは避けてください。

  • トークンを生成する 際に、トークンの使用を特定のロールに制限します。

  • プログラム アクセス トークンを定期的に見直し、ローテーションします。ユーザーは トークンを生成する 際に有効期限をセットでき、管理者は すべてのトークンの最大有効期限を短縮できます。トークンのローテーションを奨励するためです。

制限事項

  • プログラム アクセス トークンをロールに制限できるのは、トークンを生成するときだけです。トークンを生成した後は、トークンが制限するロールを変更したり削除したりすることはできません。

  • プログラム アクセス トークンの有効期限は、トークンの生成時にのみセットできます。トークンを生成した後、有効期限を変更することはできません。 プログラム アクセス トークンを取り消し、有効期限の異なる新しいトークンを生成することができます。

  • プログラム アクセス トークンのシークレットを表示できるのは、トークンを作成したときだけです。プログラム アクセス トークンを作成した後は、トークンに関する情報のみを表示することができ、トークンのシークレットを表示することはできません。

  • 管理者は、指定されたユーザーのすべてのプログラム アクセス トークンをリストできますが、アカウントのすべてのプログラム アクセス トークンをリストすることはできません。

  • プログラム アクセス トークンを取り消した後、それを回復することはできません。

言語: 日本語