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

この記事では、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 日より前に作成された場合、サービスプリンシパルの作成者は、デフォルトでサービスプリンシパルマネージャーロールを持ちません。アカウント管理者にサービスプリンシパルマネージャーの役割を付与するよう依頼してください。

サービスプリンシパルユーザーは 、サービスプリンシパルとしてジョブを実行できます。ジョブは、ジョブ所有者の 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)」を参照してください。

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

サービスプリンシパルAPIs Databricksを のワークスペース レベルのに対してのみ認証するには、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プリンシパルのアクセストークンが生成されます。

次のコマンドを実行します。
```
databricks token-management create-obo-token <application-id> --lifetime-seconds <lifetime-seconds> --comment <comment> -p <profile-name>
```
- <application-id> をDatabricksサービスプリンシパルのアプリケーション ID に置き換えます。
- --lifetime-seconds: <lifetime-seconds> を、アクセストークンが有効な秒数に置き換えます。たとえば、1 日は 86400 秒です。 --lifetime-seconds オプションが指定されていない場合、アクセストークンは無期限に設定されます (推奨されません)。
- --comment: <comment> をアクセストークンの目的に関する意味のあるコメントに置き換えます。 --commentオプションが指定されていない場合、コメントは生成されません。
- --profile-name: <profile-name> を、Databricks サービスプリンシパルとターゲットワークスペースの認証情報を含む Databricks 構成プロファイルの名前に置き換えます。-p オプションが指定されていない場合、Databricks CLI は DEFAULTという名前の構成プロファイルを検索して使用しようとします。
応答で、 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プリンシパルの別のアクセストークンが生成されます。

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

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

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