Перейти к основному содержимому

Авторизация

В основе работы API Диадока лежит контекст пользователя, поэтому перед началом работы нужно аутентифицироваться.

Аутентификация в Диадоке происходит по протоколу OpenID Connect с помощью сервиса OpenID Провайдера — сервера, который выдает токен доступа к продукту.

Токен доступа (access_token) — уникальный код, который позволяет идентифицировать пользователя и выполнять действия от его имени в API Диадока. Его нужно передавать в методы API в HTTP-заголовке Authorization.

Чтобы реализовать аутентификацию в интеграционном решении, выполните шаги:

  1. Оставьте заявку на странице интеграции. После этого с вами свяжется менеджер, предоставит доступ в Кабинет интегратора и выдаст идентификатор вашего приложения client_id.

  2. Выпустите в Кабинете интегратора ключ приложения client_secret. Для этого:

    1. Перейдите в Кабинет интегратора.

    2. В разделе «API-ключи» нажмите «+ Выпустить ключ».

    3. Сохраните полученный ключ в надежное место: он понадобится для следующих действий. Это секретный ключ, не передавайте его третьим лицам.

  3. Выберите подходящий для вашего приложения алгоритм аутентификации и получите с его помощью токен доступа access_token.

    • Refresh Token Flow — подходит для роботизированных приложений, не позволяющих взаимодействовать с пользователем для авторизации. Самый простой алгоритм для автоматического обновления токена, подходит для большинства решений.
    • Authorization Code Flow — подходит для бэкенд-приложений, которые могут отображать страницу авторизации.
    • Device Authorization Flow — подходит для приложений с ограничениями на ввод данных для аутентификации, например, для desktop-приложений или 1С.

    Выбранный способ аутентификации можно изменить в Кабинете интегратора, но изменения применятся не сразу — потребуется около 5 минут.

  4. Используйте полученный токен доступа access_token в заголовке Authorization при вызовах методов API Диадока:

    Authorization: Bearer <access_token>

    Обратите внимание, что время жизни токена ограничено: токен нужно обновить, пока он еще активен.

Схема 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.

Чтобы реализовать эту схему, нужно настроить Кабинет интегратора:

  1. Перейдите в Кабинет интегратора.

  2. В разделе «Способ получения токенов (clientMode)» выберите значение «AuthorizationCode».

  3. После этого в разделе «Выпуск токенов» выберите необходимые для работы приложения скоупы и нажмите кнопку «Получить refresh-токен».

    Если вы впервые выпускаете токен, перед вами появится следующее сообщение.

    Нажмите кнопку «Подтвердить» и подождите 2-5 минут, чтобы изменения вступили в силу. После этого снова приступите к выпуску refresh-токена.

  4. В окне выбора учетной записи выберите ту запись, для которой хотите получить токен.

    Если вы хотите получить токен для технической учетной записи, а не для текущей, нажмите «Скопировать ссылку». Полученную ссылку откройте в браузере, в котором не проходила авторизация (или в режиме «Инкогнито»), а затем авторизуйтесь под технической учетной записью.

  5. Подтвердите доступы для работы приложения.

  6. Введите 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.

Чтобы реализовать эту схему, нужно настроить Кабинет интегратора:

  1. Перейдите в Кабинет интегратора.

  2. В разделе «Способ получения токенов (clientMode)» выберите значение «AuthorizationCode».

  3. Укажите адрес перенаправления. Если поле адреса пустое, вызов /connect/authorize вернет ошибку. Для тестирования можно указать http://localhost, а для рабочего приложения заведите отдельную страницу под адрес перенаправления.

к сведению

Примеры реализации описанного алгоритма можно посмотреть в проекте веб-приложения.

Вы можете использовать примеры, чтобы не реализовывать взаимодействие с OpenID Провайдером самостоятельно.

Чтобы получить токен доступа, выполните следующие шаги:

  1. Получите временный код подтверждения.

    Для этого перенаправьте пользователя из приложения на страницу авторизации с помощью запроса GET /connect/authorize сервиса OpenID Провайдера.

    В ответ OpenID Провайдер запросит у пользователя данные для входа и разрешения, а затем перенаправит его на указанный вами адрес и вернет в нем временный код подтверждения.

  2. Обменяйте временный код подтверждения на токен доступа access_token.

    Для этого выполните запрос POST /connect/token сервиса OpenID Провайдера.

    В ответе метод вернет токен доступа access_token, время его жизни и токен обновления refresh_token, с помощью которого можно обновить токен доступа.

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

Получение токена через Device Authorization Flow

Алгоритм подходит для приложений, в которых пользователю сложно вводить данные для аутентификации, например: desktop-приложения, консольные приложения, смарт-устройства, телевизоры. Этот способ получения токена подразумевает, что вместо своих данных пользователь может ввести в браузере некий код, полученный от приложения.

Для настройки интеграционного решения на работу с OpenID Connect нужно реализовать собственное клиентское приложение или воспользоваться готовыми сертифицированными библиотеками OpenID Connect.

к сведению

Пример реализации описанного алгоритма можно посмотреть в проекте консольного приложения.

Чтобы реализовать эту схему, нужно настроить Кабинет интегратора:

  1. Перейдите в Кабинет интегратора.

  2. В разделе «Способ получения токенов (clientMode)» выберите значение «Device».

Чтобы получить токен доступа, выполните следующие шаги:

  1. Получите временный код подтверждения.

    Для этого выполните запрос POST /connect/deviceauthorization сервиса OpenID Провайдера.

    В ответ OpenID Провайдер вернет приложению временный код подтверждения, код проверки пользователя и URI для авторизации.

  2. Перенаправьте пользователя на страницу авторизации, где он должен ввести свои данные и выдать доступ вашему приложению.

  3. Обменяйте временный код подтверждения на токен доступа access_token.

    В то время, как пользователь авторизуется, приложение должно периодически выполнять запрос POST /connect/token к сервису OpenID Провайдера до тех пор, пока не получит токен доступа или ошибку.

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

Обновление токена

Время жизни токена доступа access_token ограничено. Это значит, что по его истечении пользователю нужно будет заново проходить авторизацию, иначе методы API будут возвращать ошибки. Чтобы не повторять операцию авторизации, достаточно один раз получить от пользователя разрешения и подтверждения, получить access_token, а после — только обновлять полученный токен. Так работает «авторизация без участия пользователя».

Обратите внимание, что обновление токена нужно реализовать на стороне приложения самостоятельно: готовой настройки для этого нет.

Токен access_token нужно обновить до истечения времени его жизни. Определить время жизни можно с помощью поля expires_in, которое возвращается вместе с токеном доступа.

Чтобы обновить токен доступа, используйте один из следующих способов:

  • повторно отправьте пользователя на страницу авторизации OpenID Провайдера:
    1. Выполните шаги Получение токена через Authorization Code Flow или Получение токена через Device Authorization Flow еще раз: в параметре scope обязательно укажите offline_access, иначе токен refresh_token не вернется.
    2. Сохраните из ответа access_token и refresh_token. В поле expires_in вернется срок жизни access_token в секундах (обычно 86400 секунд).
    3. Обменяйте refresh_token на новую пару токенов до конца периода expires_in. Рекомендуем менять токены заранее — например, раз в 12 часов.
    4. Замените сохраненный refresh_token значением из ответа. При каждом обмене приходит новый токен, старый больше не понадобится.
    5. Повторяйте обмен не реже раза в 30 дней — столько действителен refresh_token.
  • выполните запрос POST /connect/token сервиса OpenID Провайдера с refresh_token, полученным вместе с access_token.
к сведению

Обратите внимание, что refresh_token вернется в ответе POST /connect/token только если при запросе GET /connect/authorize или POST /connect/deviceauthorization в параметре scope указан offline_access.

Проверка прав пользователя

Методы Диадока, которые работают с ящиком, контролируют доступ пользователя к этому ящику по следующему алгоритму:

  1. Диадок извлекает из HTTP-заголовка Authorization значение параметра access_token и с его помощью определяет идентификатор пользователя. Если какое-то действие не удалось выполнить, метод вернет код ошибки 401 (Unauthorized). Это возможно в следующих случаях:
    • в запросе отсутствует HTTP-заголовок Authorization,
    • в HTTP-заголовке Authorization не указан access_token,
    • токен поврежден или просрочен.
  2. По идентификатору пользователя Диадок находит ящики, к которым у пользователя есть доступ.
  3. Диадок извлекает из параметров запроса идентификатор ящика. Если идентификатор ящика не входит в список ящиков, доступных пользователю, метод вернет код ошибки 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-www-form-urlencoded , а не raw илиform-data .
  • Заголовок Authorization удален из запроса токена.
  • Ключ client_secret передается в теле запроса, а не в параметрах.
  • В качестве ключа client_secret используется ключ API из приложения в Кабинете интегратора.
  • Запрос отправляется к методу того алгоритма, который был выбран в приложении в Кабинете интегратора. Например, если в приложении выбран алгоритм Authorization Code Flow, а запрос отправлен на /connect/deviceauthorization , сервис вернет ошибку invalid_client .
  • Пробелы и кавычки в значениях не экранированы.

Причину ошибки, которую вернул метод Диадока, можно уточнить по заголовку ответа X-Diadoc-ErrorCode: он содержит идентификатор ошибки, например DiadocApi.Forbidden.

Оцените материал страницы

Нашли ошибку или столкнулись с проблемой?

СКБ Контурс 1988 года