将 Google Workspace 插件与第三方服务关联

链接预览中的自定义授权卡,其中包含公司徽标、说明和登录按钮。

如果您的 Google Workspace 插件连接到需要授权的第三方服务或 API,该插件可以提示用户登录并授予访问权限。

本页面介绍了如何使用授权流程(例如 OAuth)对用户进行身份验证,其中包含以下步骤:

  1. 检测何时需要授权。
  2. 返回提示用户登录服务的卡片界面。
  3. 刷新插件,以便用户可以访问服务或受保护的资源。

如果您的插件只需要用户身份,您可以使用用户的 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_NAMEExample Account,则提示符会提示“This add-on would like to show additional information,, but it need approval to access your Example Account.”

完成授权后,系统会提示用户刷新插件以访问受保护的资源。

自定义授权卡

如需修改授权提示,您可以为服务的登录体验创建自定义卡片。

如果您要公开发布插件,必须使用自定义授权卡。如需详细了解 Google Workspace Marketplace 的发布要求,请参阅应用审核简介

下图显示了插件首页的自定义授权卡片示例。该卡片包含一个徽标、说明和登录按钮:

Cymbal Labs 的自定义授权卡,其中包含公司徽标、说明和登录按钮。

如需使用此自定义卡片示例,请返回以下 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