通过OAuth设备代码流授权无头访问

Important

此功能在 Beta 版中。 要使用它,工作区管理员必须从预览页面开启工作区设备代码授权。 请参阅 Manage Azure Databricks 预览版。

使用设备代码授权,在无法打开浏览器的机器上获得工作区级OAuth访问令牌,比如远程虚拟机或容器。 你先在无头机器上开始登录,在其他设备上的浏览器完成登录,然后返回确认码给无头机器以获取令牌。

该流程基于 OAuth 2.0设备授权授权(RFC 8628),并增加了确认步骤。 登录后,Azure Databricks会显示一个确认码,你需要在无头机上输入。 没有这个代码,令牌请求会失败,所以单纯登录不会发出令牌。 你还必须将确认码返回给发起请求的机器。

如果你的机器能打开浏览器,就用标准的用户到机器(U2M)流程。 请参阅 授权用户使用 OAuth 访问 Azure Databricks。

Requirements

  • 一位工作区管理员在预览页面开启了工作区设备代码授权。 请参阅 Manage Azure Databricks 预览版。 如果未开启,请求会失败,出现一个 access_denied 错误,提示 Device authorization is not enabled for this workspace。
  • 你使用以下OAuth客户端之一:
  • 你有工作区的URL。 设备代码授权只对工作区主机有效,不能在账户控制台上使用。

使用设备代码获取访问令牌

在完成步骤 1 后,你有 10 分钟的时间在步骤 2 中批准此次登录。 批准后,你还有10分钟完成第三步。 如果任一时间窗口已过,就从第一步重新开始。

步骤1:请求设备代码和用户代码

在无头机器上,使用 curl 来请求设备代码。 将 <databricks-instance> 替换为 Azure Databricks 工作区实例名称(例如 adb-1234567890123456.7.azuredatabricks.net)。

要请求设备代码,请运行以下操作:

curl --request POST \
https://<databricks-instance>/oidc/v1/device/auth \
--data "client_id=databricks-cli" \
--data "scope=all-apis offline_access"

如果你使用自定义OAuth应用,设置 client_id 为其客户端ID。 仅当需要刷新令牌时,才在scope中包含offline_access。

响应类似于以下内容:

{
  "device_code": "Zk9x...Qm3w",
  "user_code": "ABCD1234",
  "verification_uri": "https://<databricks-instance>/device/verification",
  "expires_in": 600
}

保存 device_code 值,以供步骤 3 使用。

步骤2:在浏览器中批准登录

在任何带有浏览器的设备上,比如你的笔记本电脑或手机:

  1. 转到步骤 1 的响应中的 verification_uri。

  2. 根据提示登录到你的 Azure Databricks 工作区。

  3. 在“登录 Databricks”页面中,输入步骤 1 中的 user_code,然后单击“登录”。

  4. 在 在您的设备上完成登录 页面,点击 复制 以复制确认码。 页面显示了代码有效的时间。

    在你的设备页面上完成登录,显示确认码、到期时间和复制按钮。

步骤3:Exchange代码以获得访问令牌

在无头机器上,使用 curl 设备代码和确认码交换访问令牌。

替换请求中的以下内容:

  • <databricks-instance>: 你的 工作区实例名称。
  • <device-code>:步骤 1 中的 device_code 值。
  • <confirmation-code>:第二步的确认码。 代码是区分大小写的。

要获得访问令牌,请运行以下操作:

curl --request POST \
https://<databricks-instance>/oidc/v1/token \
--data "client_id=databricks-cli" \
--data "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
--data "device_code=<device-code>" \
--data "confirmation_code=<confirmation-code>"

如果你使用自定义的OAuth应用,请设置 client_id 为你在第一步中使用的客户端ID。 对于机密应用程序,也要传递 client_secret。

从响应中复制access_token值。 例如:

{
  "access_token": "eyJr...Dkag",
  "refresh_token": "doau...f26e",
  "scope": "all-apis offline_access",
  "token_type": "Bearer",
  "expires_in": 3600
}

访问令牌有效期为一小时。 仅当你在第 1 步请求了 offline_access 范围时,回复才包括 refresh_token。 设备代码和确认码只能使用一次。

与标准RFC 8628流程不同,该流程不使用轮询。 在你拿到确认码后,发送一次令牌请求。

步骤4:调用Azure Databricks REST API

使用访问令牌调用工作区级的 REST API。

这个例子使用curl以及Bearer认证来列出工作区中所有可用的集群。 将 <oauth-access-token> 替换为访问令牌,并将 替换为 Azure Databricks adb-1234567890123456.7.azuredatabricks.net,例如 <databricks-instance>。

export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
"https://<databricks-instance>/api/2.0/clusters/list"

刷新令牌与会话生命周期

设备代码流会发出一次性刷新令牌,无论你的 OAuth 应用的令牌设置如何。 这遵循了RFC 9700第4.14节中的刷新令牌轮换指南。 设备代码流中的刷新令牌具有以下限制:

  • 一次性使用: 每个刷新令牌只能使用一次。 当你用它获取新的访问令牌时,响应会包含一个新的刷新令牌,旧的则停止工作。 如果你在30秒内重新发送之前的刷新令牌,响应会返回当前刷新令牌而不是错误。 每次都存储新的刷新令牌。 参见 “什么是一次性刷新令牌?”。
  • 24小时会话: 刷新令牌在完成设备代码流程后最多只能使用24小时。 你的 OAuth 应用的令牌访问策略可以缩短这一时限,但不能延长这一时限。

会话结束后,再次运行设备代码流以获取新的访问令牌。

排除故障

下表列出了设备代码流可能返回的错误及其解决方法。

Error Cause 解决方案
access_denied: Device authorization is not enabled for this workspace 工作区的工作区设备代码授权预览功能未开启。 请工作区管理员在 预览 页面开启它。
unauthorized_client: Device authorization is not enabled for this app OAuth 客户端不支持设备代码授权。 使用 databricks-cli 或自定义OAuth应用。
在验证页面This code is invalid, expired, or already used 用户代码有误、已过期或已使用过。 检查验证码并再次输入。 如果过期了,就从第一步重新开始。
invalid_request: Invalid device code 设备代码错误、过期或已被使用。 从第一步重新开始。
invalid_request: Invalid confirmation code 确认码缺失、错误或过期。 检查你复制的确认码是否完全准确,包括大小写。 如果过期了,就从第一步重新开始。
invalid_request: Device grant rate limit exceeded (HTTP 429) 你发送了太多令牌请求,针对同一个设备代码。 等几秒钟,再试一次。 如果代码过期,就从第一步重新开始。
验证页面提示 Too many attempts 你输入用户码太多次了。 等几秒钟,再试一次。

安全建议

用户代码和确认码可让您访问您的工作区。 遵循以下建议:

  • 仅在你自己发起的登录过程中输入用户代码 如果有人发给你用户验证码或验证链接并让你登录,不要输入。 攻击者可以利用这个请求获取你的账户令牌。
  • 把设备代码、确认码和令牌当作密码来对待。 不要分享它们,也不要将其写入日志或源代码管理系统。
  • 只需申请你需要的权限范围。 如果你不需要刷新令牌,可以省略 offline_access。