如果您的 Google Workspace 插件连接到需要授权的第三方服务或 API，该插件可以提示用户登录并授予访问权限。
本页面介绍了如何使用授权流程（例如 OAuth）对用户进行身份验证，其中包含以下步骤：
- 检测何时需要授权。
- 返回提示用户登录服务的卡片界面。
- 刷新插件，以便用户可以访问服务或受保护的资源。
如果您的插件只需要用户身份，您可以使用用户的 Google Workspace ID 或电子邮件地址直接对其进行身份验证。如需使用电子邮件地址进行身份验证，请参阅验证 JSON 请求。如果您使用 Google Apps 脚本构建了插件，请访问 Apps 脚本文档，了解如何将插件关联到第三方服务。
检测是否必须获得授权
使用您的插件时，用户可能无权访问受保护的资源，原因有多种，例如：
- 尚未生成用于连接到第三方服务的访问令牌或已过期。
- 访问令牌未涵盖请求的资源。
- 访问令牌未涵盖请求所需的范围。
您的插件应检测这些情况，以便用户可以登录并访问您的服务。
提示用户登录您的服务
当您的插件检测到需要授权时，该插件必须返回一个卡片界面，以提示用户登录服务。登录卡必须重定向用户，以便在您的基础架构上完成第三方身份验证和授权流程。
我们建议您使用 Google 登录功能保护目标应用，并使用登录期间签发的身份令牌获取用户 ID。子声明包含用户的唯一 ID，并且可以与您的插件中的 ID 相关联。
构建并返回登录卡片
对于服务的登录卡，您可以使用 Google 的基本授权卡，也可以自定义卡以显示其他信息，例如贵组织的徽标。如果您要公开发布插件，则必须使用自定义卡片。
基本授权卡
下图显示了 Google 的基本授权卡示例：
如需使用基本授权卡，则返回以下 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 的发布要求，请参阅应用审核简介。
下图显示了插件首页的自定义授权卡片示例。该卡片包含一个徽标、说明和登录按钮：
如需使用此自定义卡片示例，请返回以下 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。