Databricksパーソナルアクセストークンを用いた認証

[Authentication using Databricks personal access tokens \| Databricks on AWS](https://docs.databricks.com/dev-tools/api/latest/authentication.html) [2022/12/6時点]の翻訳です。

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

Databricks REST APIの認証を受け、APIにアクセスするために、Databricksパーソナルアクセストークンあるいはパスワードを使用することができます。トークンを使用することを強くお勧めします。

:::note warn
**重要！**
認証フローにおいてトークンはパスワードを置き換えるものとなるので、パスワードのようにトークンも保護されなくてはなりません。トークンを保護するために、トークンを以下の場所に格納することをお勧めします。

- [シークレットを管理](https://qiita.com/taka_yayoi/items/338ef0c5394fe4eb87c0)し、ノートブックで[シークレットユーティリティ(dbutils.secrets)](https://qiita.com/taka_yayoi/items/3717623187859809515d#%E3%82%B7%E3%83%BC%E3%82%AF%E3%83%AC%E3%83%83%E3%83%88%E3%83%A6%E3%83%BC%E3%83%86%E3%82%A3%E3%83%AA%E3%83%86%E3%82%A3dbutilssecrets)を用いてトークンを取得。
- ローカルキーを格納し、実行時にトークンを取得するために[Python keyring](https://pypi.org/project/keyring/)パッケージを使用。
:::

:::note
**注意**
セキュリティのベストプラクティスとして、自動化ツール、システム、スクリプト、アプリで認証を行う際、ワークスペースのユーザーではなく[サービスプリンシパル](https://docs.databricks.com/administration-guide/users-groups/service-principals.html)に属するアクセストークンを使用することをお勧めします。サービスプリンシパルのアクセストークンを作成するには、[Manage access tokens for a service principal](https://docs.databricks.com/administration-guide/users-groups/service-principals.html#personal-access-tokens)をご覧ください。
:::

# 要件

2018年1月以降に作成されたすべてのDatabricksアカウントにおいて、トークンベースの認証はデフォルトで有効化されています。トークンベースの認証が無効化されている場合、[Databricksにおけるパーソナルアクセストークンの管理](https://qiita.com/taka_yayoi/items/712170ba2f2c2bdf5d24)で説明されているタスクを実行する前に管理者は機能を有効化しなくてはなりません。

# パーソナルアクセストークンの生成

[Databricksパーソナルアクセストークン](https://qiita.com/taka_yayoi/items/f5493a4169e95e1a7a61#databricks%E3%83%91%E3%83%BC%E3%82%BD%E3%83%8A%E3%83%AB%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3)をご覧ください。

[Token API 2\.0](https://docs.databricks.com/dev-tools/api/latest/tokens.html)を用いてトークンの生成、廃棄を行うこともできます。

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

# パーソナルアクセストークンの廃棄

このセクションでは、Databricks UIによるパーソナルアクセストークンの廃棄方法を説明します。[Token API 2\.0](https://docs.databricks.com/dev-tools/api/latest/tokens.html)を用いてトークンの生成、廃棄を行うこともできます。

1. Databricksワークスペースのトップバーに表示されているご自身のユーザー名をクリックし、ドロップダウンから**User Settings**を選択します。
1. **Access Tokens**タブに移動します。
1. 廃棄したいトークンの**x**をクリックします。
1. トークン廃棄のダイアログで、**Revoke Token**ボタンをクリックします。

# Databricks REST APIにアクセスするためにパーソナルアクセストークンを使う

`.netrc`ファイルにパーソナルアクセストークンを格納し`curl`を使用するか、`Authorization: Bearer`ヘッダーにトークンを指定することができます。

## `.netrc`ファイルにトークンを格納し`curl`で使う

`machine`、`login`、`password`プロパティを持つ[\.netrc](https://everything.curl.dev/usingcurl/netrc)ファイルを作成します。

```ini:ini
machine <databricks-instance>
login token
password <token-value>
```

ここでは、

- `<databricks-instance>`はお使いのDatabricksデプロイメントの[ワークスペースURL](https://qiita.com/taka_yayoi/items/7127cabac70dd994fcba#%E3%83%AF%E3%83%BC%E3%82%AF%E3%82%B9%E3%83%9A%E3%83%BC%E3%82%B9%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%82%BF%E3%83%B3%E3%82%B9%E5%90%8Durlid)に含まれるインスタンスIDです。例えば、ワークスペースのURLが`https://abc-d1e2345f-a6b2.cloud.databricks.com`の場合、`<databricks-instance>`は`abc-d1e2345f-a6b2.cloud.databricks.com`です。
- `token`は文字列リテラルの`token`です。
- `<token-value>`は`dapi1234567890ab1cde2f3ab456c7d89efa`のようなトークンの値となります。

結果として以下のようになります。

```ini:ini
machine abc-d1e2345f-a6b2.cloud.databricks.com
login token
password dapi1234567890ab1cde2f3ab456c7d89efa
```

複数のマシン/トークンのエントリーがある場合、一行ごとにエントリーを記述し、同じ行にマシン/トークンごとの`machine`、`login`、`password`プロパティを記述します。これは以下のようになります。

```ini:ini
machine abc-d1e2345f-a6b2.cloud.databricks.com login token password dapi1234567890ab1cde2f3ab456c7d89efa
machine bcd-e2f3456a-b7c3.cloud.databricks.com login token password dapi2345678901cd2efa3b4cd567e8f90abc
machine cde-f3a4567b-c8d4.cloud.databricks.com login token password dapi3456789012de3fab4c5de678f9a01bcd
```

:::note warn
**重要！**
オプションとして、`login`にご自身のDatabrikcsユーザー名、`password`にDatabricksのパスワードを指定することができます。しかし、APIエンドポイントの認証を受けるにはパーソナルアクセストークンを使用することをお勧めします。ユーザー名とパスワードを使用する際、以下のように資格情報を引き渡すために`-u`を*使用しないでください*。

```bash:Bash
# これは **やめてください**
curl -u <your-username>:<your-password> -X GET https://<databricks-instance>/api/2.0/clusters/list
```
:::

以下のサンプルは、`curl`コマンドで`--netrc`(`-n`を使うこともできます)を用いて、`.netrc`ファイルを呼び出します。`.netrc`ファイルでマッチする`machine`エントリーを特定するために指定されたワークスペースURLを使用します。

```bash:Bash
curl --netrc -X GET https://abc-d1e2345f-a6b2.cloud.databricks.com/api/2.0/clusters/list
```

## `Bearer`認証にトークンを渡す

`Bearer`認証を用いたヘッダーにトークンを含めることができます。`curl`やあなたが開発する任意のクライアントでこのアプローチを活用することができます。後者に関しては、[大きなファイルをDBFSにアップロード](https://qiita.com/taka_yayoi/items/5f3fd1aaf9a4bf481b97#%E5%A4%A7%E3%81%8D%E3%81%AA%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%92dbfs%E3%81%AB%E3%82%A2%E3%83%83%E3%83%97%E3%83%AD%E3%83%BC%E3%83%89)をご覧ください。

以下の例では、特定のワークスペースで使用できるすべてのクラスターを一覧するために`Bearer`認証を用いています。

```bash:Bash
export DATABRICKS_TOKEN=dapi1234567890ab1cde2f3ab456c7d89efa

curl -X GET --header "Authorization: Bearer $DATABRICKS_TOKEN" \
https://abc-d1e2345f-a6b2.cloud.databricks.com/api/2.0/clusters/list
```

### Databricks 無料トライアル

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