Databricksにおけるパーソナルアクセストークンの管理

[Manage personal access tokens \| Databricks on AWS](https://docs.databricks.com/administration-guide/access-control/tokens.html) [2023/1/31時点]の翻訳です。

:::note warn
本書は抄訳であり内容の正確性を保証するものではありません。正確な内容に関しては原文を参照ください。
:::

# 要件

Databricks REST APIに対する認証を行うために、ユーザーはパーソナルアクセストークンを作成し、REST APIのリクエストで使用することができます。トークンにはオプションの有効期限があり、無効化することができます。[Databricksパーソナルアクセストークンを用いた認証](https://qiita.com/taka_yayoi/items/fa7f10bc80475c513383)をご覧ください。

ユーザーあたりのパーソナルアクセストークンの数は、[ワークスペース](https://docs.databricks.com/workspace/index.html)ごとに600個に制限されています。

:::note warn
**重要！**
ユーザー名とパスワード(ネイティブの認証)ではなくトークンベースのREST認証を強く推奨します。
:::

2018年1月以降に作成されたすべてのDatabricksアカウントにおいて、トークンベースを作成する機能はデフォルトで有効化されています。ワークスペースの管理者は、いつワークスペースが作成されたのかに関係なく、任意のワークスペースでパーソナルアクセストークンを作成する機能を有効化、無効化することができます。

ワークスペースでパーソナルアクセストークンを作成する機能が有効化されている場合、ワークスペース管理者は、トークンを監視し、どの非管理者ユーザーがトークンを作成、使用できるのかを管理し、新規トークンにおける最大有効期限を設定することもできます。

ワークスペースでパーソナルアクセストークンを生成する機能が[有効化](#ワークスペースにおけるトークンベースの認証の有効化無効化)されると、デフォルトではDatabricksワークスペースのすべてのユーザーがDatabricks REST APIにアクセスするためにパーソナルアクセストークンを生成することができ、無期限のトークンを含み好きな有効期限でトークンを生成することができます。

Databricks管理者としては、よりきめ細かいレベルでトークン使用をコントロールするために、[Token Management API 2\.0](https://docs.databricks.com/dev-tools/api/latest/token-management.html)や[Permissions API 2\.0](https://docs.databricks.com/dev-tools/api/latest/permissions.html)を活用することができます。これらのAPIはそれぞれのワークスペースインスタンスで公開されています。どのようにAPIにアクセスし、認証を受けるのかに関しては、[Databricksパーソナルアクセストークンを用いた認証](https://qiita.com/taka_yayoi/items/fa7f10bc80475c513383)をご覧ください。Databricks管理者としてAPIにアクセスする必要がありまうs。

いくつかのタスクに関しては、管理コンソールを活用することもできます。

以下の表では、ウェブアプリケーションを用いて実行できるタスクと、REST APIを用いて実行できるタスクを示しています。Yesとなっているセルに関しては、関連ドキュメントを参照するために単語をクリックしてください。

| タスク | 説明 | 管理コンソール | REST API |
|:--|:--|:--|:--|
| 有効化/無効化  | 当該ワークスペースですべてのトークンを有効化、無効化します。  | [Yes](#ワークスペースにおけるトークンベースの認証の有効化無効化)  | [Yes](#ワークスペースにおけるトークンベースの認証の有効化無効化)  |
| トークンを使用できるユーザーの制御  |  当該ワークスペースで特定のユーザー、グループにパーソナルアクセストークンの作成と利用を制限します。トークンの作成、使用権限を剥奪すると、そのユーザーの既存のトークンも削除されます。 | [Yes](#管理コンソールを用いたトークン権限の管理)  |  [Yes](#permissions-apiを用いたトークン権限の管理) |
| 新規トークンの最大有効期限  |  当該ワークスペースにおける新規トークンの最大有効期限を設定します。 | No  | [Yes](#新規トークンの最大有効期限の設定rest-apiのみ)  |
| 既存トークンの管理  |  既存のトークンに対して、トークンの作成者、有効期限、トークンの説明文を取得します。Databricks APIにアクセスする必要のないユーザーからトークンの権限を剥奪します。トークン作成を監視、制御することで、ワークスペースからのデータ漏洩を引き起こす長期間存在し続けるトークンやトークンの紛失のリスクを軽減します。 | No  | [Yes](#トークンの監視および無効化rest-apiのみ)   |

管理とトークンの利用においてREST APIを用いたトークン管理の典型的なフローに関しては以下の図をご覧ください。管理コンソールを使用できる一連のタスクに関するトピックについては上の表をご覧ください。
![](https://docs.databricks.com/_images/token-management.png)

# 要件

この機能を使用するには[プレミアムプラン以上](https://databricks.com/jp/product/aws-pricing)が必要です。

# ワークスペースにおけるトークンベースの認証の有効化、無効化

2018年以降に作成されたすべてのDatabricksワークスペースでは、デフォルトでトークンベースの認証が有効化されています。管理コンソールでこの設定を変更することができます。トークンを使用できるユーザーを指定するには、[トークンを使用、作成できるユーザーのコントロール](#トークンを使用作成できるユーザーのコントロール)をご覧ください。

:::note alert
**警告！**
[Partner Connect](https://docs.databricks.com/partner-connect/index.html)、[パートナー連携](https://docs.databricks.com/partners/partners.html)、[サービスプリンシパル](https://docs.databricks.com/administration-guide/users-groups/service-principals.html)を使用する際には、ワークスペースでトークンが有効化されている必要があります。
:::

ワークスペースでパーソナルアクセストークンを作成する機能を無効化するには以下を実行します。

1. 管理コンソールに移動します。
1. **Workspace Settings**タブをクリックします。
1. **Personal Access Tokens**トグルをクリックします。
1. **Confirm**をクリックします。変更が反映されるまでには数秒要します。

REST APIリクエストに対するトークンベースの認証を使用するには、[Databricksパーソナルアクセストークンを用いた認証](https://qiita.com/taka_yayoi/items/fa7f10bc80475c513383)をご覧ください。

ワークスペースでトークンベースの認証を無効化した際にトークンは削除されません。トークンの機能を後で有効化すると、有効期限が切れていないトークンはすぐに利用できるようになります。

特定のユーザーに対してトークンの使用を無効化したい場合には、ワークスペースでトークンベースの認証を有効にしつつも、ユーザーとグループに対してきめ細かい権限を設定することができます。[トークンを使用、作成できるユーザーのコントロール](#トークンを使用作成できるユーザーのコントロール)をご覧ください。

また、この変更を行うためにREST APIを使用することもできます。ワークスペースでトークン管理機能を有効化、無効化するには、[workspace configuration for tokens API](https://docs.databricks.com/dev-tools/api/latest/token-management.html#operation/set-configuration)(`PATCH /workspace-conf`)を呼び出します。JSONリクエストのボディで、`enableTokensConfig`を`true`(有効)あるいは`false`(無効)を指定します。

機能を有効化するには以下のようにします。

```bash:Bash
curl -X PATCH -n \
  https://<databricks-instance>/api/2.0/workspace-conf \
  -d '{
    "enableTokensConfig": "true",
    }'
```

# トークンを使用、作成できるユーザーのコントロール

ユーザーは以下のいずれかのトークン権限を持ちます。

- **No permissions**
- **Can Use** - ユーザーがパーソナルアクセストークンを使えるかどうか。Databricksプラットフォームバージョン3.28 (Sept 9-15, 2020)リリース以降に作成されたワークスペースでは、デフォルトでは非管理者ユーザーやグループにCan Use権限が付与されていません。管理者は明示的にユーザーやグループ、あるいはすべてのユーザーを表す`users`グループにCan Use権限を付与する必要があります。

    :::note warn
    **重要！**
    3.28リリース以前に作成されたワークスペースでは、設定されている権限が維持されます。以前のデフォルトは全ユーザーがCan Use権限を持つというものでした。管理者はグループ権限を剥奪し、別のグループや非管理ユーザーに権限を付与することができます。[トークン権限の剥奪](#トークン権限の剥奪)をご覧ください。
  :::

- **Can Manage** - ユーザーやグループがパーソナルアクセストークンと権限を管理できるかどうか。`admins`グループのユーザーはデフォルトでこの権限を持ち、これを剥奪することはできません。ほかのグループにこの権限を付与することができます。APIはこれらのルールを強制します。

以下のテーブルでは、トークンに関係するタスクそれぞれで必要となる権限を一覧しています。

| タスク | No permissions | Can Use | Can Manage |
|:--|:--|:--|:--|
| トークンの作成  | -  |  Yes | Yes  |
| 認証でトークンを使用  | -  |  Yes |  Yes |
| 自分のトークンの削除  |  - | Yes  | Yes  |
| すべてのユーザーのトークンの削除 ** |  - | -  |  Yes |
| すべてのトークンの一覧 ** | -  | -  | Yes  |
| トークンアクセス権の変更 *** | -  | -  |  Yes |

** でマークされているアクションでは[Token Management API 2\.0](https://docs.databricks.com/dev-tools/api/latest/token-management.html)が必要です。

*** でマークされているアクションは管理コンソールあるいは[Permissions API 2\.0](https://docs.databricks.com/dev-tools/api/latest/permissions.html)で実行することができます。[トークンを使用、作成できるユーザーのコントロール](#トークンを使用作成できるユーザーのコントロール)をご覧ください。

## 管理コンソールを用いたトークン権限の管理

管理コンソールを用いてワークスペースのトークン権限を管理するには、以下の手順を踏みます。

1. [管理コンソール](https://docs.databricks.com/administration-guide/admin-console.html)に移動します。
1. **Workspace Settings**タブをクリックします。
1. トークン権限エディタを開くために**Personal Access Tokens**の隣にある**Permissions**ボタンをクリックします。
1. 権限を追加、削除、更新します。権限の意味やワークスペースにおけるデフォルトの権限に関しては、[トークンを使用、作成できるユーザーのコントロール](#トークンを使用作成できるユーザーのコントロール)をご覧ください。

    `users`グループにCan Use権限があり、非管理者ユーザーに対してより細かい権限を適用したい場合には、**users**の行の隣にある権限ドロップダウンの隣の**X**をクリックし、**users**グループから**Can Use**権限を削除します。

    他のエンティティに権限を許可するには、アクセスを許可したいユーザーやグループを選択します。**Select User or Group…** ドロップダウンからユーザーやグループを選択し、**Can Use**を選択し、**+ Add**ボタンをクリックします。以下の例では、管理者が**users**グループからアクセス権を削除し、Data Science B2グループにアクセス権を付与しています。
![](https://docs.databricks.com/_images/tokens-permissions-editor-notallusers.png)

1. 変更を保存するために**Save**をクリックします。

:::note alert
**警告！**
変更を保存したあとは、Can UseやCan Manage権限をこれまで有していたユーザーはトークンベースの認証へのアクセスを拒否され、彼らのアクティブなトークンは即座に削除されます。削除されたトークンを取得することはできません。
:::

## Permissions APIを用いたトークン権限の管理

### ワークスペースのすべてのトークン権限の取得

すべてのDatabricksユーザー、Databricksグループ、Databricksサービスプリンシパルのトークン権限を取得するには、ワークスペースのすべてのトークン県花を取得するために、[get\-tokens\-permissions](https://docs.databricks.com/dev-tools/api/latest/permissions.html#operation/get-tokens-permissions)を呼び出します。([Permissions API](https://docs.databricks.com/dev-tools/api/latest/permissions.html)のドキュメントに記載されているように`GET /permissions/authorization/tokens`などを呼び出します)

レスポンスには配列`access_control_list`が含まれます。それぞれの要素はユーザーオブジェクト、グループオブジェクト、サービスプリンシパルオブジェクトとなります。それぞれには、タイプに適したアイデンティティフィールドが含まれます。ユーザーは`user_name`フィールド、グループは`group_name`フィールド、サービスプリンシパルには`service_principal_name`フィールドが含まれます。すべての要素には許可されている権限レベル(`CAN_USE`か`CAN_MANAGE`)を示す`all_permissions`フィールドがあります。

例えば、

```bash:Bash
curl -n -X GET "https://<databricks-instance>/api/2.0/preview/permissions/authorization/tokens"
```

レスポンスは以下のようになります。

```json:JSON
{
  "object_id": "authorization/tokens",
  "object_type": "tokens",
  "access_control_list": [
    {
      "user_name": "jsmith@example.com",
      "all_permissions": [
        {
          "permission_level": "CAN_USE",
          "inherited": false
        }
      ]
    }
  ]
}
```

### トークン権限の設定

トークン権限を設定するには、[Update token permissions for a specific entity API](https://docs.databricks.com/dev-tools/api/latest/permissions.html#operation/set-tokens-permissions)を呼び出します(`PATCH /permissions/authorization/tokens`)。

1つ以上のユーザー、グループ、サービスプリンシパルに対して権限を設定することができます。それぞれのユーザーに対して、`user_name`リクエストプロパティで指定するメールアドレスを知っている必要があります。それぞれのグループに対して、`group_name`リクエストプロパティでグループ名を指定します。それぞれのサービスプリンシパルに対して、`service_principal_name`プロパティでサービスプリンシパルの`applicationId`を指定します。

明示的に記述されない(ユーザーやグループのような)エンティティは、このリクエストによる直接の影響はありませんが、グループのメンバーに対する変更は間接的にユーザーアクセスに影響を与えます。

このAPIでは許可を行うことだけができ、権限の剥奪を行うことはできません。

以下の例では、ユーザー`jsmith@example.com`とグループ`mygroup`にアクセス権を付与しています。

```bash:Bash
curl -n -X PATCH "https://<databricks-instance>/api/2.0/preview/permissions/authorization/tokens" \
  -d '{
    "access_control_list": [
      {
        "user_name": "jsmith@example.com",
        "permission_level": "CAN_USE",
      },
      {
        "group_name": "mygroup",
        "permission_level": "CAN_USE",
      }
    ]
  }'
```

レスポンスは以下のようになります。

```json:JSON
{
  "access_control_list": [
    {
      "user_name": "jsmith@example.com",
      "all_permissions": [
        {
          "permission_level": "CAN_USE",
          "inherited": false
        }
      ]
    },
    {
      "group_name": "mygroup",
      "all_permissions": [
        {
          "permission_level": "CAN_USE",
          "inherited": false
        }
      ]
    }
  ]
}
```

一つのリクエストでワークスペースのすべてのエンティティに対するトークン権限を設定したい場合には、[Replace all token permissions for workspace API](https://docs.databricks.com/dev-tools/api/latest/permissions.html#operation/update-tokens-permissions)(`PUT /permissions/authorization/tokens`)を使用します。[トークン権限の剥奪](#トークン権限の剥奪)をご覧ください。

### トークン権限の剥奪

:::note
**注意**
Databricksプラットフォームバージョン3.28 (Sept 9-15, 2020)のリリース以降に作成されたワークスペースでは、デフォルトではユーザーはCan Use権限を持ちません。管理者は明示的に`users`グループ全体あるいはユーザー毎、グループ毎にこれらの権限を付与しなくてはなりません。3.28以前に作成されたワークスペースでは設定されている権限を維持します。デフォルトは全ユーザーがCan Use権限を持つというものでした。管理者はグループのアクセス権を削除し、別のグループや非管理ユーザーに権限を付与することができます。
:::

すべての非管理者ユーザー、一部の非管理者ユーザーから権限を剥奪するには、ワークスペース全体で権限が付与されているすべてのオブジェクトに対する権限の完全なセットを指定する必要がある[Replace all token permissions for workspace API](https://docs.databricks.com/dev-tools/api/latest/permissions.html#operation/update-tokens-permissions)(`PUT /permissions/authorization/tokens`)を使用します。

非管理者ユーザーのサブセットにトークンの作成、使用を許可したい場合には、以下の3つすべてを行います。

- ユーザー、グループ、サービスプリンシパルに`CAN_USE`権限を**付与**します。
- 一部の非管理者ユーザーにのみ許可したい場合には、ビルトインの`users`グループには`CAN_USE`権限を**付与しません**。
- ビルトインの`admins`グループに`CAN_MANAGE`を**付与**します。これはAPIの要件です。

:::note alert
**警告！**
リクエストが成功すると、直接トークン権限を持たない、あるいはグループを通じて間接的な権限を持たないユーザーやサービスプリンシパルのトークンは即座に削除されます。削除されたトークンを取得することはできません。
:::

以下の例では、`field-automation-group`グループに`CAN_USE`権限を付与し、`users`(全ユーザー)グループの権限を除外し、APIの要件である`admins`グループへの`CAN_MANAGE`を付与しています。`field-automation-group`グループに属していないすべての非管理者ユーザーはトークン作成の権限を失い、既存のトークンは即座に削除(剥奪)されます。

```bash:Bash
curl -n -X PUT "https://<databricks-instance>/api/2.0/preview/permissions/authorization/tokens" \
  -d '{
    "access_control_list": [
      {
        "group_name": "field-automation-group",
        "permission_level": "CAN_USE",
      },
      {
        "group_name": "admins",
        "permission_level": "CAN_MANAGE",
      },
    ]
  }'
```

# 新規トークンの最大有効期限の設定(REST APIのみ)

ワークスペースにおける新規トークンの最大有効期限を管理するために[workspace configuration for tokens APIs](https://docs.databricks.com/dev-tools/api/latest/token-management.html#tag/Workspace-configuration-for-tokens)を使用します。

新規トークンの最大有効期限を設定するには、[Set the maximum token lifetime for new tokens API](https://docs.databricks.com/dev-tools/api/latest/token-management.html#operation/set-configuration)(`PATCH /workspace-conf`)をコールします。新規トークンの最大有効期限を整数値の日数で`maxTokenLifetimeDays`に設定します。ゼロにセットすると、有効期限のない新規トークンの作成を許可します。

例は以下のようになります。

```bash:Bash
curl -n -X PATCH "https://<databricks-instance>/api/2.0/workspace-conf" \
  -d '{
  "maxTokenLifetimeDays": "90"
  }'
```

:::note alert
**警告！**
この制限は新規トークンにのみ適用されます。既存のトークンを確認するには、[get tokens API](https://docs.databricks.com/dev-tools/api/latest/token-management.html#operation/get-tokens)を使用してください。
:::

ワークスペースにおける新規トークンの最大有効期間を取得するには、[workspace configuration for tokens API](https://docs.databricks.com/dev-tools/api/latest/token-management.html#operation/get-configuration)(`GET /workspace-conf`)をコールし、クエリーパラメーターとして`keys=maxTokenLifetimeDays`を指定します。レスポンスの`maxTokenLifetimeDays`プロパティには、新規トークンの最大有効期間が整数値の日付が含まれます。ゼロの場合、有効期限がない新規トークンの作成が許可されています。

例えば、

```bash:Bash
curl -n -X GET "https://<databricks-instance>/api/2.0/workspace-conf?keys=maxTokenLifetimeDays"
```

は、以下のようなレスポンスを返します。

```json:JSON
{
    "maxTokenLifetimeDays": "90"
}
```

# トークンの監視および無効化(REST APIのみ)

ワークスペースの既存のトークンを管理するために[token management APIs](https://docs.databricks.com/dev-tools/api/latest/token-management.html#tag/Token-management)を使用します。

## ワークスペースのトークンの取得

ワークスペースのトークンを取得するには、[get all tokens API](https://docs.databricks.com/dev-tools/api/latest/token-management.html#operation/get-tokens)(`GET /token-management/tokens`)を使用します。レスポンスには配列`token_infos`が含まれます。それぞれの要素はトークンを表現し、ID(`token_id`)、作成時刻(`creation_time`)、有効期限切れのタイミング(`expiry_time`)、説明文(`comment`)、作成者(IDの`created_by_id`あるいはユーザー名の`created_by_username`)を含んでいます。

[SCIM get user API](https://docs.databricks.com/dev-tools/api/latest/scim/scim-users.html)(`GET /scim/v2/Users/{id}`)を用いることでユーザーに関する詳細情報を取得することができます。

ユーザーで結果をフィルタリングするには、リクエストボディのプロパティ`created_by_id`(ID)あるいは`created_by_username`(ユーザー名)を設定します。[SCIM get users API](https://docs.databricks.com/dev-tools/api/latest/scim/scim-users.html)(`GET /scim/v2/Users`)を用いることで表示名からユーザーIDを取得することができます。

例えば、

```bash:Bash
curl -n -X GET "https://<databricks-instance>/api/2.0/token-management/tokens" \
  -d '{
  "created_by_id": "1234567890"
  }'
```

の結果は以下のようになります。

```json:JSON
{
  "token_infos": [
    {
      "token_id": "<token-id>",
      "creation_time": 1580265020299,
      "expiry_time": 1580265020299,
      "comment": "This is for ABC division's automation scripts.",
      "created_by_id": 1234567890,
      "created_by_username": "jsmith@example.com"
    }
  ]
}
```

あるいは、[get a token API](https://docs.databricks.com/dev-tools/api/latest/token-management.html#operation/get-token)(`GET /token-management/tokens/{token_id}`)を用いて特定のトークンを取得することができます。

## トークンの削除(剥奪)

1. トークンIDを特定します。[ワークスペースのトークンの取得](#ワークスペースのトークンの取得)をご覧ください。
1. [delete a token API](https://docs.databricks.com/dev-tools/api/latest/token-management.html#operation/delete-token)(`DELETE /token-management/tokens`)をコールします。パスにトークンIDを指定します。

```bash:Bash
curl -n -X DELETE "https://<databricks-instance>/api/2.0/token-management/tokens/<token-id>"
```

# Terraform連携

以下のように、[Databricks Terraformプロバイダー](https://qiita.com/taka_yayoi/items/691ee4909b0961de5ad1)と[databricks\_permissions](https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/permissions#token-usage)を用いることで、完全に自動化された環境で権限を管理することができます。

:::note alert
**警告！**
以下の設定には`authorization = "tokens"`という文が含まれています。Databricksワークスペースごとには1つの`authorization = "tokens"`権限リソースが許容されます。そうでない場合、恒久的な設定ドリフトが発生します。以下の変更を適用したあと、以前`CAN_USE`あるいは`CAN_MANAGE`権限を有していたユーザーは、トークンベースの認証の権限を失います。彼らのアクティブなトークンは即座に削除(剥奪)されます。
:::

```terraform:Terraform
resource "databricks_group" "auto" {
  display_name = "Automation"
}

resource "databricks_group" "eng" {
  display_name = "Engineering"
}

resource "databricks_permissions" "token_usage" {
  authorization = "tokens"

  access_control {
    group_name       = databricks_group.auto.display_name
    permission_level = "CAN_USE"
  }

  access_control {
    group_name       = databricks_group.eng.display_name
    permission_level = "CAN_USE"
  }
}
```

### Databricks 無料トライアル

[Databricks 無料トライアル](https://databricks.com/jp/try-databricks)