Настройка приложения OAuth 2.0
Для настройки нового OAuth-приложения и выполнения аутентификации с веб-сервисом:
1.Откройте страницу веб-сервиса и перейдите на вкладку [Аутентификация].
2.В поле [Аутентификация] выберите “OAuth 2.0”.
3.В поле [Приложение] нажмите [+] (Рис. 1).
Рис. 1 — Добавление нового OAuth-приложения
Заполните страницу настройки OAuth-приложения (Рис. 2). Необходимые значения параметров обычно можно найти в документации веб-сервиса или получить через API такого веб-сервиса. Например, данные для доступа к Google API можно найти в разделе [Учетные данные] консоли разработчика Google, а также в документации API.
Рис. 2 — Страница настройки OAuth-приложения
Поскольку в разных сервисах используется различная терминология, а также есть отличия в структуре API и документации, то настройка аутентификации также имеет свои особенности. Общие проблемы настройки OAuth и способы их решения описаны в отдельной статье.
Ниже приведены общие рекомендации по заполнению параметров настройки OAuth, а также подсказки, как получить значения таких параметров.
Важно
Настройка OAuth-аутентификации выполняется на стороне bpm’online и во внешнем приложении.
Название
В поле [Название] укажите название нового приложения, которое отобразится на вкладке [Аутентификация] в поле [Приложение]. Также можно выбрать изображение, которое будет использоваться как иконка этого OAuth-приложения.
Client ID
В поле [Client ID] укажите идентификатор клиента, выданный сервером авторизации интегрированного веб-сервиса. В документации и в API разных веб-сервисов секретный ключ также может называться:
•Application (идентификатор приложения)
•Consumer ID (идентификатор заказчика)
•Public key (публичный ключ)
Указанный идентификатор будет значением параметра вызова client_id. Подробнее >>>
Пример
Client ID для Google API можно найти в разделе [Учетные данные] консоли Google API (https://console.developers.google.com), в поле “Client ID”. Подробнее >>>
Client secret
В поле [Client secret] укажите секретный ключ, предоставленный сервером авторизации. Также в документации и в API разных веб-сервисов секретный ключ может называться:
•Application secret (секретный ключ приложения)
•Consumer secret
•Secret key
Указанный секретный ключ будет значением параметра вызова client_secret. Подробнее >>>
Пример
Client secret для Google API можно найти в разделе [Учетные данные] консоли Google API (https://console.developers.google.com), в поле “Client secret”. Подробнее >>>
URL запроса кода авторизации
В поле [URL запроса кода авторизации] укажите URL, который будет служить конечной точкой (endpoint) для запроса доступа у пользователя, который его может предоставить. Например, когда Google информирует вас, что приложение пытается получить доступ к определенным данным, вы выступаете в роли “пользователя, который может предоставить доступ”.
Указанный URL является значением параметра вызова auth_url. Подробнее >>>
Пример
URL запроса кода авторизации для Google API — “https://accounts.google.com/o/oauth2/auth”. Его можно найти в документации, описывающей пример интеграции OAuth-приложения с Google. Также URL доступен в JSON-файле с настройками, который можно загрузить в разделе “Учетные данные” консоли разработчика Google.
URL запроса токена
В поле [URL запроса токена] укажите URL-адрес, который будет использоваться в качестве конечной точки (endpoint) для запроса токена доступа при вызове веб-сервиса. Подробнее >>>
Пример
URL запроса токена для Google API — “https://www.googleapis.com/oauth2/v3/token”. Его можно найти в документации, описывающей пример интеграции OAuth-приложения с Google. Также URL доступен в JSON-файле с настройками, который можно загрузить в разделе “Учетные данные” консоли разработчика Google.
Redirect URL
При настройке OAuth-аутентификации на стороне веб-сервиса необходимо указать URL-адрес, по которому сервер аутентификации будет перенаправлять пользователей после выполнения аутентификации. “Redirect URL” отображается на странице настройки OAuth-аутентификации (Рис. 3).
Рис. 3 — Redirect URL на странице настройки OAuth-аутентификации в bpm’online
Убедитесь, что в настройках интегрированного сервиса указан корректный URL-адрес для переадресации.
Отправлять client id и secret в запросе токена
Выберите часть запроса токена, которая будет содержать токен доступа. Авторизация предусматривает несколько способов передачи токена. В поле [Отправлять client id и secret в запросе токена] доступны для выбора следующие варианты: “Как заголовок Basic авторизации”, “В теле запроса” или “В параметрах GET-запроса”. Вариант передачи зависит от особенностей сторонней системы и обычно рассматривается в ее документации.
В теле запроса
Многие популярные сервисы, например, Google, Linkedin, JIRA и т. д. обрабатывают запросы, когда токен доступа передается в теле запроса.
Пример
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
&client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw
Как заголовок Basic авторизации
Некоторые сервисы, такие, как QuickBooks, Docusign, GoToWebinar требуют, чтобы идентификатор и секретный ключ клиента передавались в формате заголовка и не примут их в теле запроса. Подробнее читайте в документации IETF.
Пример
curl -X POST "https://api.getgo.com/oauth/v2/token" \:
-H "Authorization: Basic {Base64 Encoded consumerKey and consumerSecret}" \
-H "Accept:application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&code=
{responseKey}&redirect_uri=http%3A%2F%2Fcode.example.com"
В параметрах GET-запроса
Некоторые сервисы выполняют аутентификацию другим способом. Например, вместо POST-запроса с параметрами, содержащимися в теле и заголовках, Facebook использует GET-запрос токена со всеми параметрами в URL запроса.
Пример
https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow/#confirm\
GET https://graph.facebook.com/v3.2/oauth/access_token?\
client_id={app-id}\
&redirect_uri={redirect-uri}\
&client_secret={app-secret}\
&code={code-parameter}
URL отзыва токена
В поле [URL отзыва токена] укажите URL, который будет использоваться в качестве конечной точки (endpoint) для отзыва токена доступа при отклонении соответствующих вызовов веб-сервиса.
Необязательное для заполнения поле. Обычно пользователь, имеющий доступ к интегрированному веб-сервису, может отменить доступ к определенным приложениям OAuth. Например, вы можете ограничить доступ к определенным приложениям в настройках своей учетной записи Google.
Пример
URL-адрес для запроса отзыва токена Google API — “https://accounts.google.com/o/oauth2/revoke”. Получить его можно в документации Google API.
Авторизоваться
По кнопке [Авторизоваться] войдите в веб-сервис, используя общие учетные данные, и разрешите доступ к стороннему приложению для bpm’online.
Разрешения (scopes)
Разрешения (scopes) используются для настройки разных уровней доступа приложения к данным от имени конечного пользователя. URL-адреса для указания на детали [Разрешения (scopes)] обычно доступны в документации веб-сервиса. Каждое API может объявлять одно или несколько разрешений.
Пример
Разрешения Google API, например, “https://www.googleapis.com/auth/gmail.readonly” (разрешение на просмотр email-сообщений и настроек) доступны в документации API.
