LoginSignup
0
0

More than 1 year has passed since last update.

@taka_yayoi(Takaaki Yayoi)inデータブリックス・ジャパン株式会社

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

Last updated at Posted at 2023-02-13

Manage personal access tokens | Databricks on AWS [2023/1/31時点]の翻訳です。

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

要件

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

ユーザーあたりのパーソナルアクセストークンの数は、ワークスペースごとに600個に制限されています。

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

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

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

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

Databricks管理者としては、よりきめ細かいレベルでトークン使用をコントロールするために、Token Management API 2.0やPermissions API 2.0を活用することができます。これらのAPIはそれぞれのワークスペースインスタンスで公開されています。どのようにAPIにアクセスし、認証を受けるのかに関しては、Databricksパーソナルアクセストークンを用いた認証をご覧ください。Databricks管理者としてAPIにアクセスする必要がありまうs。

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

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

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

管理とトークンの利用においてREST APIを用いたトークン管理の典型的なフローに関しては以下の図をご覧ください。管理コンソールを使用できる一連のタスクに関するトピックについては上の表をご覧ください。

要件

この機能を使用するにはプレミアムプラン以上が必要です。

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

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

警告！
Partner Connect、パートナー連携、サービスプリンシパルを使用する際には、ワークスペースでトークンが有効化されている必要があります。

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

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

REST APIリクエストに対するトークンベースの認証を使用するには、Databricksパーソナルアクセストークンを用いた認証をご覧ください。

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

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

また、この変更を行うためにREST APIを使用することもできます。ワークスペースでトークン管理機能を有効化、無効化するには、workspace configuration for tokens API(PATCH /workspace-conf)を呼び出します。JSONリクエストのボディで、enableTokensConfigをtrue(有効)あるいはfalse(無効)を指定します。

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

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権限を付与する必要があります。

    重要！
    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が必要です。

*** でマークされているアクションは管理コンソールあるいはPermissions API 2.0で実行することができます。トークンを使用、作成できるユーザーのコントロールをご覧ください。

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

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

  1. 管理コンソールに移動します。

  2. Workspace Settingsタブをクリックします。

  3. トークン権限エディタを開くためにPersonal Access Tokensの隣にあるPermissionsボタンをクリックします。

  4. 権限を追加、削除、更新します。権限の意味やワークスペースにおけるデフォルトの権限に関しては、トークンを使用、作成できるユーザーのコントロールをご覧ください。

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

    他のエンティティに権限を許可するには、アクセスを許可したいユーザーやグループを選択します。Select User or Group… ドロップダウンからユーザーやグループを選択し、Can Useを選択し、+ Addボタンをクリックします。以下の例では、管理者がusersグループからアクセス権を削除し、Data Science B2グループにアクセス権を付与しています。

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

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

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

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

すべてのDatabricksユーザー、Databricksグループ、Databricksサービスプリンシパルのトークン権限を取得するには、ワークスペースのすべてのトークン県花を取得するために、get-tokens-permissionsを呼び出します。(Permissions APIのドキュメントに記載されているようにGET /permissions/authorization/tokensなどを呼び出します)

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

例えば、

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

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

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を呼び出します(PATCH /permissions/authorization/tokens)。

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

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

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

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

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
{
  "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(PUT /permissions/authorization/tokens)を使用します。トークン権限の剥奪をご覧ください。

トークン権限の剥奪

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

すべての非管理者ユーザー、一部の非管理者ユーザーから権限を剥奪するには、ワークスペース全体で権限が付与されているすべてのオブジェクトに対する権限の完全なセットを指定する必要があるReplace all token permissions for workspace API(PUT /permissions/authorization/tokens)を使用します。

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

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

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

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

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を使用します。

新規トークンの最大有効期限を設定するには、Set the maximum token lifetime for new tokens API(PATCH /workspace-conf)をコールします。新規トークンの最大有効期限を整数値の日数でmaxTokenLifetimeDaysに設定します。ゼロにセットすると、有効期限のない新規トークンの作成を許可します。

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

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

警告！
この制限は新規トークンにのみ適用されます。既存のトークンを確認するには、get tokens APIを使用してください。

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

例えば、

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

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

JSON
{
    "maxTokenLifetimeDays": "90"
}

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

ワークスペースの既存のトークンを管理するためにtoken management APIsを使用します。

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

ワークスペースのトークンを取得するには、get all tokens API(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(GET /scim/v2/Users/{id})を用いることでユーザーに関する詳細情報を取得することができます。

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

例えば、

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

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

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(GET /token-management/tokens/{token_id})を用いて特定のトークンを取得することができます。

トークンの削除(剥奪)

  1. トークンIDを特定します。ワークスペースのトークンの取得をご覧ください。
  2. delete a token API(DELETE /token-management/tokens)をコールします。パスにトークンIDを指定します。
Bash
curl -n -X DELETE "https://<databricks-instance>/api/2.0/token-management/tokens/<token-id>"

Terraform連携

以下のように、Databricks Terraformプロバイダーとdatabricks_permissionsを用いることで、完全に自動化された環境で権限を管理することができます。

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

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 無料トライアル

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0