Databricks CLI 的驗證

備註

Databricks CLI 的使用須遵循 Databricks 許可證 和 Databricks 隱私通知，包括任何使用資料條款。

本文說明如何在 Databricks CLI 與你的 Azure Databricks 帳號及工作區之間設定認證。 它假設你已經安裝了 Databricks 的 CLI。 請參閱 以安裝或更新 Databricks CLI。

在執行 Databricks CLI 指令之前，你必須為你計畫使用的帳號或工作區設定 認證 。 所需的設定取決於您要執行 工作區層級 命令、 帳戶層級 命令或兩者。

若要檢視可用的 CLI 命令群組，請執行 databricks -h。 如需對應 REST API 作業的清單，請參閱 Databricks REST API。

關於 Microsoft Entra 如何透過 Azure DevOps 驗證 Databricks 的詳細資訊，請參見 Azure Databricks 上的 Azure DevOps 驗證。

OAuth 機器對機器 (M2M) 身份驗證

使用 OAuth 的機器對機器 （M2M） 驗證可讓服務、腳本或應用程式存取 Databricks 資源，而不需要互動式使用者登入。 M2M 驗證不依賴個人存取權杖 （PAT） 或使用者認證，而是使用服務主體和 OAuth 用戶端認證流程來要求和管理權杖。

若要設定和使用 OAuth M2M 驗證：

1. 完成 OAuth M2M 驗證設定步驟。 請參見 使用 OAuth 授權服務主體存取至 Azure Databricks。

2. 在你的 檔案中建立一個 Azure Databricks .databrickscfg，並包含以下欄位。

   針對帳戶級別的指令

   [<some-unique-configuration-profile-name>]
   host          = <account-console-url>
   account_id    = <account-id>
   client_id     = <service-principal-client-id>
   client_secret = <service-principal-oauth-secret>
   

   針對工作區層級的命令

   [<some-unique-configuration-profile-name>]
   host          = <workspace-url>
   client_id     = <service-principal-client-id>
   client_secret = <service-principal-oauth-secret>
   

要使用配置檔案，請在 CLI 命令中通過 --profile 或 -p 標誌來傳遞。 例如：

databricks account groups list -p <profile-name>

在--profile 或-p 之後按 Tab 鍵，以顯示可用設定檔的清單。

OAuth 使用者對電腦 （U2M） 驗證

使用 OAuth 使用者對機器 （U2M） 驗證，您可以以互動方式登入，CLI 會代表您管理短期權杖。 OAuth 代幣會在一小時內過期，這降低了代幣意外暴露的風險。 請參見 利用 OAuth 授權用戶存取 Azure Databricks。

若要登入：

針對帳戶級別的指令

databricks auth login --host <account-console-url> --account-id <account-id>

針對工作區層級的命令

databricks auth login --host <workspace-url>

CLI 會引導您完成瀏覽器型登入流程。 完成時，CLI 會儲存一個包含你工作區主機和設定檔名稱的 設定檔 。 您可以接受建議的設定檔名稱或輸入您自己的設定檔名稱。

要使用配置檔案，請在 CLI 命令中通過 --profile 或 -p 標誌來傳遞。 例如：

databricks clusters list -p <profile-name>

在--profile 或-p 之後按 Tab 鍵，以顯示可用設定檔的清單。

令牌儲存

從 Databricks CLI 版本 1.0.0 起，預設情況下，U2M 令牌會儲存在作業系統原生的安全儲存中：macOS 的 Keychain、Windows 的憑證管理器，以及 Linux 的 D-Bus Secret Service。 你的 .databrickscfg 檔案只包含非機密設定，例如主機和設定檔名稱。 代幣本身從未被寫入其中。

每個設定檔都有自己的快取標記。 如果你有多個設定檔指向同一個工作區，登出其中一個並不會讓其他設定檔也登出。

如果你的環境不支援作業系統原生的安全儲存（例如無頭伺服器或 CI 環境），你可以退回到 明文令牌儲存。

關於安全儲存錯誤的故障排除，請參見 Databricks CLI 故障排除。

使用明文備援

如果您的環境不支援安全儲存，或依賴基於檔案的憑證儲存（例如透過 SSH 同步憑證檔案），您可以將 CLI 設定為使用純 JSON 檔案，並選擇以下任一選項。 設定好任一選項後，再跑 databricks auth login 一次。

• 設定環境 DATABRICKS_AUTH_STORAGE 變數。

  export DATABRICKS_AUTH_STORAGE=plaintext
  

• 在 Databricks 組態設定檔 檔案 ~/.databrickscfg 中設定 auth_storage 設定。

  [__settings__]
  auth_storage = plaintext
  

環境變數優先於設定設定檔設定。

Azure 管理式身分驗證

Azure 受管理身份 認證使用 Azure 資源的受管理身份（前稱為 Managed Service Identities （MSI））進行身分驗證。 參見 什麼是Azure資源的受管理身份？。 另見 Authenticate with Azure managed identities。

要建立 Azure 使用者指派的管理身份，請執行以下操作：

1. 建立或識別一台 Azure 虛擬機，並在上面安裝 Databricks CLI 後，將你的管理身份指派給你的 Azure 虛擬機和目標 Azure Databricks 帳號、工作區，或兩者兼有。 請參見將 Azure 託管身份應用於 Azure Databricks。

2. 在Azure虛擬機上，建立或識別一個Azure Databricks 配置檔，並在你的 .databrickscfg 檔案中輸入以下欄位。 如果您建立設定檔，請將占位符替換成適當的值。

   對於帳戶層級命令，在您的.databrickscfg文件中設置以下值：

   [<some-unique-configuration-profile-name>]
   host            = <account-console-url>
   account_id      = <account-id>
   azure_client_id = <azure-managed-identity-application-id>
   azure_use_msi   = true
   

   要針對工作區層級指令，在您的.databrickscfg文件中設定以下數值：

   [<some-unique-configuration-profile-name>]
   host            = <workspace-url>
   azure_client_id = <azure-managed-identity-application-id>
   azure_use_msi   = true
   

   Databricks 建議使用 host 並明確指派該工作區的身份。 或者，使用 azure_workspace_resource_id 搭配 Azure 資源 ID。 此方法需要對 Azure 資源擁有貢獻者或擁有者權限，或是擁有特定 Azure Databricks 權限的自訂角色。

3. 在 Azure 虛擬機上，使用 Databricks CLI 的 --profile 或 -p 選項，後接著你的設定檔名稱，用來設定 Databricks 的設定檔，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

   小提示

   您可以在 Tab 或 --profile 之後按 -p，以顯示現有可用組態配置檔的清單，以便從中選擇，而不是手動輸入組態配置檔名稱。

Microsoft Entra ID 服務主體認證

Microsoft Entra ID 服務主體 認證使用 Microsoft Entra ID 服務主體的憑證來進行認證。 若要建立和管理Azure Databricks服務主體，請參見Service Principals。 另見 與Microsoft Entra服務主體認證。

要設定並使用Microsoft Entra ID服務主體認證，必須在本地安裝 Authenticate，並安裝 Azure CLI。 您也必須執行下列動作：

1. 在您的 檔案中建立或識別一個 Azure Databricks .databrickscfg，並包含以下欄位。 如果您建立設定檔，請將占位符替換成適當的值。

   對於帳戶層級命令，在您的.databrickscfg文件中設置以下值：

   [<some-unique-configuration-profile-name>]
   host                = <account-console-url>
   account_id          = <account-id>
   azure_tenant_id     = <azure-service-principal-tenant-id>
   azure_client_id     = <azure-service-principal-application-id>
   azure_client_secret = <azure-service-principal-client-secret>
   

   要針對工作區層級指令，在您的.databrickscfg文件中設定以下數值：

   [<some-unique-configuration-profile-name>]
   host                = <workspace-url>
   azure_tenant_id     = <azure-service-principal-tenant-id>
   azure_client_id     = <azure-service-principal-application-id>
   azure_client_secret = <azure-service-principal-client-secret>
   

   Databricks 建議使用 host，並明確指派 Microsoft Entra ID 服務主體給工作區。 或者，使用 azure_workspace_resource_id 搭配 Azure 資源 ID。 此方法需要對 Azure 資源擁有貢獻者或擁有者權限，或是擁有特定 Azure Databricks 權限的自訂角色。

2. 使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱，作為 Databricks CLI 命令呼叫的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

   小提示

   您可以在 Tab 或 --profile 之後按 -p，以顯示現有可用組態配置檔的清單，以便從中選擇，而不是手動輸入組態配置檔名稱。

Azure CLI 認證

Azure CLI 認證利用Azure CLI來驗證已登入的實體。 另見 用 Azure CLI 認證。

要設定 Azure CLI 認證，您必須執行以下步驟：

1. 請在本地安裝 Azure CLI。

2. 使用Azure CLI執行 az login 指令登入 Azure Databricks。 請參見以Azure CLI登入。

3. 在您的 檔案中建立或識別一個 Azure Databricks .databrickscfg，並包含以下欄位。 如果您建立設定檔，請將占位符替換成適當的值。

   對於帳戶層級命令，在您的.databrickscfg文件中設置以下值：

   [<some-unique-configuration-profile-name>]
   host       = <account-console-url>
   account_id = <account-id>
   

   要針對工作區層級指令，在您的.databrickscfg文件中設定以下數值：

   [<some-unique-configuration-profile-name>]
   host = <workspace-url>
   

4. 使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱，作為 Databricks CLI 命令呼叫的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

   小提示

   您可以在 Tab 或 --profile 之後按 -p，以顯示現有可用組態配置檔的清單，以便從中選擇，而不是手動輸入組態配置檔名稱。

身份驗證評估順序

每當 Databricks CLI 驗證到 Azure Databricks 工作空間或帳號時，會依下列順序尋找所需設定：

1. 服務包設定檔案，適用於從服務包工作目錄執行的命令。 套件組合設定檔案不能直接包含認證值。
2. 環境變數，如本文和 統一驗證的環境變數和欄位中所列。
3. 配置檔案 在.databrickscfg檔案中。

一旦CLI找到所需的設定，它就會停止搜尋其他位置。

範例：

• 如果設定了環境變數，那麼 DATABRICKS_TOKEN CLI 會使用它，即使在 .databrickscfg 中存在多個 token。
• 如果未設定 DATABRICKS_TOKEN，並且套件環境參照配置檔案名稱（例如 dev → 配置檔案 DEV），則 CLI 會使用 .databrickscfg 中該配置檔案的認證。
• 如果未設定 DATABRICKS_TOKEN ，且組合環境指定 host 值，則 CLI 會搜尋 .databrickscfg 中符合 host 的設定檔，然後使用其 token。

個人存取權杖認證（舊有系統）

這很重要

Azure Databricks 建議在可能的情況下使用 OAuth 取代 PAT，因為 OAuth 提供更強的安全性。 請考慮以下認證方法：

• OAuth 機器對機器 (M2M) 認證
• OAuth 使用者到機器 (U2M) 身分驗證
• Azure managed identities authentication
• Microsoft Entra ID 服務主體認證
• Azure CLI 認證

Azure Databricks 個人存取令牌認證使用 Azure Databricks 個人存取令牌來認證目標 Azure Databricks 實體，例如 Azure Databricks 使用者帳號。 請參見 用Azure Databricks個人存取憑證認證（舊版）。

若要建立個人存取權杖，請遵循為 工作區使用者建立個人存取權杖中的步驟。