OAuth интеграции. Документация для разработчиков

Связанные статьи:

• OAuth интеграции. Общее описание

Что нужно сделать для запуска интеграции по OAuth:

• Заключить партнерское соглашение и получить client_id 
• Сгенерировать secret с помощью API /v3/partner-applications/{applicationId}/reset-secret
• Определить список требуемых разрешений для работы приложения (доступ к мероприятия, файлам и тд)
• Реализовать запрос доступа с помощью OAuth и интегрироваться с UserAPI
• Провести финальный тест и добавить приложение в магазин интеграция МТС Линк

1. Получение client_id

После заключения партнерского приложения разработчик получает:

2. Создание secret

Чтобы получить secret нужно будет вызвать метод UserAPI (Получение secret для интеграции по OAuth):

curl --location --request POST 'https://userapi.mts-link.ru/v3/partner-applications/{applicationId}/reset-secret' \
--header 'x-auth-token: {apiKey}'

где
{ applicationId } - 1
{apiKey} - ключ к UserAPI вашего тестового стенда
Ответ:

{
"data": {
"secret": "{secret}"
}
}

3. Настройка тестового стенда

По умолчанию, все OAuth интеграции запрещены, чтобы предотвратить несанкционированный доступ. Администратору нужно явным образом разрешить интеграцию, тогда её смогут использовать другие сотрудники организации. 

Разрешить доступ можно через API.

curl --location --request POST 'https://userapi.mts-link.ru/v3/partner-application-clients/{applicationId}/enable' \

--header 'x-auth-token: {apiKey}'

Также администратор может разрешить в ЛК (Организация - Интеграции - OAuth-приожения)

Подробнее:

• Включение партнёрского приложения по API
• Отключение партнёрского приложения по API
• Список партнерских приложений

4. Разрешения на запуск методов

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

Список скоупов

Соответствие роутов скоупам

5. Сценарий запроса токена

 5.1 Авторизация пользователя

Размещаете в вашем приложении кнопку "Подключить МТС Линк". При нажатии пользователя нужно перенаправить на страницу запроса доступа к данным пользователя. 

Формат ссылки: https://my.mts-link.ru/authorize?response_type=code
&client_id={clientId из шага 1}
&scope=userapi_events_read+userapi_events_write
&state={не обязательно, значение, которое вернем при обратном редиректе}

Опционально можно передать &redirect_uri=https://example-app.com/callback. Данный параметр указывает на какой url в этот раз отправить обратно, если зарегистрируете у нас более одного приложения.

После авторизации пользователя в МТС Линк и подтверждения им предоставления прав пользователь будет перенаправлен на указанный redirect_url с добавлением параметров code и state (если они его передавали).

?code={code}&state=123 

Возможные ошибки:

• Тариф клиента не разрешает интеграцию по API

• Приложение не разрешено для установки в данной организации

• Приложение не найдено

5.2 Получение JWT-токена

Ваше приложение с использованием полученного code выполняет запрос для получения JWT-токена

curl --location 'https://my.mts-link.ru/api/idp/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={clientId}' \
--data-urlencode 'client_secret={secret}' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={code}'

Пример ответа

{

"token_type": "Bearer",    

"expires_in": 600,

"access_token": "...",

"refresh_token": "..."

}

5.3 Выполнение запросов к UserAPI от имени пользователя

Некоторые методы UserAPI поддерживают работу одновременно с разными типами ключей, но отличаются заголовки. Оба типа авторизации в API продолжат работать дальше.

• для OAuth параметр: --header 'authorization: Bearer {access_token}'

• для обычного API ключа: --header 'x-auth-token: {apiKey}'

Пример запроса временных зон:
curl --location --request POST 'https://userapi.mts-link.ru/v3/timezones' \ --header 'authorization: Bearer {access_token}'

где {access_token} - полученное в предыдущем пункте значение.

5.4 Актуализация токена

curl --location 'https://my.mts-link.ru/api/idp/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={clientId}' \
--data-urlencode 'client_secret={secret}' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token={refresh_token}'

5.5 Профиль текущего пользователя

API. Profile профиль пользователя (OAuth)

6. Управление токенами пользователей

Внутри личного кабинета МТС Линк пользователь видит список подключенных интеграций и может их удалить. При этом токен становится неактивным, все доступы приложения удаляются.

Администратор организации видит сессии пользователей и может при необходимости удалять сессии других пользователей, или запрещать приложение  с одновременным удалением сессий сразу для всех пользователей организации.