Способы входа: passkeys, коды, соцсети, SSO

Включите метод через PUT methods/{name}/ с телом {"enabled": true} в API управления аутентификацией вашего приложения или в консоли. Размещённая страница входа показывает только включённые вами методы. Каждый JSON-вызов ниже начинается с transaction, полученного из POST authorize/. Транзакция действует 10 минут. Успешный вход возвращает {code, redirect_uri, state}. Обменяйте код через POST token/ в течение 60 секунд (см. токены и JWKS). Вместо кода вызов входа может вернуть один из следующих шагов. Выполните шаг, после чего вы получите код.

​

Пароль

POST password/ принимает transaction, email и password.

• Пароль должен соответствовать вашему password_min_length (8, 10, 12 или 14 символов; по умолчанию 10). Распространённые пароли и пароли только из цифр отклоняются с ошибкой password_policy. Если включена проверка на утёкшие пароли, известный утёкший пароль отклоняется с ошибкой password_breached.
• Войти с паролем могут только пользователи с подтверждённой электронной почтой.
• Неверный пароль, неизвестный адрес электронной почты, неподтверждённая почта, учётная запись, доступ к которой заблокирован, и заблокированная учётная запись получают одинаковый ответ: 400 {"error": "invalid_credentials"}. Ваш интерфейс не может определить, какой именно случай произошёл, и злоумышленник тоже не может.

​

Регистрация

Сначала при регистрации подтверждается адрес электронной почты. Вызовите POST email/start/ с purpose: "signup", email и password, затем POST email/complete/ с кодом. Аккаунт создаётся с подтверждённой электронной почтой.

• signup_policy определяет, кто может зарегистрироваться: anyone, invited (только по ссылке-приглашению) или allowed_domains.
• При allow_subaddresses: false (значение по умолчанию) адрес с + в локальной части отклоняется.
• Если в брендинге заданы ссылки на условия или политику конфиденциальности, размещённая форма регистрации просит пользователя их принять.

​

Код по электронной почте

POST email/start/ принимает transaction, purpose (login или signup) и email и возвращает 202 {challenge, expires_in: 600}. Пользователь получает 6-значный код, который действует 10 минут. POST email/complete/ принимает transaction, purpose, challenge и code. Есть 5 попыток, после чего пользователь должен запросить новый код. Размещённая страница предлагает новый код через 30 секунд. Код входа для адреса без аккаунта создаёт аккаунт, если это разрешено signup_policy. Это регистрация без пароля.

​

Магическая ссылка

Размещённая страница отправляет ссылку для входа, которая действует 15 минут. Она остаётся привязанной к исходной транзакции PKCE, поэтому ссылка работает только в том потоке, который её запустил. Пользователь подтверждает вход на странице, которую открывает ссылка. JSON-эндпоинта для магических ссылок нет.

​

Код по телефону

POST phone/start/ принимает transaction, phone и необязательный channel (sms, по умолчанию, или whatsapp). Номер приводится к формату E.164. Возвращается 202 {challenge, expires_in: 600}. POST phone/complete/ принимает transaction, challenge и 6-значный code. Есть 5 попыток.

• Коды по телефону доставляются через проверку телефона Didit. Включите метод, указав workflow_id сценария, который содержит проверку телефона.
• Первый вход по телефону создаёт аккаунт, только если signup_policy равен anyone.
• Если доставка не удалась, вызов возвращает 503 {"error": "delivery_unavailable"}.

​

Passkeys

Passkey работают через WebAuthn. Доверяющей стороной (relying party) является источник входа вашего приложения. Didit запрашивает обнаруживаемые учётные данные (resident key) и всегда требует верификацию пользователя, например отпечаток пальца, лицо или PIN-код устройства. Didit не запрашивает аттестацию.

• Challenge для passkey действует 5 минут.
• Для добавления passkey нужна сессия, созданная не более 5 минут назад. Иначе вызов возвращает 403 {"error": "reauthentication_required"}. Сначала повторно войдите в аккаунт.
• Вход с passkey считается многофакторным.
• После регистрации размещённая страница предлагает добавить passkey (passkeys/setup/begin/ и passkeys/setup/complete/).
• Android-приложения, зарегистрированные в приложении, могут использовать те же ключи доступа.

​

Вход через социальные сети

Вход через Google, Microsoft, Apple и GitHub использует ваши собственные учетные данные OAuth-приложения, которые задаются через PUT methods/{provider}/ и credentials: {client_id, client_secret}. URL обратного вызова провайдера находится на origin, используемом для входа. При первом входе через провайдера пользователь также подтверждает владение адресом электронной почты с помощью кода (POST social/email/start/ и POST social/email/verify/). При последующих входах через этого провайдера этот шаг пропускается. GitHub не может подтвердить недавний вход, поэтому он не предлагается, если вы передаете prompt=login или max_age.

​

SSO для организаций

SSO для организаций позволяет компании клиента входить через собственного провайдера удостоверений SAML или OIDC. Настраивайте его для каждой организации клиента по адресу organizations/{id}/sso/ с параметрами protocol (saml или oidc), enabled и config.

• Вы можете отправить IT-команде клиента ссылку для настройки, которая действительна 7 дней.
• Метаданные вашего поставщика услуг SAML публикуются по адресу {origin}/sso/saml/metadata/.
• Размещенная страница входа находит подключение по верифицированному домену электронной почты пользователя или по organization=<slug> в URL входа.

​

Didit ID Wallet

Люди, которые уже прошли верификацию в Didit, могут войти с помощью своего Didit ID Wallet. Этот способ всегда включен. Поле verified_identity в сессии затем содержит данные, которыми человек решил поделиться.

​

MFA

Вторым фактором выступает приложение-аутентификатор (TOTP) с кодами восстановления или ключ доступа.

• mfa_policy определяет, кто обязан использовать MFA: optional, everyone или organization_admins (по умолчанию). Тот, кто подключил аутентификатор, всегда обязан его использовать.
• Чтобы подключить аутентификатор, вызовите POST mfa/enroll/ с актуальной сессией (созданной не более 5 минут назад). Метод возвращает {challenge, uri}; отобразите uri как QR-код. Затем отправьте первый код в POST mfa/confirm/. Ответ содержит 10 одноразовых кодов восстановления. Показывайте их один раз.
• При входе отправьте TOTP-код или код восстановления в POST mfa/complete/ вместе с challenge. Вам доступно 5 попыток. Чтобы вместо этого использовать ключ доступа, вызовите POST mfa/passkey/begin/ и POST mfa/passkey/complete/.
• Коды меняются с шагом 30 секунд. Код, который уже был принят, нельзя использовать повторно.
• SMS-коды и коды по электронной почте не доступны в качестве второго фактора.

​

Забытый пароль и сброс пароля

POST password-reset/start/ принимает email и возвращает 202 {"status": "sent", "expires_in": 1800}. Ответ одинаковый независимо от того, существует ли учетная запись для этого адреса. Ссылка для сброса действительна 30 минут. POST password-reset/complete/ принимает token и password и возвращает {"status": "password_changed"}. Также метод:

• снимает блокировку,
• завершает все сессии, если включена опция revoke_on_password_change (по умолчанию),
• аннулирует другие ожидающие коды и ссылки этого пользователя.

​

Приглашения

При signup_policy: "invited" регистрироваться могут только приглашенные пользователи. Ссылка-приглашение действительна 7 дней и открывает размещенную страницу /invite. Перейдите к токенам и JWKS или прочитайте о защите от ботов, чтобы узнать о блокировках и проверочных испытаниях.