Подключите дополнение Google Workspace к стороннему сервису.

Пользовательская карта авторизации из предварительного просмотра ссылки, которая включает логотип компании, описание и кнопку входа.
Интерфейс карты входа для надстройки, которая просматривает ссылки из стороннего сервиса.

Если ваша надстройка Google Workspace подключается к стороннему сервису или API, требующему авторизации, надстройка может предложить пользователям войти в систему и авторизовать доступ.

На этой странице объясняется, как аутентифицировать пользователей с помощью потока авторизации (например, OAuth), который включает следующие шаги:

  1. Определите, когда требуется авторизация.
  2. Верните интерфейс карты, который предлагает пользователям войти в службу.
  3. Обновите надстройку, чтобы пользователи могли получить доступ к службе или защищенному ресурсу.

Если вашему дополнению требуется только удостоверение пользователя, вы можете аутентифицировать пользователей напрямую, используя их идентификатор Google Workspace или адрес электронной почты. Чтобы использовать адрес электронной почты для аутентификации, см. раздел Проверка запросов JSON . Если вы создали надстройку с помощью Google Apps Script, посетите документацию по Apps Script , чтобы узнать о подключении надстройки к сторонней службе.

Обнаружить, что требуется авторизация

При использовании вашего дополнения пользователям может быть не разрешен доступ к защищенному ресурсу по ряду причин, например следующих:

  • Токен доступа для подключения к сторонней службе еще не создан или срок его действия истек.
  • Токен доступа не распространяется на запрошенный ресурс.
  • Токен доступа не охватывает требуемые области запроса.

Ваше дополнение должно обнаруживать такие случаи, чтобы пользователи могли войти в систему и получить доступ к вашей службе.

Предлагайте пользователям войти в ваш сервис

Когда надстройка обнаруживает, что требуется авторизация, надстройка должна вернуть интерфейс карты , чтобы предложить пользователям войти в службу. Карта входа должна перенаправлять пользователей для завершения стороннего процесса аутентификации и авторизации в вашей инфраструктуре.

Мы рекомендуем вам защитить целевое приложение с помощью входа в систему Google и получить идентификатор пользователя, используя токен идентификации, выданный во время входа в систему. Подзапрос содержит уникальный идентификатор пользователя, который можно сопоставить с идентификатором вашего дополнения.

Создайте и верните карту входа

В качестве карты входа в службу вы можете использовать базовую карту авторизации Google или настроить карту для отображения дополнительной информации, например логотипа вашей организации. Если вы публикуете свое дополнение публично, вам необходимо использовать специальную карточку.

Карта базовой авторизации

На следующем изображении показан пример базовой карты авторизации Google:

Запрос базовой авторизации для примера учетной записи. В подсказке говорится, что надстройка хотела бы показать дополнительную информацию, но для доступа к учетной записи требуется одобрение пользователя.

Чтобы использовать базовую карту авторизации, верните следующий ответ JSON:

{
  "basic_authorization_prompt": {
    "authorization_url": "AUTHORIZATION_REDIRECT",
    "resource": "RESOURCE_DISPLAY_NAME"
  }
}

Замените следующее:

  • AUTHORIZATION_REDIRECT : URL-адрес веб-приложения, которое обрабатывает авторизацию.
  • RESOURCE_DISPLAY_NAME : отображаемое имя защищенного ресурса или службы. Это имя отображается пользователю в запросе авторизации. Например, если ваш RESOURCE_DISPLAY_NAME — это 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 : URL-адрес логотипа или изображения. Должен быть общедоступным URL-адресом.
  • LOGO_ALT_TEXT : альтернативный текст для логотипа или изображения, например Cymbal Labs Logo .
  • DESCRIPTION . Призыв к действию, призывающий пользователей войти в систему, например Sign in to get started .
  • Чтобы обновить кнопку входа:
    • AUTHORIZATION_REDIRECT : URL-адрес веб-приложения, которое обрабатывает авторизацию.
    • Необязательно: Чтобы изменить цвет кнопки, обновите плавающие значения RGBA color поля.
  • TEXT_SIGN_UP : текст, предлагающий пользователям создать учетную запись, если у них ее нет. Например, New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here .