トークン認証を使用して API Databricks アプリに接続する

OAuth 2.0 ベアラー トークン認証を使用して、HTTP API を公開する Databricks アプリ (FastAPI アプリや Gradio アプリなど) を呼び出すことができます。この方法は、ローカル開発環境、外部アプリケーション、その他の Databricks アプリから機能します。

注記

このメソッドは、 APIまたはエンドポイントを公開するアプリ（ /api/ルートを使用してアクセス可能）にのみ適用されます。 ユーザー インターフェースまたはバックグラウンド処理のみを提供するアプリの場合、トークン認証を使用して接続することはできません。

要件

トークン認証を使用して Databricks アプリに接続するには、次の要件を満たす必要があります。

• アプリは、 /api/ルートを使用してアクセス可能な API エンドポイントを少なくとも 1 つ公開する必要があります。
• アプリに対するCAN USE権限が必要です。「Databricks アプリのアクセス許可を構成する」を参照してください。
• サポートされている認証方法のいずれかを使用してDatabricksアクセスを生成できる必要があります。

認証方法

接続シナリオに一致する認証方法を選択します。

ローカルでの開発

ローカル開発環境から接続するには、ユーザー資格情報を使用して Databricks CLI または SDK を使用します。

1. CLI でログインします。

   Bash

   databricks auth login --host https://<workspace-url> --profile my-env

   Databricks では、OAuth ユーザー対マシン (U2M) 認証の使用を推奨しています。

2. アクセス許可を生成する:

CLI

Bash

databricks auth token --profile my-env

Python

Python

from databricks.sdk.core import Config
config = Config(profile="my-env")
token = config.oauth_token().access_token

外部アプリケーション

外部アプリケーションからプログラムによるアクセスの場合は、マシン間 (M2M) 資格情報を使用したサービスプリンパルシ認証を使用します。 OAuthを使用したDatabricksへのサービスプリンシパル アクセスの承認を参照してください。

1. サービスプリンシパルを作成し、クライアントIDとシークレットを取得します。 「サービスシプリンパル」を参照してください。

2. Databricks SDKを使用してアクセストークンを生成します。

   Python

   from databricks.sdk import WorkspaceClient
   import requests
   
   # Option 1: Explicit credentials
   wc = WorkspaceClient(
       host="https://<workspace-url>",
       client_id="<service-principal-client-id>",
       client_secret="<service-principal-client-secret>"
   )
   
   # Option 2: Environment variables
   # Set DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET
   wc = WorkspaceClient()
   
   # Generate Bearer token
   headers = wc.config.authenticate()

他のDatabricksアプリから

あるDatabricksアプリから別の Databricks アプリに接続すると、アプリは割り当てられたサービスプリンシパルを使用して認証を自動的に処理します。

Python

from databricks.sdk import WorkspaceClient
import requests

# No explicit credentials needed, uses app's service principal
wc = WorkspaceClient()
headers = wc.config.authenticate()

Databricksノートブックから

DatabricksノートブックからアプリAPI呼び出すには、ノートブックの内部セキュリティを対象ユーザーを対象としたOAuthセキュリティと交換し、そのセキュリティ ノートを使用してアプリにクエリを実行する必要があります。

1. アプリのOAuthクライアントIDを取得します。Databricks SDKを使用してIDを取得します。

   Python

   from databricks.sdk import WorkspaceClient
   
   w = WorkspaceClient()
   app_client_id = w.apps.get("<app-name>").oauth2_app_client_id

2. ノートブックトークンを、オーディエンススコープのアクセストークンと交換します。

   Python

   import requests
   
   url = "https://<workspace-url>/oidc/v1/token"
   notebook_token = (
       dbutils.notebook.entry_point.getDbutils()
       .notebook().getContext().apiToken().get()
   )
   
   data = {
       "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
       "subject_token": notebook_token,
       "subject_token_type": "urn:databricks:params:oauth:token-type:personal-access-token",
       "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
       "scope": "all-apis",
       "audience": app_client_id,
   }
   
   response = requests.post(url=url, data=data)
   audience_token = response.json()["access_token"]

3. アプリを呼び出すには、ベアラートークンとしてaudience_tokenを使用してください。例については、 「アプリにリクエストを送信する」を参照してください。

注記

交換された は特定のアプリにスコープされているため、他のDatabricks APIs呼び出すために使用することはできません。 社内交換リクエストのscope問題は、ユーザー認証でアプリに設定されたスコープと一致するか、そのスーパーセットである必要があります。

ユーザー認証の OAuth スコープを指定する

アプリがユーザー認証を使用する場合、アクセストークンには、アプリ用に設定されているスコープの上位集合となるスコープを含める必要があります。トークンに必要なスコープが含まれていない場合、リクエストは401または403エラーで失敗する可能性があります。

Databricks CLIを使用して生成されたトークンには、デフォルトでall-apisスコープが含まれており、これはあらゆるアプリのユーザー認証要件を満たします。

Bash

databricks auth token --profile my-env

all-apisの代わりに特定のスコープをリクエストするには、カスタムOAuthフローを使用して、明示的なスコープを使用して手動でアクセスをリクエストできます。 例えば、次のリクエストは、 sql 、 file.files 、 dashboards.genieスコープを持つアクセストークンを明示的に要求しています。

Bash

curl --request POST \
https://<databricks-instance>/oidc/v1/token \
--data "client_id=databricks-cli" \
--data "grant_type=authorization_code" \
--data "redirect_uri=<redirect-url>" \
--data "code_verifier=<code-verifier>" \
--data "code=<authorization-code>" \
--data "scope=sql+file.files+dashboards.genie"

完全な手順については、 OAuth U2M アクセスを手動で生成する」を参照してください。

アプリにリクエストを送信する

アプリの API エンドポイントを呼び出すときは、Authorization ヘッダーに Bearer トークンを含め、 <your-endpoint>アプリの実際の API パスに置き換えます。

CURL

Bash

curl "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>" \
     -H "Authorization: Bearer <YOUR_TOKEN>"

Python with requests

Python

import requests

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers={"Authorization": f"Bearer {token}"}
)

Python with SDK

Python

from databricks.sdk import WorkspaceClient
import requests

wc = WorkspaceClient()
headers = wc.config.authenticate()

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers=headers
)

セキュリティに関する考慮事項

ローカル環境からアプリに接続する場合は、次のセキュリティのベスト プラクティスに従ってください。

• ソースコードにアクセストークンをハードコーディングしないでください。 環境変数または安全な資格情報ストアを使用します。
• トークンが侵害された場合のセキュリティ リスクを最小限に抑えるため、トークンを定期的に更新します。
• アプリケーション ログにアクセス ネットワークや機密データを記録しないようにします。

トラブルシューティング

ローカル マシンからアプリに接続するときに問題が発生した場合は、これらのソリューションを試してください。

認証失敗（401エラー）

次の点を確認してください。

• トークンは有効です (実行databricks auth token --profile my-env )
• プロフィールは正しく設定されています databricks auth login
• トークンの有効期限は切れていません
• お客様のトークンには、必要なOAuthスコープが含まれています。トークンのスコープは、ユーザー認証でアプリ用に設定されているスコープのスーパーセットである必要があります。

権限が拒否されました（403 エラー）

次の点を確認してください。

• アプリに対するCAN USE権限があります
• トークンには必要な OAuth スコープが含まれています。スコープが不十分な場合、有効な権限があっても 403 エラーが発生する可能性があります。

アプリが見つかりません（404エラー）

次の点を確認してください。

• IDとワークスペースURLは正しいです
• アプリがデプロイされ実行されている
• エンドポイントパスはアプリ内に存在します

ネットワーク接続の問題

次の点を確認してください。

• ネットワークではアウトバウンドHTTPS接続が許可されています
• *.databricksapps.comドメインはネットワークからアクセス可能です

さらに、組織が構成を必要とするプロキシを使用しているかどうかを確認します。

追加リソース

詳細については、次のリソースを参照してください。

• クックブック: ローカルマシンから接続する
• クックブック: 外部アプリケーションからの接続
• クックブック: 他のアプリから接続する
• Databricks アプリの権限を構成する
• Databricks アプリのワークスペースと開発環境をセットアップする
• Databricks CLIの認証
• Databricks統合認証