Авторизация
В основе работы API Диадока лежит контекст пользователя, поэтому перед началом работы нужно аутентифицироваться.
Аутентификация в Диадоке происходит по протоколу OpenID Connect с помощью сервиса OpenID Провайдера — сервера, который выдает токен доступа к продукту.
Токен доступа (access_token) — уникальный код, который позволяет идентифицировать пользователя и выполнять действия от его имени в API Диадока. Его нужно передавать в методы API в HTTP-заголовке Authorization.
Чтобы реализовать аутентификацию в интеграционном решении, выполните шаги:
-
Оставьте заявку на странице интеграции. После этого с вами свяжется менеджер, предоставит доступ в Кабинет интегратора и выдаст идентификатор вашего приложения
client_id. -
Выпустите в Кабинете интегратора ключ приложения
client_secret. Для этого:-
Перейдите в Кабинет интегратора.
-
В разделе «API-ключи» нажмите «+ Выпустить ключ».
-
Сохраните полученный ключ в надежное место: он понадобится для следующих действий. Это секретный ключ, не передавайте его третьим лицам.
-
-
Выберите подходящий для вашего приложения алгоритм аутентификации и получите с его помощью токен доступа
access_token.- Refresh Token Flow — подходит для роботизированных приложений, не позволяющих взаимодействовать с пользователем для авторизации. Самый простой алгоритм для автоматического обновления токена, подходит для большинства решений.
- Authorization Code Flow — подходит для бэкенд-приложений, которые могут отображать страницу авторизации.
- Device Authorization Flow — подходит для приложений с ограничениями на ввод данных для аутентификации, например, для desktop-приложений или 1С.
Выбранный способ аутентификации можно изменить в Кабинете интегратора, но изменения применятся не сразу — потребуется около 5 минут.
-
Используйте полученный токен доступа
access_tokenв заголовкеAuthorizationпри вызовах методов API Диадока:Authorization: Bearer <access_token>GET /GetMyOrganizationsHost: diadoc-api.kontur.ruAuthorization: Bearer {{access_token}}Accept: application/jsonОбратите внимание, что время жизни токена ограничено: токен нужно обновить, пока он еще активен.
Схема Client Credentials Flow для Диадока не подходит: для выпуска токенов нужен первичный пользовательский контекст и подтверждение прав доступа.
Обратите внимание, что запросы авторизации уходят не в Диадок, а на identity.kontur.ru. Поэтому адрес API Диадока для вызова /connect/authorize и /connect/token не подходит.
При авторизации в качестве client_secret нужно передать ключ API со страницы приложения в Кабинете интегратора.
Чтобы приложение работало без участия оператора, обновляйте токен доступа access_token с помощью refresh_token. Срок жизни access_token ограничен, схема обновления описана в разделе Обновление токена.
Выбор учетной записи для интеграции
Токен отражает права того сотрудника, который подтвердил доступ. Поэтому для интеграции лучше использовать сервисную учетную запись с нужными правами, а не личную запись сотрудника. В этом случае схема интеграции не сломается, если сотрудник уйдет из компании или сменит должность. Сохраняйте доступ к сервисной учетной записи и привязанному к ней адресу электронной почты.
В зависимости от реализуемого сценария у учетной записи должны быть определенные права:
- отправка документов — право на создание и редактирование документов;
- подписание — право подписывать документы;
- вызов административных методов (например, CreateEmployee) — права администратора.
Получение токена доступа
Получение токена через Refresh Token Flow
Алгоритм подходит для роботизированных приложений, которые не могут взаимодействовать с пользователем для авторизации.
Этот способ получения токена подразумевает, что refresh_token выпускается один раз в Кабинете интегратора, а затем приложение получает access_token без участия оператора — по client_id, client_secret и refresh_token.
Чтобы реализовать эту схему, нужно настроить Кабинет интегратора:
-
Перейдите в Кабинет интегратора.
-
В разделе «Способ получения токенов (clientMode)» выберите значение «AuthorizationCode».
-
После этого в разделе «Выпуск токенов» выберите необходимые для работы приложения скоупы и нажмите кнопку «Получить refresh-токен».
Если вы впервые выпускаете токен, перед вами появится следующее сообщение.
Нажмите кнопку «Подтвердить» и подождите 2-5 минут, чтобы изменения вступили в силу. После этого снова приступите к выпуску refresh-токена.
-
В окне выбора учетной записи выберите ту запись, для которой хотите получить токен.
Если вы хотите получить токен для технической учетной записи, а не для текущей, нажмите «Скопировать ссылку». Полученную ссылку откройте в браузере, в котором не проходила авторизация (или в режиме «Инкогнито»), а затем авторизуйтесь под технической учетной записью.
-
Подтвердите доступы для работы приложения.
-
Введите API-ключ и нажмите «Получить refresh-токен». Скопируйте полученный refresh-токен и сохраните его для использования в вашем интеграционном решении.
После получения refresh-токена вы можете изменить способ получения токенов (clientMode) в вашем приложении на любой другой. Полученный refresh-токен при этом останется активен и будет работать в вашем интеграционном решении без изменений.
С помощью полученного refresh-токена вы можете получить токен доступа access_token по алгоритму обновления. Обновлять refresh-токен не требуется: он будет действителен до тех пор, пока вы не отзовете его в Кабинете интегратора. Срок жизни refresh-токен — 30 дней, счетчик его срока жизни обновляется при каждом использовании refresh-токена для получения токена доступа access_token.
Не забывайте обновлять токен доступа access_token до истечения времени его жизни (обычно составляет 24 часа).
Получение токена через Authorization Code Flow
Алгоритм подходит для приложений с серверной частью (с бэкендом).
Для настройки интеграционного решения на работу с OpenID Connect нужно реализовать собственное клиентское приложение или воспользоваться готовыми сертифицированными библиотеками OpenID Connect.
Чтобы реализовать эту схему, нужно настроить Кабинет интегратора:
-
Перейдите в Кабинет интегратора.
-
В разделе «Способ получения токенов (clientMode)» выберите значение «AuthorizationCode».
-
Укажите адрес перенаправления. Если поле адреса пустое, вызов
/connect/authorizeвернет ошибку. Для тестирования можно указатьhttp://localhost, а для рабочего приложения заведите отдельную страницу под адрес перенаправления.
Примеры реализации описанного алгоритма можно посмотреть в проекте веб-приложения.
Вы можете использовать примеры, чтобы не реализовывать взаимодействие с 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— адрес ресурса интегратора, на который будет перенаправлен пользователь после аутентификации. Передайте в этом параметре адрес своего ресурса, на котором вы сможете принять перенаправление и обработать параметры адреса. OpenID Провайдер получит данные пользователя для входа и разрешения, а затем перенаправит пользователя на указанный адрес, вернув в его параметрах временный код подтверждения. Такой же адрес должен быть указан в списке разрешенных адресов в Кабинете интегратора.nonce— строка, предназначенная для проверки того, что запрос связан с токеном доступа. Она должна вернуться при получении токена доступа.
Все передаваемые параметры должны быть в формате url_encoded.
Пример HTTP-запроса:
GET /connect/authorize?response_type=code&client_id={{client_id}}&scope=openid profile email offline_access Diadoc.PublicAPI Diadoc.PublicAPI.Staging&redirect_uri=https://www.example.com&nonce=n-0S6_WzA2Mj HTTP/1.1Host: identity.kontur.ruContent-type: application/x-www-form-urlencodedПример cURL-запроса для UNIX:
bashcurl --location --request GET 'https://identity.kontur.ru/connect/authorize?response_type=code&client_id={{client_id}}&scope=openid%20profile%20email%20offline_access%20Diadoc.PublicAPI%20Diadoc.PublicAPI.Staging&redirect_uri=https://www.example.com&nonce=n-0S6_WzA2Mj'Пример запроса для Windows PowerShell:
powershellcurl.exe "https://identity.kontur.ru/connect/authorize?response_type=code&client_id={{client_id}}&scope=openid%20profile%20email%20offline_access%20Diadoc.PublicAPI%20Diadoc.PublicAPI.Staging&redirect_uri=https://www.example.com&nonce=n-0S6_WzA2Mj"В ответ метод перенаправит пользователя на страницу аутентификации. Из ее кода нужно получить следующие значения:
-
config.requestParams— значение для сверки с параметромnonce, который был передан при запросе. -
BackUrl— ссылка на страницу авторизации в следующем формате:BackUrl: "https://identity.kontur.ru/connect/authorize?nonce=n-0S6_WzA2Mj\u0026client_id={{client_id}}\u0026redirect_uri=https%3A%2F%2Fwww.example.com\u0026response_type=code\u0026scope=openid%20profile%20email%20offline_access%20Diadoc.PublicAPI%20Diadoc.PublicAPI.Staging"
В строке
BackUrlв качестве разделителя используются значения\u0026. После получения ссылки нужно заменить эти значения на амперсанд (&) и открыть ссылку в браузере. После этого пользователь должен подтвердить доступ кнопкой «Разрешить» под той учетной записью, от имени которой будут отправляться запросы.После того, как пользователь введет свои данные и выдаст разрешения на странице аутентификации, OpenID Провайдер перенаправит его на адрес, указанный в поле
redirect_uri. В нем будет содержаться сгенерированный временный код подтверждения и другие параметры.Параметры ответа в строке URL:
code— временный код подтверждения, который нужно обменять на токен доступаaccess_tokenна следующем этапе авторизации.state— строка состояния, которую OpenID Провайдер возвращает без изменения.scope— список прав доступа, которые выдал пользователь вашему приложению.error— ошибка аутентификацииaccess_denied. Возвращается вместо кода подтверждения, если пользователь или сервер по какой-то причине не выдал разрешение на доступ к данным.
Пример ответа с кодом подтверждения:
HTTP/1.1 302 FoundLocation: https://www.example.com?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj&scope=openid profile email offline_access Diadoc.PublicAPI Diadoc.PublicAPI.StagingПример ответа с ошибкой:
HTTP/1.1 302 FoundLocation: 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— временный код подтверждения. Код действителен в течение 5 минут. Если время истекло, необходимо перенаправить пользователя на страницу авторизации.client_id— идентификатор вашего приложения.client_secret— ключ вашего приложения.redirect_uri— адрес, на который получен код подтверждения.
Все передаваемые параметры должны быть в формате url_encoded.
Пример HTTP-запроса:
POST /connect/token HTTP/1.1Host: identity.kontur.ruContent-Type: application/x-www-form-urlencodedgrant_type=authorization_codecode=SplxlOBeZQQYbYS6WxSbIAclient_id={{client_id}}client_secret={{client_secret}}redirect_uri=https://www.example.comПример cURL-запроса для UNIX:
bashcurl --location --request POST 'https://identity.kontur.ru/connect/token' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'grant_type=authorization_code' \--data-urlencode 'client_id={{client_id}}' \--data-urlencode 'client_secret={{client_secret}}' \--data-urlencode 'redirect_uri=https://www.example.com' \--data-urlencode 'code={{code}}'Пример запроса для Windows PowerShell:
powershellcurl.exe --location --request POST 'https://identity.kontur.ru/connect/token'--header 'Content-Type: application/x-www-form-urlencoded'--data-urlencode 'grant_type=authorization_code'--data-urlencode 'code={{code}}'--data-urlencode 'client_id={{client_id}}'--data-urlencode 'client_secret={{client_secret}}'--data-urlencode 'redirect_uri=https://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 OKContent-type: application/json{"access_token": "811d58...40","token_type": "Bearer","refresh_token":"RjY2NjM5NzA2OWJjuE7c","expires_in": 3600,"id_token": "eyJhbGciOifQ.ewogI3pAKfQ.ggW8hq-rvKMzqg"}
Вы можете обновить токен доступа access_token до истечения времени его жизни, чтобы пользователю не пришлось повторно проходить аутентификацию.
Получение токена через Device Authorization Flow
Алгоритм подходит для приложений, в которых пользователю сложно вводить данные для аутентификации, например: desktop-приложения, консольные приложения, смарт-устройства, телевизоры. Этот способ получения токена подразумевает, что вместо своих данных пользователь может ввести в браузере некий код, полученный от приложения.
Для настройки интеграционного решения на работу с OpenID Connect нужно реализовать собственное клиентское приложение или воспользоваться готовыми сертифицированными библиотеками OpenID Connect.
Пример реализации описанного алгоритма можно посмотреть в проекте консольного приложения.
Чтобы реализовать эту схему, нужно настроить Кабинет интегратора:
-
Перейдите в Кабинет интегратора.
-
В разделе «Способ получения токенов (clientMode)» выберите значение «Device».
Чтобы получить токен доступа, выполните следующие шаги:
-
Получите временный код подтверждения.
Для этого выполните запрос
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.
Пример HTTP-запроса:
POST /connect/deviceauthorization HTTP/1.1Host: identity.kontur.ruContent-Type: application/x-www-form-urlencodedclient_id={{client_id}}client_secret={{client_secret}}scope=openid profile email offline_access Diadoc.PublicAPI Diadoc.PublicAPI.StagingПример cURL-запроса для UNIX:
bashcurl --location --request POST 'https://identity.kontur.ru/connect/deviceauthorization' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'client_id={{client_id}}' \--data-urlencode 'client_secret={{client_secret}}' \--data-urlencode 'scope=openid profile email offline_access Diadoc.PublicAPI Diadoc.PublicAPI.Staging'Пример запроса для Windows PowerShell:
powershellcurl.exe --location --request POST 'https://identity.kontur.ru/connect/deviceauthorization'--header 'Content-Type: application/x-www-form-urlencoded'--data-urlencode 'client_id={{client_id}}'--data-urlencode 'client_secret={{client_secret}}'--data-urlencode 'scope=openid profile email offline_access Diadoc.PublicAPI Diadoc.PublicAPI.Staging'Параметры ответа POST /connect/deviceauthorization:
device_code— временный код подтверждения, который нужно обменять на токен доступаaccess_token.user_code— код, который пользователь должен ввести на странице ввода кода в приложении.verification_uri— URI страницы, на которую нужно перенаправить пользователя для ввода кода, если приложение не умеет открывать пользовательский браузер.verification_uri_complete— URI страницы, на которую нужно перенаправить пользователя в браузере.interval— периодичность попыток обменаdevice_codeнаaccess_tokenв секундах.expires_in— время жизни временного кода подтвержденияdevice_codeв секундах.
Пример ответа с кодом подтверждения:
HTTP/1.1 200 OKContent-Type: application/jsonCache-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 Bad RequestContent-Type: application/jsonCache-Control: no-store{"error": "invalid_client"} -
Перенаправьте пользователя на страницу авторизации, где он должен ввести свои данные и выдать доступ вашему приложению.
Это можно сделать следующими способами:
- Открыть в браузере ссылку, полученную в
verification_uri_complete. - Отрисовать пользователю QR-код со ссылкой, полученной в
verification_uri_complete. Отсканировав этот код, пользователь перейдет на страницу авторизации.
После этого пользователь должен перейти по предложенной ссылке на своем персональном устройстве, авторизоваться и разрешить вашему приложению получить доступ к данным.
Обратите внимание, что ссылка действительна в течение ограниченного срока — этот срок возвращается в поле
expires_inи обычно составляет 300 секунд. Если пользователь за это время не успеет использовать ссылку изverification_uri_complete, то нужно будет повторить первый этап и получить новую ссылку. - Открыть в браузере ссылку, полученную в
-
Обменяйте временный код подтверждения на токен доступа
access_token.В то время, как пользователь авторизуется, приложение должно периодически выполнять запрос
POST /connect/tokenк сервису OpenID Провайдера до тех пор, пока не получит токен доступа или ошибку.В ответ на запрос
POST /connect/tokenOpenID Провайдер может вернуть:- ошибку
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.
Пример HTTP-запроса:
POST /connect/token HTTP/1.1Host: identity.kontur.ruContent-type: application/x-www-form-urlencodedgrant_type=urn:ietf:params:oauth:grant-type:device_codeclient_id={{client_id}}client_secret={{client_secret}}scope=openid profile email offline_access Diadoc.PublicAPI Diadoc.PublicAPI.Stagingdevice_code=NGU5OWFiNjQ5YmQwNGY3YTdmZTEyNzQ3YzQ1YSAПример cURL-запроса для UNIX:
bashcurl --location --request POST 'https://identity.kontur.ru/connect/token' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \--data-urlencode 'client_id={{client_id}}' \--data-urlencode 'client_secret={{client_secret}}' \--data-urlencode 'scope=openid profile email offline_access Diadoc.PublicAPI Diadoc.PublicAPI.Staging' \--data-urlencode 'device_code={{device_code}}'Пример запроса для Windows PowerShell:
powershellcurl.exe --location --request POST 'https://identity.kontur.ru/connect/token'--header 'Content-Type: application/x-www-form-urlencoded'--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code'--data-urlencode 'client_id={{client_id}}'--data-urlencode 'client_secret={{client_secret}}'--data-urlencode 'scope=openid profile email offline_access Diadoc.PublicAPI Diadoc.PublicAPI.Staging'--data-urlencode 'device_code={{device_code}}'Если запрос был выполнен успешно, 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 OKContent-Type: application/jsonCache-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 Diadoc.PublicAPI.Staging"}Пример ответа с ошибкой:
HTTP/1.1 400 Bad RequestContent-Type: application/jsonCache-Control: no-store{"error": "authorization_pending"} - ошибку
Вы можете обновить токен доступа access_token до истечения времени его жизни, чтобы пользователю не пришлось повторно проходить аутентификацию.
Обновление токена
Время жизни токена доступа access_token ограничено. Это значит, что по его истечении пользователю нужно будет заново проходить авторизацию, иначе методы API будут возвращать ошибки. Чтобы не повторять операцию авторизации, достаточно один раз получить от пользователя разрешения и подтверждения, получить access_token, а после — только обновлять полученный токен. Так работает «авторизация без участия пользователя».
Обратите внимание, что обновление токена нужно реализовать на стороне приложения самостоятельно: готовой настройки для этого нет.
Токен access_token нужно обновить до истечения времени его жизни. Определить время жизни можно с помощью поля expires_in, которое возвращается вместе с токеном доступа.
Чтобы обновить токен доступа, используйте один из следующих способов:
- повторно отправьте пользователя на страницу авторизации OpenID Провайдера:
- Выполните шаги Получение токена через Authorization Code Flow или Получение токена через Device Authorization Flow еще раз: в параметре
scopeобязательно укажитеoffline_access, иначе токенrefresh_tokenне вернется. - Сохраните из ответа
access_tokenиrefresh_token. В полеexpires_inвернется срок жизниaccess_tokenв секундах (обычно 86400 секунд). - Обменяйте
refresh_tokenна новую пару токенов до конца периодаexpires_in. Рекомендуем менять токены заранее — например, раз в 12 часов. - Замените сохраненный
refresh_tokenзначением из ответа. При каждом обмене приходит новый токен, старый больше не понадобится. - Повторяйте обмен не реже раза в 30 дней — столько действителен
refresh_token.
- Выполните шаги Получение токена через Authorization Code Flow или Получение токена через Device Authorization Flow еще раз: в параметре
- выполните запрос
POST /connect/tokenсервиса OpenID Провайдера сrefresh_token, полученным вместе сaccess_token.
Обратите внимание, что refresh_token вернется в ответе POST /connect/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.
Пример HTTP-запроса:
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"
}
Обновление токенов без участия пользователя прекращается в следующих случаях:
- в
scopeне указанoffline_access: в этом случаеrefresh_tokenне вернется; - сохраненное в приложении значение
refresh_tokenне заменено на новое из ответа: в этом случае при следующем обновлении будет использован старый токен, время жизни которого истекло; - токен не обновлялся больше срока своей жизни (обычно 30 дней): в этом случае его действие истекает и пользователю придется выдавать разрешение заново;
- у пользователя, который выдал разрешение, больше нет прав на выдачу: в этом случае сервис вернет ошибку
403 (Forbidden).
Проверка прав пользователя
Методы Диадока, которые работают с ящиком, контролируют доступ пользователя к этому ящику по следующему алгоритму:
- Диадок извлекает из HTTP-заголовка
Authorizationзначение параметраaccess_tokenи с его помощью определяет идентификатор пользователя. Если какое-то действие не удалось выполнить, метод вернет код ошибки401 (Unauthorized). Это возможно в следующих случаях:- в запросе отсутствует HTTP-заголовок
Authorization, - в HTTP-заголовке
Authorizationне указанaccess_token, - токен поврежден или просрочен.
- в запросе отсутствует HTTP-заголовок
- По идентификатору пользователя Диадок находит ящики, к которым у пользователя есть доступ.
- Диадок извлекает из параметров запроса идентификатор ящика. Если идентификатор ящика не входит в список ящиков, доступных пользователю, метод вернет код ошибки
403 (Forbidden).
Ошибки авторизации
| Ошибка | Причина | Что проверить |
|---|---|---|
400 (Bad Request) или 401 (Unauthorized)на /connect/authorize | В приложении не указан адрес перенаправления или запрос был отправлен не на identity.kontur.ru. | Заполните адрес перенаправления в приложении и отправьте запрос на identity.kontur.ru. |
401 (Unauthorized) в ответ наAuthenticate (V3) | Ключ разработчика выпущен для другой площадки. | Используйте ключ той площадки, к которой обращаетесь. |
403 (Forbidden) | Токен и ящик относятся к разным площадкам. Идентификатор ящика, полученный методом GetOrganization на главной площадке, не подойдет для использования на тестовой площадке, и наоборот. | Для каждой площадки получите и используйте разные идентификаторы ящиков. |
| У пользователя нет права подписи в организации. Метод вернет ошибку с текстом «У вас нет права подписи в организации», а в заголовке ответа X-Diadoc-ErrorCode будет содержаться значениеDocumentService.EmployeeCannotSignDocuments. | Выдайте пользователю право SignDocuments. Инструкцияпо управлению правами сотрудника приведена в разделе Управление правами сотрудника. | |
| Сотрудник заблокирован в организации. | Обратитесь к администратору организации. | |
| Пользователь доверенного сервиса не допущен к ящику. | Проверьте настройки доступа для доверенного сервиса. | |
| Запрос сервисного пользователя отправлен с IP-адреса, который не входит в доверенные сети организации. | Добавьте IP-адрес в доверенные сети или обратитесь к администратору организации. | |
| API-клиент заблокирован за опасную активность. | Обратитесь в техническую поддержку<br /><https://www.diadoc.ru/support>__. | |
| Пользователь не зарегистрирован в организации, а условия авторегистрации не выполняются. Если в организации есть действующий администратор, метод отправит ему запрос на доступ к ящику и вернет ошибку с текстом Access to Box is<br />denied. Request to admins of Box was created. Please<br />try again later. | Повторите запрос после того, как администратор организации предоставит доступ к ящику. | |
| Способ входа не совпадает с тем, который настроен в организации: например, пользователь вошел по логину и паролю, а в организации обязателен вход через SSO-провайдера. | Войдите способом, который настроен в организации. | |
/connect/token не отдает токен по коду изAuthorization Code Flow | Срок жизни кода истек: обычно он живет 5 минут. | Повторите первый этап авторизации. |
Invalid auth token | Токен содержит лишний префикс или опечатки. | Убедитесь, что токен введен корректно и без опечаток. Правильный вид заголовка — Authorization: Bearer <access_token>, безaccess_token=. |
invalid_client при запросе токена в Postman | Запрос оформлен неверно. |
|
Причину ошибки, которую вернул метод Диадока, можно уточнить по заголовку ответа X-Diadoc-ErrorCode: он содержит идентификатор ошибки, например DiadocApi.Forbidden.