Чтобы работать с API Диадока, нужно авторизоваться. Сейчас Диадок поддерживает две схемы авторизации:
Диадок предоставляет возможность аутентифицироваться по протоколу OpenID Connect. Аутентификация происходит с помощью сервиса OpenID Провайдера — сервера, который выдает токен доступа к продукту.
Токен доступа (access_token) — уникальный код, который позволяет идентифицировать пользователя и выполнять действия от его имени в API Диадока. Его нужно передавать в методы API в HTTP-заголовке Authorization.
Чтобы реализовать эту схему аутентификации, выполните шаги:
Оставьте заявку на странице интеграции. После этого с вами свяжется менеджер, предоставит вам доступ в Кабинет интегратора и выдаст идентификатор вашего приложения client_id.
Выпустите в Кабинете интегратора ключ приложения client_secret по инструкции. Это секретный ключ, не передавайте его третьим лицам.
Выберите подходящий для вашего приложения алгоритм по схеме ниже:
Затем:
укажите выбранный алгоритм в Кабинете интегратора в настройке приложения «Способ получения токенов»,
реализуйте выбранный алгоритм в вашем приложении согласно инструкции:
Получите с помощью выбранного алгоритма токен доступа access_token и используйте его в заголовке Authorization при вызовах методов API Диадока:
Authorization: Bearer <access_token>
Пример вызова метода
GET /GetMyOrganizations
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Accept: application/json
Обновите токен доступа access_token до истечения времени его жизни.
- Примеры реализации аутентификации через OpenID Connect в клиентском приложении можно найти по следующим ссылкам:
-
Алгоритм подходит для приложений с серверной частью (c бэкендом).
Примечание
Для описанного алгоритма в открытом доступе есть готовые решения: например, для JS, .Net и Java. Вы можете использовать их, чтобы не реализовывать взаимодействие с OpenID Провайдером самостоятельно.
Получите временный код подтверждения.
Для этого перенаправьте пользователя из приложения на страницу авторизации с помощью запроса GET /connect/authorize сервиса OpenID Провайдера.
В ответ OpenID Провайдер запросит у пользователя данные для входа и разрешения, а затем перенаправит его на указанный вами адрес и вернет в нем временный код подтверждения.
Подробнее
Параметры запроса GET /connect/authorize
response_type — ответ, который нужно получить от OpenID Провайдера. Укажите значение code.
client_id — идентификатор вашего приложения.
scope — список прав доступа, которые необходимы приложению в текущей сессии. Укажите следующие значения для доступа к данным Диадока:
openid — для взаимодействие с Провайдером по OpenID Connect,
profile — для получения основной информация о пользователе,
email — для получения адреса электронной почты пользователя,
offline_access — для доступа к refresh_token для обновления токена,
Diadoc.PublicAPI.Staging — для работы с тестовым пространством Диадока,
Diadoc.PublicAPI — для работы с продуктовым пространством Диадока.
redirect_uri — ссылка, на которую будет перенаправлен пользователь после аутентификации.
nonce — строка, предназначенная для проверки того, что запрос связан с токеном доступа. Она должна вернутся при получении токена доступа.
Все передаваемые параметры должны быть в формате url_encoded.
Пример запроса
GET /connect/authorize
?response_type=code
&client_id={{client_id}}
&scope=openid profile email offline_access Diadoc.PublicAPI
&redirect_uri=http://www.example.com/
&nonce=n-0S6_WzA2Mj HTTP/1.1
Host: identity.kontur.ru
Content-type: application/x-www-form-urlencoded
В ответ метод перенаправит пользователя на страницу аутентификации. После того, как пользователь введет свои данные и выдаст разрешения на странице аутентификации, OpenID Провайдер перенаправит его на URL-адрес, указанный в поле redirect_uri. В нем будет содержаться сгенерированный временный код подтверждения и другие параметры.
Параметры ответа в строке URL
code — временный код подтверждения, который нужно обменять на токен доступа access_token.
state — cтрока состояния, которую OpenID Провайдер возвращает без изменения.
scope — список прав доступа, которые выдал пользователь вашему приложению.
error — ошибка аутентификации access_denied. Возвращается вместо кода подтверждения, если пользователь или сервер по какой-то причине не выдал разрешение на доступ к данным.
Пример ответа с кодом подтверждения
HTTP/1.1 302 Found
Location: https://www.example.com
?code=SplxlOBeZQQYbYS6WxSbIA
&state=af0ifjsldkj
&scope=openid profile email offline_access Diadoc.PublicAPI
Пример ответа с ошибкой
HTTP/1.1 302 Found
Location: https://www.example.com
?error=access_denied
&error_description=
&state=af0ifjsldkj
Обменяйте временный код подтверждения на токен доступа access_token.
Для этого выполните запрос POST /connect/token сервиса OpenID Провайдера.
В ответе метод вернет токен доступа access_token, время его жизни и токен обновления refresh_token, с помощью которого можно обновить токен доступа.
Подробнее
Параметры запроса POST /connect/token
grant_type — способ запроса токена. Укажите значение authorization_code.
code — временный код подтверждения.
client_id — идентификатор вашего приложения.
client_secret — ключ приложения вашего приложения.
redirect_uri — ссылка, на которую получен код подтверждения.
Все передаваемые параметры должны быть в формате url_encoded.
Пример запроса
POST /connect/token HTTP/1.1
Host: identity.kontur.ru
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
code=SplxlOBeZQQYbYS6WxSbIA
client_id={{client_id}}
client_secret={{client_secret}}
redirect_uri=http://www.example.com
Если запрос был выполнен успешно, OpenID Провайдер вернет в ответе токен доступа access_token и токен для обновления refresh_token.
Если токен выдать не удалось, OpenID Провайдер вернет в ответе ошибку.
Параметры ответа POST /connect/token
access_token — токен доступа.
token_type — тип токена. Всегда имеет значение Bearer.
refresh_token — токен для обновления токена доступа.
expires_in — время жизни токена доступа access_token в секундах.
id_token — токен авторизации.
Пример ответа
200 OK
Content-type: application/json
{
"access_token": "811d58...40",
"token_type": "Bearer",
"refresh_token":"RjY2NjM5NzA2OWJjuE7c",
"expires_in": 3600,
"id_token": "eyJhbGciOifQ.ewogI3pAKfQ.ggW8hq-rvKMzqg"
}
Вы можете обновить токен доступа access_token до истечения времени его жизни, чтобы пользователю не пришлось повторно проходить аутентификацию.
Алгоритм подходит для приложений, в которых пользователю сложно вводить данные для аутентификации, например: desktop-приложения, консольные приложения, смарт-устройства, телевизоры. Этот способ получения токена подразумевает, что вместо своих данных пользователь может ввести в браузере некий код, полученный от приложения.
Получите временный код подтверждения.
Для этого выполните запрос POST /connect/deviceauthorization сервиса OpenID Провайдера.
В ответ OpenID Провайдер вернет приложению временный код подтверждения, код проверки пользователя и URI для авторизации.
Подробнее
Параметры запроса POST /connect/deviceauthorization
client_id — идентификатор вашего приложения.
client_secret — ключ приложения вашего приложения.
scope — список прав доступа, которые необходимы приложению в текущей сессии. Укажите следующие значения для доступа к данным Диадока:
openid — для взаимодействие с Провайдером по OpenID Connect,
profile — для получения основной информация о пользователе,
email — для получения адреса электронной почты пользователя,
offline_access — для доступа к refresh_token для обновления токена,
Diadoc.PublicAPI.Staging — для работы с тестовым пространством Диадока,
Diadoc.PublicAPI — для работы с продуктовым пространством Диадока.
Все передаваемые параметры должны быть в формате url_encoded.
Пример запроса
POST /connect/deviceauthorization HTTP/1.1
Host: identity.kontur.ru
Content-Type: application/x-www-form-urlencoded
client_id={{client_id}}
client_secret={{client_secret}}
scope=openid profile email offline_access Diadoc.PublicAPI
Параметры ответа POST /connect/deviceauthorization
device_code — временный код подтверждения, который нужно обменять на токен доступа access_token.
user_code — код, который пользователь должен ввести на странице ввода кода в приложении.
verification_uri — URI страницы, на которую нужно перенаправить пользователя для ввода кода, если приложение не умеет открывать пользовательский браузер.
verification_uri_complete — URI страницы, на которую нужно перенаправить пользователя в браузере.
interval — периодичность попыток обмена device_code на access_token в секундах.
expires_in — время жизни токена доступа access_token в секундах.
Пример ответа с кодом подтверждения
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"device_code":"NGU5OWFiNjQ5YmQwNGY3YTdmZTEyNzQ3YzQ1YSA",
"user_code": "BDWPHQPK",
"verification_uri": "https://identity.kontur.ru/device",
"verification_uri_complete": "https://identity.kontur.ru/device?user-code=BDWPHQPK",
"interval": 3,
"expires_in": 300
}
Пример ответа с ошибкой
HTTP/1.1 400 OK
Content-Type: application/json
Cache-Control: no-store
{
"error": "invalid_client"
}
Перенаправьте пользователя на страницу авторизации, где он должен ввести свои данные и выдать доступ вашему приложению.
Подробнее
Это можно сделать следующими способами:
Открыть в браузере ссылку, полученную в verification_uri_complete.
Отрисовать пользователю QR-код со ссылкой, полученной в verification_uri_complete. Отсканировав этот код, пользователь перейдет на страницу авторизации.
После этого пользователь должен перейти по предложенной ссылке на своем персональном устройстве, авторизоваться и разрешить вашему приложению получить доступ к данным.
Обменяйте временный код подтверждения на токен доступа access_token.
В то время, как пользователь авторизуется, приложение должно периодически выполнять запрос POST /connect/token сервиса OpenID Провайдера до тех пор, пока не получит токен доступа или ошибку.
Подробнее
В ответ на запрос POST /connect/token OpenID Провайдер может вернуть:
ошибку authorization_pending — пользователь не завершил авторизацию.
ошибку access_denied — на странице авторизации пользователь отказался выдать требуемый доступ.
ошибку expired_token — срок действия временного кода подтверждения истек.
токен доступа access_token — пользователь авторизовался и выдал требуемый доступ.
Приложение должно повторять запрос все время, пока OpenID Провайдер возвращает в ответ authorization_pending.
Параметры запроса POST /connect/token
grant_type — тип ответа. Укажите значение urn:ietf:params:oauth:grant-type:device_code.
client_id — идентификатор вашего приложения.
client_secret — ключ приложения вашего приложения.
scope — список прав доступа, которые необходимы приложению в текущей сессии.
device_code — временный код подтверждения.
Все передаваемые параметры должны быть в формате url_encoded.
Пример запроса
POST /connect/token HTTP/1.1
Host: identity.kontur.ru
Content-type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:device_code
client_id={{client_id}}
client_secret={{client_secret}}
scope=openid profile email offline_access Diadoc.PublicAPI
device_code=NGU5OWFiNjQ5YmQwNGY3YTdmZTEyNzQ3YzQ1YSA
Если запрос был выполнен успешно, OpenID Провайдер вернет в ответе токен доступа access_token и токен для обновления refresh_token.
Если токен выдать не удалось, OpenID Провайдер вернет в ответе ошибку.
Параметры ответа POST /connect/token
access_token — токен доступа.
id_token — токен авторизации.
refresh_token — токен для обновления токена доступа.
token_type — тип токена. Всегда имеет значение Bearer.
expires_in — время жизни токена доступа access_token в секундах.
scope — список прав доступа, которые выдал пользователь вашему приложению.
Пример ответа с токеном доступа
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token":"AYjcyMzY3ZDhiNmJkNTY",
"id_token": "eyJhbGciOifQ.ewogI3pAKfQ.ggW8hq-rvKMzqg",
"refresh_token":"RjY2NjM5NzA2OWJjuE7c",
"token_type":"Bearer",
"expires_in":3600,
"scope":"openid profile email offline_access Diadoc.PublicAPI"
}
Пример ответа с ошибкой
HTTP/1.1 400 OK
Content-Type: application/json
Cache-Control: no-store
{
"error": "authorization_pending"
}
Вы можете обновить токен доступа access_token до истечения времени его жизни, чтобы пользователю не пришлось повторно проходить аутентификацию.
Время жизни токена доступа access_token ограничено. До истечения этого времени его нужно обновить, иначе методы API будут возвращать ошибки, а пользователю вновь придется авторизовываться в OpenID Провайдере.
Определить время жизни токена доступа access_token можно по значению поля expires_in, полученного вместе с токеном.
Чтобы обновить токен доступа access_token, используйте refresh_token, полученный вместе с ним при запросе. Для этого выполните запрос POST /connect/token сервиса OpenID Провайдера.
Примечание
Обратите внимание, что refresh_token вернется в ответе запросов на получение токена GET /connect/authorize и POST /connect/deviceauthorization только если вы указали в них параметр scope = offline_access.
Подробнее
Параметры запроса POST /connect/token
grant_type — способ запроса токена. Укажите значение refresh_token.
client_id — идентификатор вашего приложения.
client_secret — ключ приложения вашего приложения.
refresh_token — токен для обновления токена доступа.
Все передаваемые параметры должны быть в формате url_encoded.
Пример запроса
POST /connect/token HTTP/1.1
Host: identity.kontur.ru
Content-type: application/x-www-form-urlencoded
grant_type=refresh_token
client_id={{client_id}}
client_secret={{client_secret}}
refresh_token=1487e3f7ce5aea612e2d7727ded76ad574e30643046ae2c247ae9c94c6b61e71
Параметры ответа POST /connect/token
access_token — токен доступа.
token_type — тип токена. Всегда имеет значение Bearer.
expires_in — время жизни токена доступа access_token в секундах.
refresh_token — токен для обновления токена доступа.
Пример ответа
200 OK
Content-type: application/json
{
"access_token": "811d583cf85deb7ab67bd91b96a9a4bafb63d6a062d7dd72f81601b84c19dc40",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "fd672752f8e9c4a8eb083fb2375b3126ae37dc69a0cf46953ef9a6e3f5a692df"
}
Методы Диадока, которые работают с ящиком, контролируют доступ пользователя к этому ящику по следующему алгоритму:
Диадок извлекает из HTTP-заголовка Authorization значение параметра access_token и с его помощью определяет идентификатор пользователя. Если какое-то действие не удалось выполнить, метод вернет код ошибки 401 (Unauthorized). Это возможно в следующих случаях:
в запросе отсутствует HTTP-заголовок Authorization,
в HTTP-заголовке Authorization не указан access_token,
токен поврежден или просрочен.
По идентификатору пользователя Диадок находит ящики, к которым у пользователя есть доступ. Этот список ящиков совпадает с тем, что вернется в ответе метода GetMyOrganizations.
Диадок извлекает из параметров запроса идентификатор ящика. Если идентификатор ящика не входит в список ящиков, доступных пользователю, метод вернет код ошибки 403 (Forbidden).
Предупреждение
Способ авторизации с помощью методов API Диадока является устаревшим и не рекомендуется к использованию. Используйте вместо него авторизацию через OpenID Connect.
Для авторизации с помощью методов API нужна следующая информация:
ключ разработчика — уникальный идентификатор интегратора в формате GUID. Чтобы получить ключ разработчика, оставьте заявку на странице интеграции. Не передавайте свой ключ третьим лицам.
авторизационный токен — массив байтов, однозначно идентифицирующий пользователя.
Эту информацию нужно передавать в стандартном HTTP-заголовке Authorization в соответствии со схемой аутентификации Диадока DiadocAuth со следующими параметрами:
ddauth_api_client_id — определяет ключ разработчика,
ddauth_token — определяет авторизационный токен.
Значения параметров в заголовке отделяются от их имен символами «=», параметры разделяются символами «,». Например:
Authorization: DiadocAuth
ddauth_api_client_id=testClient-8ee1638deae84c86b8e2069955c2825a,
ddauth_token=3IU0iPhuhHPZ6lrlumGz4pICEedhQ1XmlMN1Pk8z0DJ51MXkcTi6Q3CODCC4xTMsjPFfhK6XM4kCJ4JJ42hlD499/Ui5WSq6lrPwcdp4IIKswVUwyE0ZiwhlpeOwRjNrvUX1yPrxr0dY8a0w8ePsc1DG8HAlZce8a0hZiWylMqu23d/vfzRFuA==
Подробная информация обо всех способах получения токена приведена на странице метода Authenticate (V3).
При вызове метода Authenticate в параметре ddauth_api_client_id HTTP-заголовка Authorization передайте ключ разработчика.
Необязательно вызывать метод Authenticate (V3) перед каждым обращением к методам API Диадока — авторизационные токены можно кэшировать. Мы рекомендуем сохранить и использовать полученный токен в течение всего сеанса работы. Полученный токен остается действительным в течение 24 часов.
Ключ разработчика и полученный авторизационный токен нужно передавать в каждый метод API. Для этого при вызове методов API нужно к каждому запросу добавлять HTTP-заголовок Authorization с параметрами ddauth_api_client_id и ddauth_token. Например, HTTP-запрос на получение списка доступных пользователю ящиков будет выглядеть так:
GET https://diadoc-api.kontur.ru/GetMyOrganizations HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: DiadocAuth ddauth_api_client_id=testClient-8ee1638deae84c86b8e2069955c2825a,ddauth_token=3IU0iPhuhHPZ6lrlumGz4pICEedhQ1XmlMN1Pk8z0DJ51MXkcTi6Q3CODCC4xTMsjPFfhK6XM4kCJ4JJ42hlD499/Ui5WSq6lrPwcdp4IIKswVUwyE0ZiwhlpeOwRjNrvUX1yPrxr0dY8a0w8ePsc1DG8HAlZce8a0hZiWylMqu23d/vfzRFuA==
Методы, работающие с определенным ящиком, контролируют доступ к нему по следующему алгоритму:
Сервер Диадока извлекает из HTTP-заголовка Authorization значение параметра ddauth_token. После его декодирования сервер получает идентификатор пользователя. Если какое-то действие не удалось выполнить, метод вернет код ошибки 401 (Unauthorized). Это возможно в случаях, когда:
в запросе отсутствует HTTP-заголовок Authorization,
нет параметра ddauth_token,
токен поврежден или просрочен,
указан некорректный ddauth_api_client_id.
По идентификатору пользователя Диадок находит ящики, к которым у пользователя есть доступ. Список ящиков совпадает со списком, который вернет метод GetMyOrganizations.
Сервер извлекает идентификатор ящика из параметров запроса. Если идентификатор ящика не входит в список ящиков, доступных пользователю, метод вернет код ошибки 403 (Forbidden).
См. также
- Методы для аутентификации:
-