Диагностика
Типовые ошибки корпоративного входа и каталога — что видит пользователь, что отвечает API и как исправить.
Ошибки API приходят в обычном формате ApiError — {code, message, reason?}, где code — значение ErrorCode (например, ERROR_CODE_SSO_REQUIRED). Общая таблица кодов — в справочнике ошибок.
Коды ошибок идентификации
| HTTP | code / reason | Что значит | Что делать |
|---|---|---|---|
| 403 | SSO_REQUIRED | Нужно свежее подтверждение SSO: его нет, оно старше 1 часа или стало недействительным после смены подключения | «Подтвердить корпоративный вход» или войти через SSO |
| 403 | RECENT_AUTH_REQUIRED | Нужно подтвердить пароль (вход не старше 5 минут) или, для включения обязательного режима, свежий SSO | «Подтвердить пароль», затем повторить |
| 403 | IDENTITY_SCOPE_DENIED | Корпоративная сессия обращается за пределы своего пространства (ЛС, заметки, другое пространство) или действие недоступно этой роли | Войти в личный аккаунт |
| 403 | DIRECTORY_ACCESS_DENIED | Каталог закрыл доступ: учётная запись отключена, удалена, вне разрешённых групп, или синхронизации не было больше часа | Проверить учётную запись в AD и «Последнюю успешную синхронизацию» |
| 403 | RECOVERY_ONLY | Сессия восстановления пытается сделать что-то кроме ремонта политики | Сменить политику; для остального войти обычным способом |
| 403 | FORBIDDEN, «identity access denied» | IdP вернул ответ, который Calab не принял (см. ниже), или вход другой учётной записью | См. «Проверка подключения не проходит» |
| 409 | CONFLICT, reason: "PLAN_LIMIT" | У пространства нет тарифа Business/Enterprise для этой функции | Сменить тариф |
| 409 | IDENTITY_CONFIG_CHANGED | Настройки изменились, пока вы их редактировали (устаревшая version) | «Обновить» и повторить |
| 409 | IDENTITY_NOT_LINKED | Учётная запись IdP не привязана ни к одному аккаунту в этом пространстве | Войти в личный аккаунт и «Привязать корпоративный вход» |
| 409 | CONFLICT, reason: "IDENTITY_NOT_CONFIGURED" | На сервере не заданы переменные IDENTITY_* | Обратиться к оператору — см. для операторов |
| 429 | — | Слишком много попыток входа, обмена или изменений; заголовок Retry-After | Подождать |
| 503 | IDENTITY_DEPENDENCY_UNAVAILABLE | Временная недоступность базы, IdP или каталога | Повторить позже; доступ вернётся сам |
Проверка подключения не проходит
Calab не раскрывает в ответе браузеру точную причину отказа IdP — это защита от подбора. Проверьте по списку:
- Адрес возврата. В IdP зарегистрирован ровно
https://id.example.com/api/auth/sso/callback/<connection-id>, с ID текущего подключения. После смены Issuer URL или Client ID ID новый. - Issuer. Поле
issuerв<issuer>/.well-known/openid-configurationпосимвольно совпадает с «Issuer URL», включая завершающий/, если он есть. auth_time. ID token содержитauth_time. В Entra — optional claim (см. Entra). Без него сервер пишет в аудит событиеauth_time_missing.- PKCE. Если discovery перечисляет
code_challenge_methods_supported, там естьS256. Для AD FS список обязателен. - Подпись. ID token подписан
RS256. - Та же учётная запись. Проверку проходит владелец той учётной записью IdP, которую он привязал к своему аккаунту.
- Секрет. Секрет действителен и не истёк. Для Entra — Value, а не Secret ID.
- Время. Часы IdP расходятся с сервером Calab не больше чем на 60 секунд.
- Сеть. IdP доступен по публичному HTTPS, или оператор добавил все его URL в
IDENTITY_ENDPOINTS; IdP не отвечает редиректом на discovery/JWKS/token.
«Активировать» неактивна или отклоняется
- Подключение ещё не проверено или изменено после проверки — проверьте снова.
- С проверки прошло больше 5 минут — проверьте снова и сразу активируйте.
- При обязательном SSO нет действующего recovery kit — создайте его.
Нельзя включить «Обязательный SSO»
Нужны одновременно: активное проверенное подключение, привязанная учётная запись владельца, свежие (≤ 5 минут) пароль и SSO, действующий recovery kit и отметка «Recovery kit сохранён». См. режимы.
Сотрудник не может войти через SSO
| Симптом | Причина |
|---|---|
| Нет кнопки «Войти через SSO» для пространства | Нет активного проверенного подключения, пространство приостановлено или нет тарифа |
| После входа в IdP — «не привязано» | Сотрудник не выполнил «Привязать корпоративный вход» из личного аккаунта. Совпадение email не привязывает |
| Вход прошёл, но пространство закрыто | Закрыл каталог (DIRECTORY_ACCESS_DENIED) или участник забанен/удалён |
| «Вход истёк. Начните заново.» | Вход в IdP не завершён за 5 минут или билет десктопа не использован за 60 секунд |
| Гость не может войти | При обязательном SSO гостевой доступ закрыт — см. режимы |
Каталог
| Симптом | Причина |
|---|---|
| Не сохраняются настройки | Хост не в IDENTITY_DIRECTORY_HOSTS или не в разрешённых сетях; URL не ldaps://…:636; неверный DN; больше 100 групп |
| «Directory synchronization unavailable» | Нет соединения, сертификат не прошёл проверку, неверный пароль bind, снимок больше 100 000 записей или не уложился в 120 секунд |
| «Directory scan returned far fewer accounts than before…» | Карантин: снимок пустой или резко меньше прежнего. Проверьте права служебной учётной записи; если сокращение настоящее — сохраните настройки ещё раз |
| Все управляемые участники потеряли доступ | Больше часа без успешной синхронизации, или настройки только что сохранены и синхронизация ещё не прошла |
| Участник снова включён в AD, но доступа нет | Нужна успешная синхронизация, затем новый вход через SSO. Ручной бан каталог не снимает |
Где смотреть подробности
Каждое действие с подключением, политикой, каталогом и восстановлением записывается в журнал аудита сервера (например, connection_activated, policy_changed, directory_changed, recovery_session_issued). В собственной установке его просматривает оператор.