サービスプリンシパルを管理する

この記事では、Databricksアカウントおよびワークスペース用のサービスプリンシパルを作成および管理する方法について説明します。

Databricks ID モデルの概要については、「 Databricks ID」を参照してください。

サービスプリンシパルのアクセスを管理するには、「認証とアクセス制御」を参照してください。

サービスプリンシパルとは

サービスプリンシパルは、自動化ツール、ジョブ、アプリケーションで使用するために、お客様がDatabricksで作成するIDです。サービスプリンシパルは、自動化ツールとスクリプトにDatabricksリソースへのAPI専用のアクセス権を提供し、ユーザーやグループを使用するよりも優れたセキュリティを実現します。

サービスプリンシパルのリソースへのアクセス権は、Databricksユーザーと同じ方法で付与および制限できます。例として、次の手順を実行します。

サービスプリンシパルアカウントの管理者ロールとワークスペース管理者ロールを付与します。
Unity Catalogを使用したアカウントレベルまたはワークスペースレベルで、サービスプリンシパルにデータへのアクセス権を付与します。
サービスプリンシパルをグループに、アカウントレベルとワークスペースレベルの両方で追加します（ワークスペースadminsグループを含む）。

また、Databricks ユーザー、サービスプリンシパル、およびグループに、サービスプリンシパルを使用するためのアクセス許可を付与することもできます。これにより、ユーザーは ID としてではなく、サービスプリンシパルとしてジョブを実行できます。これにより、ユーザーが組織を離れたり、グループが変更されたりした場合にジョブが失敗するのを防ぎます。

Databricksユーザーとは異なり、サービスプリンシパルはAPIのみのIDです。データブリックUIへのアクセスには使用できません。

Databricks では、ワークスペースで ID フェデレーションを有効にすることをお勧めします。 ID フェデレーションを使用すると、アカウントコンソールでサービスプリンシパルを設定し、特定のワークスペースへのアクセス権を割り当てることができます。これにより、Databricks の管理とデータガバナンスが簡素化されます。

重要

アカウントが 2023 年 11 月 8 日以降に作成された場合、ID フェデレーションはすべての新しいワークスペースでデフォルトによって有効になり、無効にすることはできません。

誰がサービスプリンシパルを管理および使用できますか?

Databricks でサービスプリンシパルを管理するには、アカウント管理者ロール、ワークスペース管理者ロール、またはサービスプリンシパルのマネージャーまたはユーザーロールのいずれかが必要です。

アカウント管理者は、サービスプリンシパルをアカウント に追加し、管理者ロールを割り当てることができます。また、ワークスペースが ID フェデレーションを使用している限り、サービスプリンシパルをワークスペースに割り当てることもできます。
ワークスペース管理者は 、サービスプリンシパルを Databricks ワークスペースに追加し、ワークスペース管理者ロールを割り当て、クラスターの作成や指定されたペルソナベースの環境へのアクセスなど、ワークスペース内のオブジェクトと機能へのアクセスを管理できます。
サービスプリンシパルマネージャーは、サービスプリンシパルの役割を管理できます。サービスプリンシパルの作成者は、サービスプリンシパルマネージャーになります。アカウント管理者は、アカウント内のすべてのサービスプリンシパルのサービスプリンシパルマネージャーです。

注

サービスプリンシパルが 2023 年 6 月 13 日より前に作成された場合、サービスプリンシパルの作成者はデフォルトでサービスプリンシパルマネージャーロールを持っていません。アカウント管理者に依頼して、サービスプリンシパルマネージャーの役割を付与してもらってください。

サービスプリンシパルユーザーはサービスプリンシパルとしてジョブを実行できます。ジョブは、ジョブ所有者の ID ではなく、サービスプリンシパルの ID を使用して実行されます。詳細については、「サービスプリンシパルとしてジョブを実行する」を参照してください。

サービスプリンシパルワークスペース管理者であるユーザーは、サービスプリンシパルに代わってトークンを作成することもできます。

注

ワークスペースのRestrictWorkspaceAdmins設定がALLOW ALLに設定されている場合、ワークスペース管理者は、ワークスペース内のサービスプリンシパルに代わって個人的なアクセスを作成できます。「ワークスペース管理者の制限」を参照してください。

サービスプリンシパルにマネージャーロールとユーザーロールを付与する方法については、サービスプリンシパルを管理するためのロールを参照してください。

アカウントでサービスプリンシパルを管理する

アカウント管理者は、アカウントコンソールを使用して、Databricks アカウントにサービスプリンシパルを追加できます。

アカウントコンソールを使用してサービスプリンシパルをアカウントに追加する

アカウント管理者として、アカウントコンソールにログインします。
サイドバーで、[ユーザー管理] をクリックします。
[サービスプリンシパル] タブで、[サービスプリンシパルの追加] をクリックします。
サービスプリンシパルの名前を入力します。
[追加] をクリックします。

アカウント管理者の役割をサービスプリンシパルに割り当てる

アカウント管理者として、アカウントコンソールにログインします。
サイドバーで、[ユーザー管理] をクリックします。
[サービスプリンシパル] タブで、ユーザー名を見つけてクリックします。
[役割 ] タブで、[アカウント管理者] または [Marketplace 管理者] をオンにします。

アカウントコンソールを使用してサービスプリンシパルをワークスペースに割り当てる

アカウントコンソールを使用してワークスペースにユーザーを追加するには、ワークスペースで ID フェデレーションを有効にする必要があります。ワークスペース管理者は、ワークスペース管理者設定ページを使用して、サービスプリンシパルをワークスペースに割り当てることもできます。詳細については、「ワークスペース管理設定を使用してサービスプリンシパルをワークスペースに追加する」を参照してください。

アカウント管理者として、アカウントコンソールにログインします。
サイドバーで、[ワークスペース] をクリックします。
ワークスペース名をクリックします。
[権限] タブで、[権限を追加] をクリックします。
サービスプリンシパルを検索して選択し、権限レベル（ワークスペースユーザーまたは管理者）を割り当て、[保存] をクリックします。

アカウントコンソールを使用してサービスプリンシパルをワークスペースから削除する

アカウントコンソールを使用してワークスペースからサービスプリンシパルを削除するには、ワークスペースで ID フェデレーションが有効になっている必要があります。サービスプリンシパルがワークスペースから削除されると、サービスプリンシパルはワークスペースにアクセスできなくなりますが、サービスプリンシパルに対するアクセス許可は維持されます。サービスプリンシパルが後でワークスペースに再度追加されると、以前のアクセス許可が回復します。

アカウント管理者として、アカウントコンソールにログインします。
サイドバーで、[ワークスペース] をクリックします。
ワークスペース名をクリックします。
[権限] タブで、サービスプリンシパルを見つけます。
サービスプリンシパル行の右端にあるケバブメニューをクリックし、[削除] を選択します。
確認ダイアログで、[ 削除] をクリックします。

Databricks アカウントでサービスプリンシパルを非アクティブ化する

アカウント管理者は、Databricks アカウント全体でサービスプリンシパルを非アクティブ化できます。非アクティブ化されたサービスプリンシパルは、Databricks アカウントまたはワークスペースに対して認証できません。ただし、サービスプリンシパルのすべてのアクセス許可とワークスペースオブジェクトは変更されません。サービスプリンシパルが非アクティブ化されると、次のことが当てはまります。

サービスプリンシパルは、どの方法からもアカウントまたはそのワークスペースに対して認証することはできません。
サービスプリンシパルによって生成されたトークンを使用するアプリケーションまたはスクリプトは、Databricks API にアクセスできなくなります。トークンは残りますが、サービスプリンシパルが非アクティブ化されている間は認証に使用できません。
サービスプリンシパルが所有するクラスターは引き続き実行されます。
サービスプリンシパルによって作成されたスケジュールされたジョブは、新しい所有者に割り当てられない限り失敗します。

サービスプリンシパルが再アクティブ化されると、同じアクセス許可で Databricks にログインできます。 Databricks では、サービスプリンシパルを削除することは破壊的なアクションであるため、サービスプリンシパルを削除するのではなく、アカウントから非アクティブ化することをお勧めします。「 Databricks アカウントからサービスプリンシパルを削除する」を参照してください。アカウントからサービスプリンシパルを非アクティブ化すると、そのサービスプリンシパルも ID フェデレーションワークスペースから非アクティブ化されます。

アカウントコンソールを使用してユーザーを非アクティブ化することはできません。代わりに、アカウントサービスプリンシパル API を使用します。「API を使用したサービスプリンシパルの非アクティブ化」を参照してください。

サービスプリンシパルをDatabricksアカウントから削除する

アカウント管理者は、サービスプリンシパルをDatabricksアカウントから削除できます。ワークスペース管理者にはその権限がありません。サービスプリンシパルをアカウントから削除すると、そのプリンシパルはワークスペースからも削除されます。

重要

アカウントからサービスプリンシパルを削除すると、ID フェデレーションが有効になっているかどうかに関係なく、そのサービスプリンシパルもワークスペースから削除されます。アカウント内のすべてのワークスペースへのアクセスを失わせたい場合を除き、アカウントレベルのサービスプリンシパルの削除は控えることをお勧めします。サービスプリンシパルを削除すると、次の結果に注意してください。

サービスプリンシパルによって生成されたトークンを使用するアプリケーションまたはスクリプトは、Databricks にアクセスできなくなります APIs
サービスプリンシパルが所有するジョブが失敗する
サービスプリンシパルストップが所有するクラスター
クエリーまたはサービスプリンシパルによって作成され、所有者として実行資格情報を使用して共有されるダッシュボードは、共有が失敗しないように新しい所有者に割り当てる必要があります

アカウントコンソールを使用してサービスプリンシパルを削除するには、次の手順を実行します。

アカウント管理者として、アカウントコンソールにログインします。
サイドバーで、[ユーザー管理] をクリックします。
[サービスプリンシパル] タブで、ユーザー名を見つけてクリックします。
[プリンシパル情報] タブで、右上隅にあるケバブメニューをクリックし、[削除] を選択します。
確認ダイアログボックスで、[削除を確認] をクリックします。

ワークスペースでサービスプリンシパルを管理する

ワークスペース管理者は、ワークスペース管理者設定ページを使用して、ワークスペースでサービスプリンシパルを管理できます。

ワークスペース管理者設定を使用してサービスプリンシパルをワークスペースに追加する

ワークスペース管理者として、Databrickワークスペースにログインします。
Databricks ワークスペースの上部バーにあるユーザー名をクリックし、 [設定]を選択します。
[ ID とアクセス ] タブをクリックします。
[サービスプリンシパル] の横にある [管理] をクリックします。
[ Add サービスプリンシパル] をクリックします。
ワークスペースに割り当てる既存のサービスプリンシパルを選択するか、「 新規追加 」をクリックして新しいサービスプリンシパルを作成します。
[追加] をクリックします。

注

ワークスペースで ID フェデレーションが有効になっていない場合、既存のアカウントサービスプリンシパルをワークスペースに割り当てることはできません。

ワークスペース管理者設定ページを使用して、サービスプリンシパルにワークスペース管理者ロールを割り当てる

ワークスペース管理者として、Databrickワークスペースにログインします。
Databricks ワークスペースの上部バーにあるユーザー名をクリックし、 [設定]を選択します。
[ ID とアクセス ] タブをクリックします。
[グループ] の横にある [管理] をクリックします。
adminsシステムグループを選択します。
[メンバーを追加]をクリックします。
サービスプリンシパルを選択し、[確定] をクリックします。

サービスプリンシパルからワークスペース管理者ロールを削除するには、管理者グループからサービスプリンシパルを削除します。

Databricks ワークスペースでサービスプリンシパルを非アクティブ化する

ワークスペース管理者は、Databricks ワークスペースでサービスプリンシパルを非アクティブ化できます。非アクティブ化されたサービスプリンシパルは、Databricks APIsからワークスペースにアクセスできませんが、サービスプリンシパルのすべてのアクセス許可とワークスペースオブジェクトは変更されません。サービスプリンシパルが非アクティブ化された場合:

サービスプリンシパルは、どのメソッドからもワークスペースを認証できません。
サービスプリンシパルの状態は、ワークスペース管理設定ページで [非アクティブ ] と表示されます。
サービスプリンシパルによって生成されたトークンを使用するアプリケーションまたはスクリプトは、Databricks API にアクセスできなくなります。トークンは残りますが、サービスプリンシパルが非アクティブ化されている間は認証に使用できません。
サービスプリンシパルが所有するクラスターは引き続き実行されます。
サービスプリンシパルによって作成されたスケジュールされたジョブは、失敗を防ぐために新しい所有者に割り当てる必要があります。

サービスプリンシパルが再アクティブ化されると、同じアクセス許可でワークスペースに対して認証できます。 Databricks では、サービスプリンシパルを削除することは破壊的なアクションであるため、サービスプリンシパルを削除するのではなく、非アクティブ化することをお勧めします。

ワークスペース管理者として、Databrickワークスペースにログインします。
Databricks ワークスペースの上部バーにあるユーザー名をクリックし、 [設定]を選択します。
[ ID とアクセス ] タブをクリックします。
[サービスプリンシパル] の横にある [管理] をクリックします。
非アクティブ化するサービスプリンシパルを選択します。
[ ステータス] で [アクティブ] をオフにします。

サービスプリンシパルをアクティブに設定するには、同じ手順を実行しますが、代わりにチェックボックスをオンにします。

ワークスペース管理設定ページを使用したワークスペースからのサービスプリンシパルの削除

ワークスペースからサービスプリンシパルを削除しても、アカウントからサービスプリンシパルは削除されません。アカウントからサービスプリンシパルを削除するには、「 Databricks アカウントからサービスプリンシパルを削除する」を参照してください。

サービスプリンシパルがワークスペースから削除されると、サービスプリンシパルはワークスペースにアクセスできなくなりますが、サービスプリンシパルに対するアクセス許可は維持されます。サービスプリンシパルが後でワークスペースに再度追加されると、以前のアクセス許可が回復します。

ワークスペース管理者として、Databrickワークスペースにログインします。
Databricks ワークスペースの上部バーにあるユーザー名をクリックし、 [設定]を選択します。
[ ID とアクセス ] タブをクリックします。
[サービスプリンシパル] の横にある [管理] をクリックします。
サービスプリンシパルを選択します。
右上隅にある [削除] をクリックします。
[削除] をクリックして確定します。

API を使用したサービスプリンシパルの管理

アカウント管理者とワークスペース管理者は、Databricks APIsを使用して、Databricks アカウントとワークスペースでサービスプリンシパルを管理できます。 API を使用してサービスプリンシパルのロールを管理するには、「 Databricks CLI を使用してサービスプリンシパルロールを管理する」を参照してください。

API を使用してアカウントでサービスプリンシパルを管理する

管理者は、アカウントサービスプリンシパル API を使用して、Databricks アカウントにサービスプリンシパルを追加および管理できます。アカウント管理者とワークスペース管理者は、別のエンドポイント URL を使用して API を呼び出します。

アカウント管理者は{account-domain}/api/2.0/accounts/{account_id}/scim/v2/を使用します。
ワークスペース管理者は{workspace-domain}/api/2.0/account/scim/v2/を使用します。

詳細については、アカウントサービスプリンシパル API を参照してください。

API を使用したサービスプリンシパルの非アクティブ化

アカウント管理者は、サービスプリンシパルのステータスを false に変更し、アカウントサービスプリンシパル API を使用してサービスプリンシパルを非アクティブ化できます。

例：

curl --netrc -X PATCH \
https://${DATABRICKS_HOST}/api/2.0/accounts/{account_id}/scim/v2/ServicePrincipals/{id} \
--header 'Content-type: application/scim+json' \
--data @update-sp.json \
| jq .

update-sp.json:

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": [
        {
          "value": "false"
        }
      ]
    }
  ]
}

非アクティブ化されたサービスプリンシパルのステータスは、アカウントコンソールで「 非アクティブ 」と表示されます。アカウントからサービスプリンシパルを非アクティブ化すると、そのサービスプリンシパルもワークスペースから非アクティブ化されます。

API を使用してワークスペースでサービスプリンシパルを管理する

アカウント管理者とワークスペース管理者は、ワークスペース割り当て API を使用して、ID フェデレーションが有効になっているワークスペースにサービスプリンシパルを割り当てることができます。ワークスペース割り当て API は、Databricks アカウントとワークスペースを通じてサポートされます。

アカウント管理者は{account-domain}/api/2.0/accounts/{account_id}/workspaces/{workspace_id}/permissionassignmentsを使用します。
ワークスペース管理者は{workspace-domain}/api/2.0/preview/permissionassignments/principals/{principal_id}を使用します。

「ワークスペース割り当てAPI」を参照してください。

ワークスペースで ID フェデレーションが有効になっていない場合、ワークスペース管理者はワークスペースレベルの APIs を使用して、サービスプリンシパルをワークスペースに割り当てることができます。「Workspace サービスプリンシパル API」を参照してください。

サービスプリンシパルのトークンを管理する

サービスシプリンパルは、次のように、Databricks OAuth トークンまたは Databricks パーソナルアクセストークンを使用して、Databricks 上のAPIsに対して認証できます。

Databricks OAuth トークンは、Databricks アカウントレベルおよびワークスペースレベルのAPIsに対する認証に使用できます。
- Databricks アカウントレベルで作成された Databricks OAuth トークンは、Databricks アカウントレベルおよびワークスペースレベルのAPIsに対する認証に使用できます。
- Databricks ワークスペースレベルで作成された Databricks OAuth トークンは、Databricks ワークスペースレベルのAPIsに対する認証のみに使用できます。
Databricks パーソナルアクセス内部は、Databricks ワークスペースレベルのAPIsに対する認証のみに使用できます。

サービスプリンシパルの Databricks OAuth 認証を管理する

アカウントレベルおよびワークスペースレベルの Databricks REST APIsに対して認証するために、アカウント管理者はサービスプリンシパルに Databricks OAuth トークンを使用できます。 OAuthトークンは、サービスプリンシパルのクライアントIDとクライアントシークレットを使用してリクエストできます。詳細については、「 OAuth マシン間 (M2M) 認証」を参照してください。

サービスプリンシパルのパーソナルアクセストークンを管理する

Databricks 上のワークスペースレベルのAPIsに対してのみサービスプリンシパルを認証するには、サービスプリンシパルユーザーであるワークスペース管理者は、次のように、サービスプリンシパルに代わって Databricks 個人アクセス人権を作成できます。

注

ワークスペースのRestrictWorkspaceAdmins設定がALLOW ALLに設定されている場合、ワークスペース管理者は、ワークスペース内のサービスプリンシパルに代わって個人的なアクセスを作成できます。「ワークスペース管理者の制限」を参照してください。

注

Databricks ユーザーインターフェイスを使用して、Databricks サービスプリンシパルの Databricks 個人アクセス権を生成することはできません。このプロセスでは、Databricks CLI バージョン 0.205 以降を使用して、Databricks サービスプリンシパルのアクセスノートを生成します。 Databricks CLI がまだインストールされていない場合は、「Databricks CLI のインストールまたは更新」を参照してください。

Databricks CLI の認証をまだ設定していない場合は、設定します。これを設定する 1 つの方法は、最初に Databricks ワークスペースユーザーに対して Databricks 個人アクセス権認証を使用することです。「Databricks の個人アクセス時の認証」を参照してください。
Databricks サービスプリンシパルのアプリケーション ID をまだ取得していない場合は、取得します。
1. ワークスペースの管理コンソールがまだ開いていない場合は、ワークスペースの上部バーでユーザー名をクリックし、 「設定」をクリックします。
2. [ワークスペース管理者]で、 [ID とアクセス]をクリックします。
3. [サービスプリンシパル] の横にある [管理] をクリックします。
4. Databricks サービスプリンパルシの名前をクリックして、その設定ページを開きます。名前が表示されない場合は、フィルターサービスプリンパルシを使用して検索してください。
5. [構成]タブで、アプリケーション ID の値をメモします。
Databricks CLI を使用して次のコマンドを実行します。これにより、Databricks サービスプリンシパルのアクセス権が生成されます。

次のコマンドで、次のプレースホルダーを置き換えます。
- <application-id>を Databricks サービスプリンシパルのアプリケーション ID に置き換えます。
- <lifetime-seconds>をアクセス墨が有効な秒数に置き換えます。たとえば、1 日は 86400 秒です。
- 必要に応じて、 <comment>アクセスアセトンの目的に関する意味のあるコメントに置き換えます。 --commentオプションを指定しない場合、コメントは生成されません。
- 必要に応じて、 <profile-name>を、Databricks ユーザーとターゲットワークスペースの認証情報を含む Databricks 構成プロファイルの名前に置き換えます。たとえば、「Databricks の個人アクセスすべて認証」を参照してください。 -pオプションが指定されていない場合、Databricks CLI は、 DEFAULTという名前の構成プロファイルを検索して使用しようとします。
```
databricks token-management create-obo-token <application-id> --lifetime-seconds <lifetime-seconds> --comment <comment> -p <profile-name>
```
応答で、Databricks サービスプリンシパルのアクセス権であるtoken_valueの値をコピーします。

コピーしたトークンは必ず安全な場所に保存してください。コピーしたトークンを他のユーザーと共有しないでください。コピーしたトークンを紛失した場合、まったく同じトークンを再生成することはできません。代わりに、この手順を繰り返して新しいトークンを作成する必要があります。

ワークスペースでトークンを作成または使用できない場合は、ワークスペース管理者がトークンを無効にしたか、トークンを作成または使用する権限を与えていないことが原因である可能性があります。ワークスペース管理者に問い合わせるか、以下をご覧ください。
- ワークスペースの個人アクセスウイルス認証を有効または無効にする
- 個人のアクセストークンの権限

サービスプリンシパルは、次のように、独自の Databricks 個人アクセス権を使用して、それ自体に追加の Databricks 個人アクセス権を作成できます。

注

Databricks ユーザーインターフェイスを使用して、Databricks サービスプリンシパルの Databricks 個人アクセス権を生成することはできません。このプロセスでは、Databricks CLI バージョン 0.205 以降を使用して、Databricks サービスプリンシパルのアクセスノートを生成します。 Databricks CLI がまだインストールされていない場合は、「Databricks CLI のインストールまたは更新」を参照してください。

この手順は、Databricks サービスプリンシパルに対する最初の Databricks 個人アクセス権がすでに生成されていることを前提としています。このアクセスウイルスを使用して Databricks CLI を設定し、Databricks サービスプリンシパルを認証し、それ自体に対して追加のアクセスウイルスを生成できるようにします。「Databricks の個人アクセス時の認証」を参照してください。

Databricks CLI を使用して次のコマンドを実行すると、Databricks サービスプリンシパルに対する別のアクセス権が生成されます。

次のコマンドで、次のプレースホルダーを置き換えます。
- 必要に応じて、 <comment>アクセスアセトンの目的に関する意味のあるコメントに置き換えます。 --commentオプションを指定しない場合、コメントは生成されません。
- 必要に応じて、 <lifetime-seconds>アクセス教訓が有効な秒数に置き換えます。たとえば、1 日は 86400 秒です。 --lifetime-secondsオプションが指定されていない場合、アクセスマラソンは無期限に設定されます (推奨されません)。
- 必要に応じて、 <profile-name>を、Databricks サービスプリンシパルとターゲットワークスペースの認証情報を含む Databricks 構成プロファイルの名前に置き換えます。 -pオプションが指定されていない場合、Databricks CLI は、 DEFAULTという名前の構成プロファイルを検索して使用しようとします。
```
databricks tokens create --comment <comment> --lifetime-seconds <lifetime-seconds> -p <profile-name>
```
応答で、Databricks サービスプリンシパルのアクセス権であるtoken_valueの値をコピーします。

コピーしたトークンは必ず安全な場所に保存してください。コピーしたトークンを他のユーザーと共有しないでください。コピーしたトークンを紛失した場合、まったく同じトークンを再生成することはできません。代わりに、この手順を繰り返して新しいトークンを作成する必要があります。

ワークスペースでトークンを作成または使用できない場合は、ワークスペース管理者がトークンを無効にしたか、トークンを作成または使用する権限を与えていないことが原因である可能性があります。ワークスペース管理者に問い合わせるか、以下をご覧ください。
- ワークスペースの個人アクセスウイルス認証を有効または無効にする
- 個人のアクセストークンの権限