Авторизация приложения и запуск интеграции

Используемые термины и сокращения

Система — используемое в вашей организации программное бизнес-приложение, с которым необходимо произвести интеграцию.

АТС — это виртуальная телефонная станция «Телфин.Офис», размещенная на хостинге и предоставляемая как облачный сервис (услуга).

Интегратор — программист или системный администратор вашей организации, реализующий интеграцию используемой системы и АТС «Телфин.Офис».

Пользователь — пользователь АТС.

API (application programming interface) — программный интерфейс приложения, с помощью которого пользователь системы может осуществлять запросы к серверу виртуальной АТС с целью осуществления определённых действий или получения требуемых данных.

Суперприложение — приложение уровня дилера/администратора типа public(получение токена доступа возможно после авторизации пользователя на сервере АТС и получения кода авторизации), создаваемое Телфин для интегратора.

App ID — идентификатор суперприложения, сгенерированный при его создании.

App Secret — пароль суперприложения, сгенерированный при его создании.

Приложение — клиентское приложение типа trusted (получение токена доступа возможно без авторизации пользователя), создаваемое интегратором для данной интеграции.

Схема взаимодействия

Для предоставления возможности интеграции из интерфейса системы предусмотрен механизм серверной авторизации на базе протокола OAuth 2.0, позволяющий реализовать безопасную аутентификацию пользователей через API виртуальной АТС и получить доступ к функциям АТС с сервера системы.

Процесс авторизации состоит из следующих шагов:

  • Открытие диалогового окна для аутентификации пользователя на API-сервере АТС.
  • Разрешение пользователем доступа к своим данным.
  • Передача API-серверу АТС значения code для получения токена доступа с временем жизни.
  • Получение сервером системы токена доступа с временем жизни access_token для доступа к API АТС.
  • Создание постоянного доверенного приложения пользователю АТС.

Схематически данный процесс происходит следующим образом:

Аутентификация пользователя

Открытие диалогового окна для аутентификации пользователя на API-сервере АТС

Телфин по запросу интегратора создает суперприложение типа public, указывает URI перенаправления и передает интегратору App ID и App Secret этого приложения.

Для авторизации пользователя необходимо перенаправить его во всплывающем окне в системе (или на отдельной страничке) на URI авторизации https://apiproxy.telphin.ru/oauth/authorize, передавая данные авторизации в качестве параметров GET-запроса в формате URL-encoded:

ПараметрОписание
response_typeТип ответа, всегда должен иметь значение code
redirect_uriURI, по которому API-сервер АТС будет посылать ответ. Должен совпадать с указанным при создании суперприложения
client_idApp ID, сгенерированный при создании суперприложения
scopeСфера разрешений для суперприложения, должен иметь значение all

Пример:

App ID a80f1e618ddd4d4584e2bd48fd404194

App Secret a2423941f5be408c998d5f7207570990

В качестве redirect_url использован https://your_site.com

Пользователь нажимает в появившемся всплывающем окне на ссылку: https://apiproxy.telphin.ru/oauth/authorize?response_type=code&client_id=a80f1e618ddd4d4584e2bd48fd404194&redirect_uri=https%3A%2F%2Fyour_site.com&scope=all

Разрешение пользователем доступа к своим данным

После нажатия на вышеуказанную ссылку должно появиться всплывающее окно с запросом подтверждения доступа. Пользователь нажимает «Разрешить».

Получение токена доступа

Передача API-серверу АТС значения code для получения токена доступа с временем жизни

Если пользователь разрешает доступ, API-сервер АТС перенаправляет его на redirect_uri суперприложения (apphostname), передавая в качестве параметра запроса значение code (код для получения токена доступа) в виде https://your_site.com/cont/url?code=aIlsm1bCglDGvQKShmJAhHrBhDyshn.

Получение данного значения code (aIlsm1bCglDGvQKShmJAhHrBhDyshn) означает, что разрешен доступ к АТС и теперь возможно получить токен доступа с временем жизни и обновлять его.

Получение сервером системы токена доступа с временем жизни access_token для доступа к API АТС

Для получения токена доступа необходимо сделать POST-запрос с сервера системы на адрес https://apiproxy.telphin.ru/oauth/token, используя полученный код. Параметры передаются в теле запроса в формате application/x-www-form-urlencoded:

ПараметрОписание
grant_typeВсегда должен иметь значение authorization_code
codeПараметр , полученный суперприложением на предыдущем шаге
redirect_uriURI перенаправления. Должен совпадать с одним из указанных при создании суперприложения
client_idApp ID, сгенерированный при создании суперприложения
client_secretApp Secret, сгенерированный при создании суперприложения

Пример:

{
"grant_type": "authorization_code",
"code": "aIlsm1bCglDGvQKShmJAhHrBhDyshn",
"client_id": "a80f1e618ddd4d4584e2bd48fd404194",
"client_secret": "a2423941f5be408c998d5f7207570990",
"redirect_uri": "https://your_site.com"
}

API-сервер АТС отвечает суперприложению. Параметры ответа:

ПараметрОписание
access_tokenТокен доступа. Используется суперприложением для API-запросов
expires_inПериод времени в секундах, в течение которого токен действителен. Если в процессе использования токена возникла ошибка авторизации, рекомендуется запросить токен заново, даже если заявленное в поле expires_in время до истечения токена еще не прошло
token_typeТип токена. Всегда имеет значение Bearer
refresh_tokenRefresh token, который может быть использован для регенерации токена доступа, когда он стал недействителен

В ответ на этот запрос сервер системы получит токен доступа, с которым можно создать на API-сервере АТС постоянное доверенное приложение (типа trusted). Создать постоянное приложение необходимо, чтобы не приходилось повторно запрашивать доступ к аккаунту пользователя АТС, как это было описано trusted выше. Приложение типа получает токен доступа без авторизации пользователя на сервере АТС.

Создание постоянного доверенного приложения

Постоянное приложение создается следующим образом.

Например, ранее был получен токен доступа pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes . Необходимо отправить запрос POST c заголовками

{
"Content-type": "application/json",
"Authorization": "Bearer pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes")
}

и телом запроса в формате json

{ 
"name": "App_name",
"type": "trusted"
}

на https://apiproxy.telphin.ru/api/ver1.0/application.

Получение токена доступа доверенным приложением

Для получения токена приложение должно сделать POST-запрос на URL https://apiproxy.telphin.ru/oauth/token. Параметры передаются в теле запроса в формате application/x-www-form-urlencoded:

ПараметрОписание
grant_typeВсегда должен иметь значение client_credentials
client_idApp ID, сгенерированный при создании суперприложения
client_secretApp Secret, сгенерированный при создании суперприложения

API-сервер АТС отвечает приложению. Параметры ответа:

ПараметрОписание
access_tokenТокен доступа. Используется приложением для API-запросов
expires_inПериод времени в секундах, в течение которого токен действителен
token_typeТип токена всегда имеет значение Bearer

Передача запросов с использованием токена

Запросы к API с токеном доступа

Полученный токен доступа необходимо передавать в заголовке Authorization в формате «Bearer <access_token>» в каждом запроса к API. Пример заголовка:

Authorization: Bearer pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes

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

Пример запроса на получение информации об авторизованном пользователе через программу curl:

curl -H "Authorization: Bearer pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes" https://apiproxy.telphin.ru/api/ver1.0/user/
{
"admin": false,
"client_id": 12,
"dealer_id": null,
"extension_group_id": null,
"extension_id": null,
"id": 20,
"login": "client1"
}