![链接预览中的自定义授权卡,其中包含公司徽标、说明和登录按钮。](https://developers.google.cn/static/workspace/add-ons/images/card-auth-link-preview.png?authuser=9&hl=fi)
如果您的 Google Workspace 插件连接到需要授权的第三方服务或 API,该插件可以提示用户登录并授予访问权限。
本页面介绍了如何使用授权流程(例如 OAuth)对用户进行身份验证,其中包含以下步骤:
- 检测何时需要授权。
- 返回提示用户登录服务的卡片界面。
- 刷新插件,以便用户可以访问服务或受保护的资源。
如果您的插件只需要用户身份,您可以使用用户的 Google Workspace ID 或电子邮件地址直接对其进行身份验证。如需使用电子邮件地址进行身份验证,请参阅验证 JSON 请求。如果您使用 Google Apps 脚本构建了插件,请访问 Apps 脚本文档,了解如何将插件关联到第三方服务。
检测是否必须获得授权
使用您的插件时,用户可能无权访问受保护的资源,原因有多种,例如:
- 尚未生成用于连接到第三方服务的访问令牌或已过期。
- 访问令牌未涵盖请求的资源。
- 访问令牌未涵盖请求所需的范围。
您的插件应检测这些情况,以便用户可以登录并访问您的服务。
提示用户登录您的服务
当您的插件检测到需要授权时,该插件必须返回一个卡片界面,以提示用户登录服务。登录卡必须重定向用户,以便在您的基础架构上完成第三方身份验证和授权流程。
我们建议您使用 Google 登录功能保护目标应用,并使用登录期间签发的身份令牌获取用户 ID。子声明包含用户的唯一 ID,并且可以与您的插件中的 ID 相关联。
构建并返回登录卡片
对于服务的登录卡,您可以使用 Google 的基本授权卡,也可以自定义卡以显示其他信息,例如贵组织的徽标。如果您要公开发布插件,则必须使用自定义卡片。
基本授权卡
下图显示了 Google 的基本授权卡示例:
![示例帐号的基本授权提示。该提示表明插件想要显示更多信息,但需要获得用户的批准才能访问帐号。](https://developers.google.cn/static/workspace/add-ons/images/third-party-auth-prompt.png?authuser=9&hl=fi)
如需使用基本授权卡,则返回以下 JSON 响应:
{ "basic_authorization_prompt": { "authorization_url": "AUTHORIZATION_REDIRECT", "resource": "RESOURCE_DISPLAY_NAME" } }
替换以下内容:
AUTHORIZATION_REDIRECT
:处理授权的 Web 应用的网址。RESOURCE_DISPLAY_NAME
:受保护的资源或服务的显示名称。此名称会在授权提示中显示给用户。例如,如果您的RESOURCE_DISPLAY_NAME
为Example Account
,则提示符会提示“This add-on would like to show additional information,, but it need approval to access your Example Account.”
完成授权后,系统会提示用户刷新插件以访问受保护的资源。
自定义授权卡
如需修改授权提示,您可以为服务的登录体验创建自定义卡片。
如果您要公开发布插件,必须使用自定义授权卡。如需详细了解 Google Workspace Marketplace 的发布要求,请参阅应用审核简介。
下图显示了插件首页的自定义授权卡片示例。该卡片包含一个徽标、说明和登录按钮:
![Cymbal Labs 的自定义授权卡,其中包含公司徽标、说明和登录按钮。](https://developers.google.cn/static/workspace/add-ons/images/card-auth-homepage.png?authuser=9&hl=fi)
如需使用此自定义卡片示例,请返回以下 JSON 响应:
{ "custom_authorization_prompt": { "action": { "navigations": [ { "pushCard": { "sections": [ { "widgets": [ { "image": { "imageUrl": "LOGO_URL", "altText": "LOGO_ALT_TEXT" } }, { "divider": {} }, { "textParagraph": { "text": "DESCRIPTION" } }, { "buttonList": { "buttons": [ { "text": "Sign in", "onClick": { "openLink": { "url": "AUTHORIZATION_REDIRECT", "onClose": "RELOAD", "openAs": "OVERLAY" } }, "color": { "red": 0, "green": 0, "blue": 1, "alpha": 1, } } ] } }, { "textParagraph": { "text": "TEXT_SIGN_UP" } } ] } ] } } ] } } }
替换以下内容:
LOGO_URL
:徽标或图片的网址。必须是公开网址。LOGO_ALT_TEXT
:徽标或图片的替代文本,例如Cymbal Labs Logo
。DESCRIPTION
:号召用户登录的号召性用语,例如Sign in to get started
。- 如需更新登录按钮,请执行以下操作:
AUTHORIZATION_REDIRECT
:处理授权的 Web 应用的网址。- 可选:如需更改按钮颜色,请更新
color
字段的 RGBA 浮点值。
TEXT_SIGN_UP
:如果用户没有帐号,此文本会提示用户创建帐号。例如New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here
。