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客户端之一:
- Databricks CLI OAuth 应用程序,客户端 ID 为
databricks-cli。 - 一个自定义的OAuth应用。 请参阅使用 Azure Databricks UI 启用自定义 OAuth 应用程序。
- Databricks CLI OAuth 应用程序,客户端 ID 为
- 你有工作区的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 的响应中的
verification_uri。根据提示登录到你的 Azure Databricks 工作区。
在“登录 Databricks”页面中,输入步骤 1 中的
user_code,然后单击“登录”。在 在您的设备上完成登录 页面,点击 复制 以复制确认码。 页面显示了代码有效的时间。
步骤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。