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

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

Requirements

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

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

認証方法

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

ローカル開発

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

1. CLI を使用してログインします。

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

   Azure Databricksでは、OAuth ユーザー間 (U2M) 認証を使用することをお勧めします。

2. アクセス トークンを生成します。

   CLI

   databricks auth token --profile my-env
   

   Python

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

外部アプリケーション

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

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

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

   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 アプリ間で接続すると、割り当てられたサービス プリンシパルを使用して認証が自動的に処理されます。

from databricks.sdk import WorkspaceClient
import requests

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

Azure Databricks ノートブックから

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

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

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

2. 対象のオーディエンスのスコープに基づいたアクセス トークンを取得するために、ノートブック トークンを交換します。

   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 を使用します。 例については、「 アプリに要求を送信する」を参照してください。

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

アプリで ユーザー承認を使用する場合、アクセス トークンには、アプリ用に構成されたスコープのスーパーセットであるスコープが含まれている必要があります。 トークンに必要なスコープがない場合、要求は 401 エラーまたは 403 エラーで失敗する可能性があります。

Databricks CLI を使用して生成されたトークンには、既定で all-apis スコープが含まれています。これは、任意のアプリのユーザー承認要件を満たします。

databricks auth token --profile my-env

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

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 ヘッダーにベアラー トークンを含め、 <your-endpoint> をアプリの実際の API パスに置き換えます。

カール

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

要求を含むPython

import requests

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

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 ドメインにはネットワークからアクセスできます

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

その他のリソース

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

• クックブック: ローカル コンピューターから接続する
• Cookbook: 外部アプリケーションから接続する
• クックブック: 他のアプリから接続する
• Databricks アプリのアクセス許可を構成する
• Databricks Apps ワークスペースと開発環境を設定する
• Databricks CLI の認証
• Databricks 統合認証