外部 OAuth 用Microsoft Azure AD の構成

このトピックでは、Snowflakeデータへの安全でプログラム的なアクセスを促進するために、Snowflakeを OAuth リソース、またAzure AD を外部 OAuth 認証サーバーとして構成する方法について説明します。

このトピックの内容:

構成手順

次の4つのステップは、Azure AD OAuth 認証サーバー、 OAuth クライアント、スコープ、および必要なメタデータに関連する構成が、環境に含まれていないことを前提としています。

ステップ1~3の情報を使用して、Snowflakeのセキュリティ統合を作成します。

既にAzure AD 認証サーバーとクライアントが構成されている場合、以下のすべてのステップを完了する必要はありません。むしろ、次の3つのステップをざっと見て、必要な情報の取得、スコープの作成、1つ以上のポリシーへのスコープの割り当て、メタデータへのアクセスができることを確認してください。

Azure AD OAuth 認証サーバーとクライアントが構成されていない場合は、次の4つのステップすべてを完了します。

重要

このトピックのこうしたステップは、外部 OAuth 用にAzure AD を構成する方法の 代表的な例 です。

セキュリティ統合 (このトピック内)に必要な情報を取得できる場合は、Azure AD を任意の状態に構成し、任意の OAuth フローを使用できます。

次のステップは、Snowflakeでセキュリティ統合を作成するために必要な情報を取得するためのガイドです。

ステップ1~3は、 OAuth 2.0および認証に関するAzure AD ドキュメントから派生しています。Microsoftによる用語の定義、ユーザーインターフェイス、 OAuth 2.0および認証に関連するオプションの詳細については、次のAzure AD ガイドを参照してください。

Azure AD で OAuth フローを決定する

Azure AD は、 OAuth クライアントがアクセストークンを取得できる2つの異なる OAuth フローをサポートしています。

  1. 認証サーバーは、ユーザーに代わって OAuth クライアントにアクセストークンを付与できます。

  2. 認証サーバーは、 OAuth クライアントに OAuth クライアント自体のアクセストークンを付与できます。

最初のフローでは、アクセストークンのIDはユーザーを参照します。2番目のフローでは、アクセストークンのIDは OAuth クライアントを参照します。

Microsoft Azure AD では、これら2つの OAuth フローのそれぞれに対して同じロール形式を使用することはできません。使用するロール形式は、使用中の OAuth フローによって異なります。使用する OAuth フローを決定した後、

Azure AD で OAuth リソースを構成する

  1. Microsoft Azureポータル に移動して認証します。

  2. Azure Active Directoryに移動します。

  3. App Registrations をクリックします。

  4. New Registration をクリックします。

  5. Snowflake OAuth Resource、または Name と類似の値を入力します。

  6. Supported account typesSingle Tenant に設定されていることを確認します。

  7. Register をクリックします。

  8. Expose an API をクリックします。

  9. Application ID URI の横にある Set リンクをクリックして、 Application ID URI を設定します。

    重要

    Application ID URI は、 https://your.company.com/4d2a8c2b-a5f4-4b86-93ca-294185f45f2e のように、組織のディレクトリ内で一意である必要があります。この値は、後続の構成ステップで <SNOWFLAKE_APPLICATION_ID_URI> と呼ばれます。

    アプリケーション ID URI の入手については、Microsoft Azure AD の内部管理者にお問い合わせください。

    アプリケーション ID URI が使用されていない場合、Snowflakeアカウント URL (つまり、 <アカウント識別子>.snowflakecomputing.com)を使用して、オーディエンスとのセキュリティ統合を作成する必要があります。詳細については、次をご参照ください。

  10. プログラムクライアントがユーザーの代わりに動作する OAuth フローの OAuth スコープとしてSnowflakeロールを追加するには、 Add a scope をクリックしてSnowflakeロールを表すスコープを追加します。

    • Snowflakeロールの名前に session:scope: プレフィックスを付けて、スコープに入力します。たとえば、Snowflake Analystロールの場合、 session:scope:analyst と入力します。

    • 同意する人を選択します。

    • スコープに display name を入力します(例:アカウント管理者)。

    • スコープに description を入力します(例:Snowflakeアカウントの管理可能)。

    • Add Scope をクリックします。

  11. プログラムクライアントが、自身のアクセストークンをリクエストする OAuth フローのロールとしてSnowflakeロールを追加するには、

    • Manifest をクリックします。

    • appRoles 要素を見つけます。

    • 次の設定で App Role を入力します。

      設定

      説明

      allowedMemberTypes

      アプリケーション

      説明

      ロールの説明。

      displayName

      ユーザーに表示するわかりやすい名前。

      ID

      一意の ID。必要に応じて、 PowerShell の [System.Guid]::NewGuid() 関数を使用して一意の ID を生成できます。

      isEnabled

      true に設定。

      lang

      言語。 null に設定。

      原点

      Application に設定。

      プレフィックスが session:role: のSnowflakeロールの名前に設定します。 . アナリストの役割には、 session:role:analyst を入力します。

      App Role は次のように現れます。

      "appRoles":[
          {
              "allowedMemberTypes": [ "Application" ],
              "description": "Account Administrator.",
              "displayName": "Account Admin",
              "id": "3ea51f40-2ad7-4e79-aa18-12c45156dc6a",
              "isEnabled": true,
              "lang": null,
              "origin": "Application",
              "value": "session:role:analyst"
          }
      ]
      
      Copy
  12. Save をクリックします。

Azure AD で OAuth クライアントを作成する

  1. Microsoft Azureポータル に移動して認証します。

  2. Azure Active Directoryに移動します。

  3. App Registrations をクリックします。

  4. New Registration をクリックします。

  5. Snowflake OAuth Client などのクライアントの名前を入力します。

  6. サポートされているアカウントタイプがシングルテナントに設定されていることを確認します。

  7. Register をクリックします。

  8. Overview セクションで、 Application (client) ID フィールドから ClientID をコピーします。これは、次のステップで <OAUTH_CLIENT_ID> と呼ばれています。

  9. Certificates & secretsNew client secret の順にクリックします。

  10. シークレットの説明を追加します。

  11. never expire を選択します。テストの目的で、無期限のシークレットを選択します。

  12. Add をクリックします。シークレットをコピーします。これは、次のステップで <OAUTH_CLIENT_SECRET> と呼ばれています。

  13. ユーザーに代わってアクセストークンをリクエストするプログラムクライアントでは、次のようにアプリケーションの委任アクセス許可を構成します。

    • API Permissions をクリックします。

    • Add Permission をクリックします。

    • My APIs をクリックします。

    • Azure AD で OAuth リソースを構成する で作成した Snowflake OAuth Resource をクリックします。

    • Delegated Permissions ボックスをクリックします。

    • このクライアントに付与したいアプリケーションで定義されたスコープに関連する許可を確認します。

    • Add Permissions をクリックします。

    • Grant Admin Consent ボタンをクリックして、クライアントにアクセス許可を付与します。テストのために、アクセス許可はこのように構成されていることに注意してください。ただし、運用環境では、この方法でアクセス許可を付与することはお勧めできません。

    • Yes をクリックします。

  14. 自分用にアクセストークンをリクエストするプログラムクライアントの場合、次のように API permissions for Applications を構成します。

    • API Permissions をクリックします。

    • Add Permission をクリックします。

    • My APIs をクリックします。

    • Azure AD で OAuth リソースを構成する で作成した Snowflake OAuth Resource をクリックします。

    • Application Permissions をクリックします。

    • このクライアントに付与するアプリケーションの Manifest で、手動により定義されたロールに関連する Permission を確認します。

    • Add Permissions をクリックします。

    • Grant Admin Consent ボタンをクリックして、クライアントにアクセス許可を付与します。テスト目的のため、アクセス許可はこのように構成されていることに注意してください。ただし、運用環境では、この方法でアクセス許可を付与することはお勧めできません。

    • Yes をクリックします。

Snowflake用の AD 情報を収集する

  1. Microsoft Azureポータル に移動して認証します。

  2. Azure Active Directoryに移動します。

  3. App Registrations をクリックします。

  4. Azure AD で OAuth リソースを構成する で作成した Snowflake OAuth Resource をクリックします。

  5. Overview インターフェイスで Endpoints をクリックします。

  6. 右側で、 OAuth 2.0 token endpoint (v2) をコピーし、 OpenID Connect metadata および Federation Connect metadata の URLs を書き留めます。

    • 次の構成ステップでは、 OAuth 2.0 token endpoint (v2)<AZURE_AD_OAUTH_TOKEN_ENDPOINT> として認識されます。エンドポイントは、 https://login.microsoftonline.com/90288a9b-97df-4c6d-b025-95713f21cef9/oauth2/v2.0/token に類似している必要があります。

    • OpenID Connect metadata の場合は、新しいブラウザーウィンドウで開きます。

      • "jwks_uri" パラメーターを見つけて、その値をコピーします。

      • このパラメーター値は、以下の構成ステップで <AZURE_AD_JWS_KEY_ENDPOINT> として認識されます。エンドポイントは、 https://login.microsoftonline.com/90288a9b-97df-4c6d-b025-95713f21cef9/discovery/v2.0/keys に類似している必要があります。

    • Federation metadata document の場合は、新しいブラウザーウィンドウで URL を開きます。

      • XML Root Element"entityID" パラメーターを見つけて、その値をコピーします。

      • このパラメーター値は、以下の構成ステップで <AZURE_AD_ISSUER> として認識されます。 entityID の値は、 https://sts.windows.net/90288a9b-97df-4c6d-b025-95713f21cef9/ に類似している必要があります。

Snowflakeでセキュリティ統合を作成する

このステップには、SnowflakeがMicrosoft Azure AD と安全に通信し、Azure AD からのトークンを検証し、 OAuth トークンに関連付けされたユーザーロールに基づいて、適切なSnowflakeデータアクセスをユーザーに提供することを確実にするためのセキュリティ統合をSnowflakeに作成することが含まれます。

ユースケースと構成のニーズに最適なセキュリティ統合を選択します。統合が前述の構成のみに基づいている場合は、最初のセキュリティ統合を使用します。詳細については、 CREATE SECURITY INTEGRATION をご参照ください。

重要

Microsoft Power BI のセキュリティ統合を作成しようとしている場合は、 Power BI SSO からSnowflakeへ のセットアップ手順に従ってください。

この SQL コマンドを実行できるのは、アカウント管理者(つまり、 ACCOUNTADMIN ロールを持つユーザー)またはグローバル CREATE INTEGRATION 権限を持つロールのみです。

セキュリティ統合パラメータの値は大文字と小文字が区別され、セキュリティ統合に入力する値は環境内のこれらの値と一致する必要があります。大文字と小文字が一致しない場合、アクセストークンが検証されず、認証試行が失敗する可能性があります。

すべての値が完全に一致することを確認します。たとえば、発行者の値がバックスラッシュで終了せず、セキュリティ統合が URL の最後にバックスラッシュ文字で作成された場合、エラーメッセージが表示されます。その場合は、 DROP INTEGRATION を使用してセキュリティ統合オブジェクトをドロップし、 CREATE SECURITY INTEGRATION を使用して正しい発行者の値でオブジェクトを再度作成する必要があります。

Azureのセキュリティ統合を作成する AD

create security integration external_oauth_azure_1
    type = external_oauth
    enabled = true
    external_oauth_type = azure
    external_oauth_issuer = '<AZURE_AD_ISSUER>'
    external_oauth_jws_keys_url = '<AZURE_AD_JWS_KEY_ENDPOINT>'
    external_oauth_token_user_mapping_claim = 'upn'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';
Copy

オーディエンスでセキュリティ統合を作成する

セキュリティ統合の external_oauth_audience_list パラメーターは AD の構成時に指定した Application ID URI と一致している必要があります。

create security integration external_oauth_azure_2
    type = external_oauth
    enabled = true
    external_oauth_type = azure
    external_oauth_issuer = '<AZURE_AD_ISSUER>'
    external_oauth_jws_keys_url = '<AZURE_AD_JWS_KEY_ENDPOINT>'
    external_oauth_audience_list = ('<SNOWFLAKE_APPLICATION_ID_URI>')
    external_oauth_token_user_mapping_claim = 'upn'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';
Copy

外部 OAuth セキュリティ統合の変更

セキュリティ統合で ALTER ステートメントを実行することにより、外部 OAuth セキュリティ統合を更新できます。

詳細については、 ALTER SECURITY INTEGRATION (外部 OAuth) をご参照ください。

外部 OAuth での ANY ロールの使用

Snowflakeにセキュリティ統合を作成する構成ステップでは、 OAuth アクセストークンにスコープ定義が含まれています。したがって、実行時に外部 OAuth セキュリティ統合を使用すると、 OAuth クライアントもユーザーも、 OAuth アクセストークンで未定義のロールを使用できなくなります。

アクセストークンを検証してセッションを作成した後、 ANY ロールは OAuth クライアントとユーザーがそのロールを決定できるようにします。必要に応じて、クライアントまたはユーザーは、 OAuth アクセストークンで定義されたロールとは異なるロールに切り替えることができます。

ANY ロールを構成するには、スコープを SESSION:ROLE-ANY として定義し、 external_oauth_any_role_mode パラメーターを使用してセキュリティ統合を構成します。このパラメーターには、指定できる3つの文字列値があります。

  • DISABLE の場合、 OAuth クライアントまたはユーザーは、ロール(つまり、 use role <ロール>;)を切り替えられません。デフォルト。

  • ENABLE の場合、 OAuth クライアントまたはユーザーは、ロールを切り替えられます。

  • ENABLE_FOR_PRIVILEGE OAuth クライアントまたはユーザーは、 USE_ANY_ROLE 権限を持つクライアントまたはユーザーのロールのみを切り替えられます。この権限は、ユーザーが使用できる1つ以上のロールに対して付与および取り消しができます。例:

    grant USE_ANY_ROLE on integration external_oauth_1 to role1;
    
    Copy
    revoke USE_ANY_ROLE on integration external_oauth_1 from role1;
    
    Copy

次のようにセキュリティ統合を定義します。

create security integration external_oauth_1
    type = external_oauth
    enabled = true
    external_oauth_any_role_mode = 'ENABLE'
    ...
Copy

外部 OAuth でのセカンダリロールの使用

プライマリロールに必要なスコープが外部トークンで渡されます。ユーザーの既定のロール(session:role-any)、またはユーザーに付与された特定のロール(session:role:<ロール名>)のいずれかです。

デフォルトでは、Snowflakeは、セッション内にあるユーザー(つまり、 DEFAULT_SECONDARY_ROLES)のデフォルトの セカンダリロール をアクティブ化 しません

セッション内にあるユーザーのデフォルトのセカンダリロールをアクティブ化し、外部 OAuth の使用中に USE SECONDARY ROLES コマンドの実行を許可するには、次のステップを実行します。

  1. 接続のセキュリティ統合を構成します。セキュリティ統合の作成時(CREATE SECURITY INTEGRATION を使用)またはその後(ALTER SECURITY INTEGRATION を使用)に、EXTERNAL_OAUTH_ANY_ROLE_MODE パラメーター値を ENABLE または ENABLE_FOR_PRIVILEGE に設定します。

  2. トークンのスコープ属性に静的な値 session:role-any を渡すように認証サーバーを構成します。スコープパラメーターの詳細については、 外部 OAuth の概要 をご参照ください。

外部 OAuth でのクライアントリダイレクトの使用

Snowflakeは、サポートされているSnowflakeクライアントでのクライアントリダイレクトおよび OAuth の使用を含め、外部 OAuth でのクライアントリダイレクトの使用をサポートしています。

詳細については、 クライアント接続のリダイレクト をご参照ください。

外部 OAuth でのネットワークポリシーの使用

現在、ネットワークポリシーは外部 OAuth セキュリティ統合に追加できません。ただし、Snowflakeアカウント全体に広く適用されるネットワークポリシーを実装することはできます。

ユースケースで OAuth セキュリティ統合に固有のネットワークポリシーが必要な場合は、 Snowflake OAuth を使用します。このアプローチにより、Snowflake OAuth ネットワークポリシーとSnowflakeアカウントに適用される他のネットワークポリシーを区別することができるようになります。

詳細については、 ネットワークポリシー をご参照ください。

外部 OAuth での複製の使用

Snowflakeは、ソースアカウントからターゲットアカウントへの外部 OAuth セキュリティ統合の複製とフェールオーバー/フェールバックをサポートします。

詳細については、 複数のアカウントにわたるセキュリティ統合とネットワークポリシーの複製 をご参照ください。

テスト手順

認証サーバーとしてAzure AD を使用しながら OAuth をテストするコンテキストでは、次を実行する必要があります。

  1. テストユーザーがAzure AD に存在し、パスワードを持っていることを確認します。

  2. login_name 属性値が <AZURE_AD_USER_USERNAME> に設定されたテストユーザーがSnowflakeに存在することを確認します。

  3. このユーザーに SYSADMIN ロールを付与します。

  4. OAuth クライアントを登録します。

  5. 次のように、 OAuth クライアントがAzure AD トークンエンドポイントに POST リクエストすることを許可します。

    • リソース所有者に設定された付与タイプ

    • clientID とシークレットを含む HTTP 基本認証ヘッダー

    • ユーザーのユーザー名およびパスワードを含む FORM データ

    • スコープを含める

cURL を使用してアクセストークンを取得する例を次に示します。Azureアプリ URI を含め、スコープが完全に修飾されている必要があることに注意してください(例: scope=https://example.com/wergheroifvj25/session:role-any)。

curl -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  --data-urlencode "client_id=<OAUTH_CLIENT_ID>" \
  --data-urlencode "client_secret=<OAUTH_CLIENT_SECRET>" \
  --data-urlencode "username=<AZURE_AD_USER>" \
  --data-urlencode "password=<AZURE_AD_USER_PASSWORD>" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "scope=<AZURE_APP_URI+AZURE_APP_SCOPE>" \
  '<AZURE_AD_OAUTH_TOKEN_ENDPOINT>'
Copy

OAuth によるSnowflakeへの接続

セキュリティ統合を構成し、アクセストークンを取得したら、次のいずれかを使用してSnowflakeに接続できます。

次の点に注意してください。

  • authenticator パラメーターを oauth に、 token パラメーターを external_oauth_access_token に設定する必要があります。

  • URL クエリパラメータとして token 値を渡す場合、 token 値を URL エンコードする必要があります。

  • token 値をプロパティオブジェクト(例: JDBC ドライバー)に渡す場合、変更は必要ありません。

たとえば、Pythonコネクタを使用している場合、以下に示すように接続文字列を設定します。

ctx = snowflake.connector.connect(
   user="<username>",
   host="<hostname>",
   account="<account_identifier>",
   authenticator="oauth",
   token="<external_oauth_access_token>",
   warehouse="test_warehouse",
   database="test_db",
   schema="test_schema"
)
Copy

外部 OAuth を使用して、Snowflakeに安全に接続できるようになりました。