ワークスペースのシークレット スコープ

ワークスペースのシークレットスコープとは、1つのワークスペース内の名前付きのシークレットの集合です。 シークレットスコープの権限は、誰がその中のシークレットを読み書きし、管理できるかを制御します。 権限はスコープ全体に適用され、個々のシークレットには適用されません。つまり、スコープ内の1つのシークレットを読み取れるユーザーでも、すべてのシークレットを読み取ることができます。 ワークスペースのシークレットスコープとUnity Catalogのシークレットを比較するには、「 シークレットをどこに保存するか」をご覧ください。

ワークスペースのシークレットスコープを使うには:

1. シークレット スコープを作成する。
2. スコープにシークレットを追加しましょう。
3. スコープに対して権限を付与してください。
4. コード内、Spark の設定プロパティ、または環境変数で秘密を参照してください。 「Spark の構成プロパティまたは環境変数のシークレットを使用する」を参照してください。

シークレット スコープを管理する

Azure Databricksは、シークレットスコープを個人ではなくロールやアプリケーションにアライメントすることを推奨しています。

シークレット スコープには、次の 2 種類があります。

• Azure Key Vault でサポート: Azure Key Vault でサポートされるシークレット スコープを使用して、Azure Key Vault に格納されているシークレットを参照できます。 Azure Key Vaultを利用するシークレットのスコープは、そのKey Vaultへの読み取り専用インターフェイスです。 Azureでそのシークレットを管理します。
• Databricks でサポート: Databricks でサポートされるシークレット スコープは、Azure Databricks によって所有および管理される暗号化されたデータベースに格納されます。

シークレット スコープを作成したら、アクセス許可を割り当てて、シークレット スコープの読み取り、書き込み、管理へのアクセス権をユーザーに付与できます。

Azure Key Vault でサポートされるシークレット スコープを作成する

Azure portal と Azure Databricks ワークスペース UI で、Azure Key Vault をバックエンドとするシークレット スコープを作成します。 DatabricksのCLIも使えます。

Requirements

• Azure Key Vault インスタンスが必要です。 Key Vault インスタンスがない場合は、「Azure portal を使用してキー コンテナーを作成する」に記載されている手順に従ってください。
• シークレット スコープをサポートするために使用する Azure Key Vault インスタンス上の Key Vault 共同作成者、共同作成者、または所有者のロールが必要です。

Unable to grant read/list permission to Databricks service principal to KeyVault 'https://xxxxx.vault.azure.net/': Status code 403, {"odata.error":{"code":"Authorization_RequestDenied","message":{"lang":"en","value":"Insufficient privileges to complete the operation."},"requestId":"XXXXX","date":"YYYY-MM-DDTHH:MM:SS"}}

Azure Databricks 用に Azure キー コンテナー インスタンスを構成する

1. Azureポータルにサインインし、Azure Key Vaultインスタンスを見つけて選択します。

2. [設定] の下の [アクセス構成] タブをクリックします。

3. [アクセス許可モデル] を [Vault アクセス ポリシー] に設定します。 新しい Key Vault は既定でAzure ロールベースのアクセス制御を採用しており、Azure Key Vault を利用したシークレット スコープはこれをサポートしていません。

   Note

   Azure Key Vault を利用するシークレット スコープを作成すると、Vault アクセス ポリシーを使用して、Azure Databricks サービスのアプリケーション ID に Get および List のアクセス許可が付与されます。

4. [設定] で、 [ネットワーク] を選択します。

5. [ファイアウォールと仮想ネットワーク] で、[次からのアクセスを許可する:] を [特定の仮想ネットワークと IP アドレスからのパブリック アクセスを許可する] に設定します。

   [例外] で、[信頼された Microsoft サービスがこのファイアウォールをバイパスすることを許可します] を選択します。

   Note

   次からのアクセスを許可する: を すべてのネットワークからのパブリック アクセスを許可する に設定することもできます。

Azure Key Vault でサポートされるシークレット スコープを作成する

1. https://<databricks-instance>#secrets/createScope にアクセスします。 <databricks-instance>を Azure Databricks デプロイのワークスペース URL に置き換えます。 この URL では大文字と小文字が区別されます。 例えば、createScopeのscopeは大文字のSを使わなければなりません。

   

2. シークレットのスコープの名前を入力します。 シークレットのスコープの名前は大文字と小文字が区別されません。

3. [プリンシパルの管理] で、[作成者] または [すべてのワークスペース ユーザー] を選択し、シークレット スコープに対する管理アクセス許可を持つユーザーを指定します。

   管理アクセス許可により、ユーザーはスコープの読み取り、書き込み、アクセス許可の付与を行うことができます。 [作成者] を選択するには、アカウントが Premium プランである必要があります。

4. [DNS 名] (例: https://databrickskv.vault.azure.net/) と [リソース ID] (次の例) を入力します。

   /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/databricks-rg/providers/Microsoft.KeyVault/vaults/databricksKV
   

   これらのプロパティは、Azure portal 内の Azure Key Vault の [設定] > [プロパティ] タブから使用できます。

5. Create をクリックしてください。

6. Databricks CLI の databricks secrets list-scopes コマンドを使用して、スコープが正常に作成されたことを確認します。

Databricks でサポートされるシークレット スコープを作成する

Databricks CLI(バージョン0.205以降)またはSecrets APIでシークレットスコープを作成します。

シークレット スコープ名:

• ワークスペース内で一意である必要があります。
• 英数字、ダッシュ、アンダースコア、@、ピリオドで構成され、128文字を超えてはなりません。
• 大文字と小文字が区別されません。

シークレット スコープ名は、機密ではないと見なされ、ワークスペース内のすべてのユーザーが読み取り可能です。

Databricks CLI を使用してスコープを作成するには、次のようにします。

databricks secrets create-scope <scope-name>

既定では、スコープは、スコープを作成したユーザーに対する管理アクセス許可付きで作成されます。 Databricks でサポートされるシークレット スコープを作成したら、シークレットを追加できます。

シークレット スコープを一覧表示する

CLI を使用してワークスペースの既存のスコープを一覧表示するには、次のようにします。

databricks secrets list-scopes

Secrets API を使用して、既存のスコープを一覧表示することもできます。

シークレットのスコープを削除する

シークレット スコープを削除すると、スコープに適用されているすべてのシークレットと ACL が削除されます。 CLI を使用してスコープを削除するには、以下を実行します。

databricks secrets delete-scope <scope-name>

Secrets API を使用して、シークレット スコープを削除することもできます。

シークレットを管理する

シークレットは、シークレット スコープ内で一意のキー名を使用して機密マテリアルを格納するキーと値のペアです。

シークレットを作成する方法は、ユーザーが Azure Key Vault でサポートされるスコープを使用しているか、Databricks でサポートされるスコープを使用しているかによって異なります。

Azure Key Vault でサポートされるスコープにシークレットを作成する

Azure Key Vault にシークレットを作成するには、Azure portal または Azure Set Secret REST API を使用します。

Databricks でサポートされるスコープにシークレットを作成する

Databricks CLI(バージョン0.205以上)、Notebook内のDatabricks SDK for Python、またはSecrets APIでシークレットを作成します。 シークレット名は大文字と小文字が区別されません。

Databricks コマンドラインインターフェース (CLI)

Databricks でサポートされるスコープにシークレットを作成する場合は、次の 3 つの方法のいずれかでシークレット値を指定できます。

• 値は --string-value フラグ付きの文字列として指定します。
• 対話形式でプロンプトが表示されたら、シークレットを入力します (1 行のシークレット)。
• 標準入力を使用してシークレットを渡します (複数行のシークレット)。

例:

databricks secrets put-secret --json '{
  "scope": "<scope-name>",
  "key": "<key-name>",
  "string_value": "<secret>"
}'

複数行のシークレットを作成する場合は、標準入力を使ってシークレットを渡すことができます。 例:

(cat << EOF
this
is
a
multi
line
secret
EOF
) | databricks secrets put-secret <scope-name> <key-name>

Databricks SDK for Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.secrets.put_secret("<secret_scope>","<key-name>",string_value ="<secret>")

シークレットを読み取る

Databricks CLI(バージョン0.205以上)で秘密を読み取るか、ノートブックのSecretsユーティリティ(dbutils.secrets)で読み取ることができます。

Databricks コマンドラインインターフェース (CLI)

Databricks CLIを使ってシークレットの値を読み取るには、base64でエンコードされた値をデコードする必要があります。 jq を使用して値を抽出し、base64 --decode を使用してデコードできます。

databricks secrets get-secret <scope-name> <key-name> | jq -r .value | base64 --decode

Secrets ユーティリティ (dbutils.secrets)

password = dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")

シークレットのリスト

特定のスコープ内のシークレットを一覧表示するには、次のようにします。

databricks secrets list-secrets <scope-name>

応答にはキー名などの秘密に関するメタデータが表示されます。 ノートブックまたはジョブでこのメタデータを一覧表示するには、Secrets ユーティリティ (dbutils.secrets)を使いましょう。 例:

dbutils.secrets.list('my-scope')

シークレットを削除します

Databricks CLI を使用してスコープからシークレットを削除するには、次のようにします。

databricks secrets delete-secret <scope-name> <key-name>

Secrets API を使用することもできます。

Azure Key Vault によってサポートされるスコープからシークレットを削除するには、Azure SetSecret REST API または Azure portal UI を使用します。

シークレット スコープのアクセス許可を管理する

デフォルトでは、シークレットスコープを作成するユーザーにはそのスコープに対する MANAGE 権限があり、これにより、スコープ内のシークレットの読み取り、シークレットの書き込み、およびその権限の管理を行うことができます。

秘密のスコープ権限は DatabricksのCLI (バージョン0.205以降)または Secrets APIで管理してください。 秘密権限レベルについては、 秘密ACLを参照してください。

シークレット スコープに対するアクセス許可をユーザーに付与する

Databricks CLI を使用してシークレット スコープに対するアクセス許可をユーザーに付与するには、次のようにします。

databricks secrets put-acl <scope-name> <principal> <permission>

既にアクセス許可が適用されているプリンシパルに対して put 要求を行うと、既存の権限レベルが上書きされます。

principal フィールドは、既存の Azure Databricks プリンシパルを指定します。 ユーザーはそのメール アドレスで、サービス プリンシパルはその applicationId 値で、グループはそのグループ名で指定されます。 詳細については、「プリンシパル」を参照してください。

例えば、datascience のようなグループにスコープ内のシークレットを読み取らせるには、READ を付与します:

databricks secrets put-acl <scope-name> <group> READ

シークレット スコープのアクセス許可を表示する

特定のシークレット スコープのすべてのシークレット スコープのアクセス許可を表示するには、次のようにします。

databricks secrets list-acls <scope-name>

特定のシークレット スコープのプリンシパルに適用されたシークレット スコープのアクセス許可を取得するには、次のようにします。

databricks secrets get-acl <scope-name> <principal>

指定されたプリンシパルとスコープに対して ACL が存在しない場合、この要求は失敗します。

シークレット スコープのアクセス許可を削除する

特定のシークレット スコープのプリンシパルに適用されたシークレット スコープのアクセス許可を削除するには、次のようにします。

databricks secrets delete-acl <scope-name> <principal>

シークレットの編集

資格情報をAzure Databricksシークレットとして格納すると、ノートブックとジョブを実行するときに資格情報の保護に役立ちます。 しかし、標準出力バッファにシークレットを誤って印刷したり、変数割り当て時に値を表示したりすることはあります。

これを防ぐために、Azure Databricksはdbutils.secrets.get()で読み込まれ、Sparkの設定プロパティで参照される秘密値をマスクしようと試みます。 表示されると、シークレット値は [REDACTED]に置き換えられます。

たとえば、dbutils.secrets.get() を使用して変数をシークレット値に設定し、その変数を出力すると、その変数は [REDACTED] に置き換えられます。

SQL でのシークレットの編集

Azure Databricksは、参照されるビューやユーザー定義関数を含め、秘密関数を呼び出すすべてのSQLデータ クエリ言語 (DQL) コマンドを伏せ字にしようとします。 secret関数を使用すると、出力は可能な限り[REDACTED]に置き換えられます。 ノートブックの編集と同様に、これはリテラル値にのみ適用され、変換または間接的に参照されるシークレットには適用されません。

SQLデータ操作言語(DML)コマンドの場合、Azure Databricksはシークレットが安全と見なされる場合にシークレットの参照を許可します。 例えば、秘密は sha() や aes_encrypt()のような暗号関数でラップされている場合、生の値が暗号化されていないまま保存されるのを防ぐことで安全です。

SQL でのシークレットの検証

Azure Databricks では、暗号化されていないシークレットがテーブルに保存される可能性がある SQL DML コマンドをブロックするための検証も適用されます。 クエリ アナライザーは、これらのシナリオを特定して防止しようとします。これにより、プレーンテキストで機密情報が誤って保存されるのを防ぐことができます。

追加リソース