Создание и авторизация приложений

Мы обновили документацию, актуальная версия страницы доступна по ссылке: Создание и авторизация приложений

Для того, чтобы стороннее приложение могло использовать ресурсы системы, его необходимо создать и авторизовать

Создание приложения

Для создания приложения нужно перейти по адресу https://<hostname>/app/register, предварительно может понадобится ввод логина и пароля.

В форме регистрации требуется ввести имя (Application name) приложения, URL перенаправления (Redirect URL) для авторизации (возможно указать несколько через пробел или не указывать ни одного), выбрать тип приложения (Application Type)  – publictrusted или password_credentials, а также указать уровень доступа приложения  (Application Access) – Call API или All.

Типы приложений

Внимание

Тип password_credentials может быть установлен только администратором.

Тип приложения определяет допустимые методы получения токена доступа.

Приложениям с типом public доступен метод получения токена доступа через код авторизации, для чего требуется, чтобы пользователь прошел авторизацию в системе (authorization_code flow). 

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

Приложениям с типом password_credentials доступен метод получения токена доступа с помощью логина и пароля пользователя (password flow).

Уровни доступа приложений

Внимание

Уровень доступа All может быть установлен только администратором.

Существуют два уровня доступа приложений: Call API и All

Разделение приложений по уровням доступа предусмотрено из-за того, что некоторые приложения, в частности, веб-интерфейсы, ожидают, чтобы АТС клиента была сконфигурирована определенным образом, и изменения конфигурации другими приложениями могут нарушить работу такого веб-интерфейса. Поскольку, как правило, внешним приложениям не требуется изменять конфигурацию АТС, по умолчанию созданное приложение имеет уровень доступа Call API. Если же приложению требуется изменение конфигурации АТС, то возможно повысить его уровень с помощью администратора.

Уровень Call API  позволяет:

Изменение конфигурации приложениям с уровнем Call API недоступно.

Уровень All  – полный доступ –  позволяет приложению получать, изменять, добавлять и удалять ресурсы, доступные авторизованному пользователю, в том числе ресурсы конфигурации. Данный уровень доступа приложению может установить только администратор.

Внимание

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


После регистрации приложения системы выведет информацию о зарегистрированном приложении, в том числе сгенерированные App ID и App secret приложения, необходимые для авторизации. 

Список всех зарегистрированных пользователем приложений доступен по адресу https://<hostname>/app/

Авторизация приложения

Для авторизации приложений в системе используется протокол OAuth2.

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

  1. Приложение перенаправляет пользователя на URL авторизации https://<hostname>/oauth/authorize, передавая данные авторизации в качестве параметров GET-запроса в формате URL-encoded.

Параметр

Описание

response_type

Тип ответа, всегда должен иметь значение code

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

Пример запроса:

GET https://<hostname>/oauth/authorize?response_type=code&client_id=2bb0c19ea4df4b908cf2db51a1aea86b&redirect_uri=http%3A%2F%2Ftestsite.com%2Furl&scope=all


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

  2. Если пользователь разрешает доступ, система перенаправляет пользователя на Redirect URL приложения, указанного при регистрации, предавая в качестве параметра запроса код для получения токена доступа.

    GET https://<apphostname>/authorized?code=SpHCEr6qiCj1kZRTvEb36qZAqWqIHz
  3. Приложение делает POST-запрос на сервер системы на URL https://<hostname>/oauth/token, для получения токена доступа, используя полученный код.

    POST https://<hostname>/oauth/token

    Параметры передаются в теле запроса в формате application/x-www-form-urlencoded.

    Параметры запроса

    Параметр
    Описание
    grant_typeВсегда должен иметь значение authorization_code
    code

    Параметр code, полученный приложением на предыдущем шаге

    redirect_uriURI перенаправления. Должен совпадать с одним из указанных при создании приложения
    client_idApp ID, сгенерированный при создании приложения
    client_secretApp Secret, сгенерированный при создании приложения 
  4. Система отвечает приложению

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

    Параметр

    Описание

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

Авторизация доверенных приложений

Если приложение доверенное (trusted), то подтверждение пользователя не требуется, приложение получает токен доступа без участия пользователя.

Данный способ авторизации может быть полезен для создания различных скриптов автоматизации, которые исключают взаимодействие пользователя с приложением.

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

POST https://<hostname>/oauth/token

Параметры запроса

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

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

Параметр

Описание

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

Авторизация приложений через логин и пароль пользователя

Если приложение имеет тип password_credentials, то возможна авторизация данного приложения по схеме, используя логин и пароль пользователя.

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

POST https://<hostname>/oauth/token

Параметры запроса

Name
Description
grant_typeВсегда должен иметь значение password
client_idApp ID, сгенерированный при создании приложения
client_secretApp Secret, сгенерированный при создании приложения
usernameИмя пользователя, для которого требуется авторизовать приложения
passwordПароль пользователя, для которого требуется авторизовать приложения

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

Параметр

Описание

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

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

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

Authorization: Bearer ykX7vsJstZkUh1x3hG5sIeRgRaICMm

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

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

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

См. далее: Запросы к API – Быстрый старт


Использования токена регенерации (Refresh Token)

Токен доступа (access token) имеет ограниченное время жизни (передается в параметре expires_in). При авторизации публичных (public) и авторизуемых по паролю (password_credentials) приложений существует возможность регенерировать токен доступа, используя токен регенерации (refresh token). Этот подход позволяет получить новый токен доступа по истечении старого без участия пользователя, так как при регенерации токена доступа с помощью токена регерации не требуются какие-либо действия от пользователя.

Для приложений типа trusted токен регенерации отсуствует.

Токен регенерации также имеет ограниченное время жизни, и если регенерация токена не удалась (система ответит за запрос кодом 401 и сообщением "invalid_grant" в поле error), приложению необходимо повторно осуществить авторизацию.

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

POST https://<hostname>/oauth/token

Параметры запроса

Name
Description
grant_typeВсегда должен иметь значение refresh_token
refresh_tokenЗначение refresh_token, полученное с токеном, который требуется регенерировать
redirect_uriURI, по которому система будет посылать ответ. Должен совпадать с указанным при создании приложения
client_idApp ID, сгенерированный при создании приложения
client_secretApp Secret, сгенерированный при создании приложения

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

Параметр

Описание

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