OAuth 2.0 流程

注意

此页面假定您已经拥有身份提供者 (IdP),例如 Google、Entra ID(以前称为 Azure AD)或 Okta,它处理身份验证过程并返回访问令牌。

了解如何通过 Web 浏览器让用户从您的扩展程序进行身份验证,并使用 OAuth 2.0 返回到您的扩展程序。

在 OAuth 2.0 中,“授权类型”一词是指应用程序获取访问令牌的方式。虽然 OAuth 2.0 定义了多种授权类型,但此页面仅描述如何使用授权码授权类型从您的扩展程序验证用户。

授权码授权流程

授权码授权类型供机密客户端和公共客户端使用,以将授权码交换为访问令牌。

用户通过重定向 URL 返回到客户端后,应用程序会从 URL 中获取授权码,并使用它来请求访问令牌。

Flow for OAuth 2.0

上图显示了

  • Docker 扩展要求用户授权访问其数据。
  • 如果用户授予访问权限,则扩展程序会从服务提供商请求访问令牌,并将来自用户的访问授权和身份验证详细信息传递给服务提供商以识别客户端。
  • 服务提供商然后验证这些详细信息并返回访问令牌。
  • 扩展程序使用访问令牌向服务提供商请求用户数据。

OAuth 2.0 术语

  • Auth URL:用于 API 提供商授权服务器的端点,用于检索授权码。
  • 重定向 URI:客户端应用程序回调 URL,在身份验证后重定向到此 URL。这必须在 API 提供商处注册。

用户输入用户名和密码后,即可成功进行身份验证。

打开浏览器页面以验证用户

从扩展程序 UI 中,您可以提供一个按钮,当选择该按钮时,会在浏览器中打开一个新窗口以验证用户。

使用 ddClient.host.openExternal API 在浏览器中打开 Auth URL。例如

window.ddClient.openExternal("https://authorization-server.com/authorize?
  response_type=code
  &client_id=T70hJ3ls5VTYG8ylX3CZsfIu
  &redirect_uri=${REDIRECT_URI});

获取授权码和访问令牌

您可以通过将 docker-desktop://dashboard/extension-tab?extensionId=awesome/my-extension 作为您正在使用的 OAuth 应用程序中的 redirect_uri 列出,并将授权码连接为查询参数来从扩展程序 UI 中获取授权码。然后,扩展程序 UI 代码将能够读取相应的代码查询参数。

重要

使用此功能需要 Docker Desktop 中的扩展程序 SDK 0.3.3。您需要确保在 镜像标签 中使用 com.docker.desktop.extension.api.version 设置的扩展程序所需的 SDK 版本高于 0.3.3。

授权

在此步骤中,用户会在浏览器中输入其凭据。授权完成后,用户将被重定向回您的扩展程序用户界面,并且扩展程序 UI 代码可以消耗作为 URL 中查询参数的一部分的授权码。

交换授权码

接下来,您需要将授权码交换为访问令牌。

扩展程序必须向 0Auth 授权服务器发送带有以下参数的 POST 请求

POST https://authorization-server.com/token
&client_id=T70hJ3ls5VTYG8ylX3CZsfIu
&client_secret=YABbyHQShPeO1T3NDQZP8q5m3Jpb_UPNmIzqhLDCScSnRyVG
&redirect_uri=${REDIRECT_URI}
&code=N949tDLuf9ai_DaOKyuFBXStCNMQzuQbtC1QbvLv-AXqPJ_f

注意

在此示例中,客户端凭据包含在 POST 查询参数中。OAuth 授权服务器可能要求将凭据作为 HTTP 基本身份验证标头发送,或者可能支持不同的格式。有关详细信息,请参阅您的 OAuth 提供商文档。

存储访问令牌

Docker Extensions SDK 没有提供专门用于存储密钥的机制。

强烈建议您使用外部存储源来存储访问令牌。

注意

用户界面本地存储在扩展程序之间是隔离的(一个扩展程序无法访问另一个扩展程序的本地存储),并且当用户卸载扩展程序时,每个扩展程序的本地存储都会被删除。

下一步

了解如何 发布和分发您的扩展程序