Если ваша надстройка Google Workspace подключается к стороннему сервису или API, требующему авторизации, надстройка может предложить пользователям войти в систему и авторизовать доступ.
На этой странице объясняется, как аутентифицировать пользователей с помощью потока авторизации (например, OAuth), который включает следующие шаги:
- Определите, когда требуется авторизация.
- Верните интерфейс карты, который предлагает пользователям войти в службу.
- Обновите надстройку, чтобы пользователи могли получить доступ к службе или защищенному ресурсу.
Если вашему дополнению требуется только удостоверение пользователя, вы можете аутентифицировать пользователей напрямую, используя их идентификатор 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 см. в разделе Об обзоре приложения .
На следующих изображениях показан пример пользовательской карты авторизации для домашней страницы надстройки. На карточке есть логотип, описание и кнопка входа:
Чтобы использовать этот пример пользовательской карточки, верните следующий ответ 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
.