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

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

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

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

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

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

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

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

また、 Databricksユーザー、サービスプリンシパル、およびグループにサービスプリンシパルを使用する権限を付与することもできます。これにより、ユーザーは自分の ID としてではなく、サービスプリンシパルとしてジョブを実行できるようになります。これにより、ユーザーが組織を離れたり、グループが変更されたりしてもジョブが失敗することがなくなります。

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

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

重要

Databricks は、2023 年 11 月 8 日に ID フェデレーションと Unity Catalog の新しいワークスペースを自動的に有効にし始め、アカウント全体で徐々にロールアウトが進んでいます。ワークスペースで ID フェデレーションがデフォルトで有効になっている場合、無効にすることはできません。詳細については、「Unity Catalogの自動有効化」を参照してください。

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

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

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

注：

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

サービスプリンシパル Manager ロールを持つユーザーは、サービスプリンシパル User ロールを継承しません。サービスプリンシパルを使用してジョブを実行する場合は、サービスプリンシパルを作成した後でも、サービスプリンシパルユーザーロールを明示的に割り当てる必要があります。

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

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

注：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

サービスプリンシパルが再アクティブ化されると、同じ権限で Databricks にログインできます。 Databricks 、サービスプリンシパルを削除することは破壊的なアクションであるため、サービスプリンシパルを削除するのではなく、アカウントから非アクティブ化することをお勧めします。非アクティブ化されたサービスプリンシパルのステータスは、アカウントコンソールで 「非アクティブ 」と表示されます。特定のワークスペースからサービスプリンシパルを非アクティブ化することもできます。「Databricksワークスペースでサービスプリンシパルを非アクティブ化する」を参照してください。

アカウントコンソールを使用してサービスプリンシパルを非アクティブ化することはできません。代わりに、アカウントサービスプリンシパル API.

例：

curl --netrc -X PATCH \
https://${DATABRICKS_HOST}/api/2.1/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"
        }
      ]
    }
  ]
}

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

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

重要

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

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

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

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

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

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

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

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

注：

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

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

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

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

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

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

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

サービスプリンシパルが再アクティブ化されると、同じ権限でワークスペースに認証できるようになります。サービスプリンシパルを削除することは破壊的なアクションであるため、 Databricks 、サービスプリンシパルを削除するのではなく非アクティブ化することを推奨しています。

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

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

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

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

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

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

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

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

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

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

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

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

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

アカウントおよびワークスペース管理者は、ワークスペース Assignment 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を使用して、サービスプリンシパルを自分のワークスペースに割り当てることができます。ワークスペースサービスプリンシパルAPI参照してください。

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

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

Databricks OAuthトークンは、 DatabricksアカウントレベルおよびワークスペースレベルのAPIsへの認証に使用できます。
- DatabricksOAuthDatabricksアカウントDatabricks レベルで作成されたトークンは、アカウントレベルおよびワークスペースレベルのAPIs への認証に使用できます。
- ワークスペースレベルで作成されたDatabricksOAuth トークンは、DatabricksDatabricks ワークスペースレベルのAPIs に対してのみ認証に使用できます。
Databricks個人用アクセストークンは、 DatabricksワークスペースレベルのAPIsに対してのみ認証に使用できます。

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

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