Эта инструкция предназначена для IT-специалистов и администраторов, которые настраивают единый вход в CheckOffice через AD FS. В ней описаны действия на стороне AD FS и параметры, которые затем необходимо указать в CheckOffice.

Общая информация о SSO-аутентификации, настройке входа и авторизации пользователей доступна в статье: «SSO-аутентификация».

Протокол: OpenID Connect, authorization code

Требуется: AD FS на Windows Server 2016 или новее

Кратко

Протокол: OpenID Connect, authorization code, confidential client. PKCE не используется. 

Приложение: Группа приложений, шаблон «Серверное приложение, подключающееся к веб-API». У приложения сервера и веб-API общий идентификатор.

Redirect URI: 

https://<domain>.checkoffice.ru/webapi/sso/callback

https://<domain>.checkoffice.ru/api/v5/sso/callback

Scopes: openid, email

Сlaim: Правило преобразования выдачи на веб-API: LDAP E-Mail-Addresses > «Адрес электронной почты». Приходит в access-токене. 

Сопоставление: Строго по адресу почты. Учетная запись должна существовать в CheckOffice, автосоздания нет. 

Политика доступа: Любая из списка, включая варианты с требованием MFA — второй фактор обеспечивает AD FS. 

Настройки CheckOffice: Адрес сервера https://<adfs-host>/adfs — обязательно с путем /adfs; Client ID; Client Secret.

Что нужно до начала

Версия AD FS: Windows Server 2016 или новее. В AD FS на 2012 R2 нет OpenID Connect — только WS‑Federation и SAML, которые CheckOffice не поддерживает. 

Доступность: AD FS открыт по HTTPS для браузеров пользователей и для серверов CheckOffice: сервис сам обращается к нему за настройками и за проверкой токена. 

Учетные записи: Пользователи уже заведены в CheckOffice, и адрес почты в карточке совпадает с почтой в Active Directory. При входе учетные записи не создаются. 

Права: Роль «Администратор» в CheckOffice и права на создание группы приложений в консоли «Управление AD FS».

Порядок настройки

Шаги 1–3 выполняются в AD FS, шаг 4 — в CheckOffice. 

1. Подготовить адрес возврата

AD FS возвращает пользователя в CheckOffice только на заранее зарегистрированный адрес, сверяя его посимвольно. Подставьте адрес вашего портала CheckOffice вместо <domain>.checkoffice.ru:

Вход из браузера: https://<domain>.checkoffice.ru/webapi/sso/callback

Вход из мобильного приложения: https://<domain>.checkoffice.ru/api/v5/sso/callback

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

2. Создать группу приложений в AD FS

Консоль Управление AD FS > в дереве слева Группы приложений > в панели справа «Добавить группу приложений…». Задайте имя и выберите шаблон «Серверное приложение, подключающееся к веб-API» в разделе «Клиент-серверные приложения». CheckOffice работает с секретом, поэтому шаблон «Веб-браузер, подключающийся к веб-приложению» не подойдет: он секрета не выдает.

Имя группы задано, шаблон — второй пункт в разделе «Клиент-серверные приложения»

На шаге «Приложение сервера» скопируйте Идентификатор клиента — это Client ID для CheckOffice. Там же добавьте оба адреса возврата: введите адрес в поле «Перенаправить URI:» и нажмите «Добавить», затем так же второй.

Оба адреса уже в списке. Добавляются по одному: поле > кнопка «Добавить»

Дальше — «Настроить учетные данные приложения»: отметьте «Создать общий секрет» и скопируйте значение. Второй раз AD FS его не покажет.

Секрет виден один раз — скопируйте сразу

На шаге «Настройка веб-интерфейса API» в поле «Идентификатор» вставьте тот же идентификатор клиента и нажмите «Добавить».

Идентификатор веб-API совпадает с идентификатором клиента и добавлен в список

Политика управления доступом — «Разрешение для каждого.», если второй фактор не нужен. Варианты с требованием MFA — в этом же списке, их можно выбрать и позже.

Выбрана «Разрешение для каждого.»

Разрешения приложения: отметьте области openid и email.

Отмечены области openid и email, остальные не нужны

На сводке сверьте адреса возврата и идентификаторы, затем «Далее» и «Закрыть».

Сводка перед созданием: адреса возврата, идентификаторы, политика, области 

Совместимость: СheckOffice не использует PKCE, поэтому настройка одинаково работает на AD FS 2016 и на более новых версиях. 

3. Выдать почту пользователя в токене

CheckOffice сопоставляет пользователя по адресу почты, поэтому AD FS должен отдавать этот адрес в claim email. По умолчанию он этого не делает — нужно правило.

Двойной клик по созданной группе приложений > в списке «Приложения» двойной клик по веб-API > вкладка «Правила преобразования выдачи» > «Добавить правило…».

Вкладка «Правила преобразования выдачи»в свойствах веб-API — пока пусто

В мастере выберите шаблон «Отправка атрибутов LDAP как утверждений».

Шаблон правила — «Отправка атрибутов LDAP как утверждений»

Задайте имя правила, хранилище атрибутов — Active Directory, и одну строку сопоставления: тип исходящего утверждения выберите из выпадающего списка.

Правило заполнено: хранилище Active Directory, строка E-Mail-Addresses > «Адрес электронной почты»

Атрибут LDAP: E-Mail-Addresses

Тип исходящего утверждения: Адрес электронной почты

⚠️ Обратите внимание

Имя claim — ровно email, без дефиса и без других написаний. Значение должно совпадать с почтой пользователя в CheckOffice; поля upn и sub не используются.

4. Включить SSO в CheckOffice

Раздел «Администрирование» > включить «Включить возможность аутентификации через OIDC» и заполнить три поля:

Адрес сервера: https://<adfs-host>/adfs

Client ID: Идентификатор клиента из шага 2

Client Secret: Секрет из шага 2

⚠️ Обратите внимание

Адрес сервера указывайте вместе с путем /adfs. CheckOffice дописывает к нему /.well-known/openid-configuration и забирает настройки автоматически. Если оставить только https://<adfs-host>, запрос уйдет в корень сайта, настроек там нет и проверка подключения не пройдет.

Сохраните и выполните проверку подключения — она подтверждает, что CheckOffice видит AD FS и получает от него настройки.

Подробнее о входе через SSO в веб-интерфейсе и мобильном приложении, а также о возможных причинах ошибки авторизации: «SSO-аутентификация».

Обратите внимание: в этой статье описана только настройка SSO-авторизации. Вопросы, связанные с документами, файлами и доступом к другим разделам CheckOffice, рассматриваются отдельно.