> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Интеграция аутентификации: архитектура и запуск в продакшн

> Архитектура интеграции Didit Authentication: экраны, хранение token, проверка на бэкенде, сессии, нативные приложения и запуск в продакшн.

Это руководство объясняет, как устроена продакшн-интеграция Didit Authentication: от первого перенаправления до контрольного списка перед запуском.
Если вы ещё не выполняли вход для пользователя, начните с [быстрого старта](https://docs.didit.me/ru/authentication/quickstart.md), а код для каждого SDK берите из быстрых стартов для платформ.

## Архитектура

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

В процессе участвуют четыре части:

| Часть | Отвечает за |
| - | - |
| Ваше приложение | Запуск входа, хранение PKCE-верификатора и `state`, хранение токенов и отправка токена доступа на ваш бэкенд. Всё это делают SDK. |
| Ваш источник входа | `https://<slug>.auth.didit.me` (или ваш [собственный домен](https://docs.didit.me/ru/authentication/branding-and-custom-domain.md#собственный-домен)): размещённые страницы, эндпоинт токенов, сессия, discovery и ключи подписи. |
| Ваш бэкенд | Проверка токена доступа при каждом защищённом запросе, проверка сессии перед чувствительными действиями и решение о том, что пользователь может делать. |
| Консоль Didit и webhook | Настройка, пользователи и их сессии, события входа и webhook `auth.*`, на которые подписывается ваш сервер. |

API-ключ Didit и секрет не должны попадать в ваше приложение ни в каком виде: публикуемый ключ доступен публично, а обмен кода авторизации защищён PKCE вместо клиентского секрета.

## Размещённые страницы или собственные экраны

Выберите, где пользователи будут вводить email, пароль или код.
Настройка называется `sign_in_ui` (по умолчанию `hosted`, либо `own`), и её можно изменить позже.

| | Размещённые страницы (рекомендуется) | Собственные экраны |
| - | - | - |
| Что вы создаёте | Кнопку входа и страницу обратного вызова. | Все экраны и все промежуточные шаги. |
| Методы | Все, включая магические ссылки, корпоративный SSO и ключи доступа. | Пароль, код из email, код телефона, MFA и проверки защиты через методы SDK без пользовательского интерфейса. Магические ссылки работают только на размещённых страницах. |
| Следующие шаги | Обрабатываются за вас: MFA, регистрация MFA, проверки защиты и верификация при регистрации. | Ваши экраны обрабатывают `mfa_required`, `mfa_enrollment_required`, `protection_required` и `verification_required`. См. [методы входа](https://docs.didit.me/ru/authentication/sign-in-methods.md). |
| Бренд | Ваш логотип, цвета и тексты из [брендинга](https://docs.didit.me/ru/authentication/branding-and-custom-domain.md). | Полностью ваш. |
| Настройка | URL перенаправления. | URL перенаправления и origin вашего веб-приложения в разделе **Allowed origins**. |

Ключи доступа привязаны к источнику входа вашего приложения.
Методы SDK для ключей доступа работают только на страницах, открытых с этого origin, поэтому на ваших собственных экранах на другом домене направляйте пользователей на размещённую страницу для ключей доступа.

## Выбор SDK

| Ваше приложение | Пакет | Где хранятся токены |
| - | - | - |
| Одностраничное веб-приложение | [`@didit-protocol/auth`](https://docs.didit.me/ru/authentication/quickstarts/javascript) или [`@didit-protocol/auth-react`](https://docs.didit.me/ru/authentication/quickstarts/react) | Веб-хранилище или память в браузере. Используйте строгую политику безопасности контента (CSP). |
| Веб-приложение с серверным рендерингом | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/ru/authentication/quickstarts/nextjs) | HttpOnly-cookie, которые устанавливает ваш сервер. Страница никогда не видит токены. |
| iOS | [`DiditAuth`](https://docs.didit.me/ru/authentication/quickstarts/ios) | Keychain. |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/ru/authentication/quickstarts/android) | Хранилище, защищённое Android Keystore. |
| React Native или Flutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/ru/authentication/quickstarts/react-native) или [`didit_auth`](https://docs.didit.me/ru/authentication/quickstarts/flutter) | Защищённое хранилище платформы через нативные модули. |
| Любой бэкенд | [Серверные SDK](https://docs.didit.me/ru/integration/server-sdks/overview.md), `verifyToken` из `@didit-protocol/auth/server`, или любая библиотека для JWT | Хранить ничего не нужно: сервер проверяет полученный токен. |

Если SDK не используется, реализуйте поток авторизации с кодом и PKCE самостоятельно: в [быстром старте для JavaScript](https://docs.didit.me/ru/authentication/quickstarts/javascript.md#без-sdk) показан весь контракт.

## Защита вашего бэкенда

Проверка сессии на фронтенде управляет только тем, что вы показываете. Ваш бэкенд принимает все решения и опирается на проверенный токен.

1. **Проверяйте токен доступа при каждом запросе.** Проверьте подпись ES256 по JWKS вашего издателя, затем `iss`, `aud`, `exp` и `typ: at+jwt`, и отклоняйте токен, у которого `act` не равен `null`, если только маршрут не принимает [ИИ-агентов](https://docs.didit.me/ru/authentication/agent-access.md). См. [проверка токена на вашем сервере](https://docs.didit.me/ru/authentication/tokens-and-jwks.md#проверка-токена-на-вашем-сервере).
2. **Проверяйте действующую сессию перед чувствительным действием.** Токен доступа остаётся действительным до истечения срока, но не дольше 5 минут. `GET /session/` сразу возвращает ошибку, если сессия отозвана, простаивала или истекла, если пользователь заблокирован или если сессия больше не соответствует вашей политике MFA. См. [проверка сессии](https://docs.didit.me/ru/authentication/tokens-and-jwks.md#проверка-сессии).
3. **Запрашивайте step-up, когда действие рискованное.** Перед выплатой, добавлением нового банковского счёта или изменением адреса электронной почты или номера телефона спросите у Didit, нужно ли пользователю пройти верификацию повторно, и действуйте только по step-up со статусом `approved`, который ваш бэкенд получил сам. См. [step-up перед чувствительными действиями](https://docs.didit.me/ru/authentication/verified-identity.md#step-up-перед-чувствительными-действиями).
4. **Берите `vendor_data` из проверенного токена**, никогда из поля, которое отправил браузер, и используйте его для верификаций и транзакций пользователя.

## Sessions

| Событие | Что происходит |
| - | - |
| Вход | Начинается сессия. Её длительность задаётся параметром `session_lifetime` (по умолчанию 30 дней), но она завершается раньше, если в течение `idle_timeout` нет активности (по умолчанию 1 день). |
| Каждые несколько минут | SDK обновляет access token, который действует не более 5 минут. Refresh token ротируется: каждый из них работает только один раз. |
| Повторно отправлен уже использованный refresh token | Didit расценивает это как кражу и завершает сессию. Выполняйте только одно обновление одновременно для каждой сессии. |
| Вход с другого устройства | При `multiple_sessions: false` остальные сессии пользователя завершаются. |
| Сброс пароля | Все сессии завершаются, если включён `revoke_on_password_change` (по умолчанию включён). |
| Выход из системы | `DELETE /session/` завершает сессию, и ваше приложение перенаправляет пользователя на `post_logout_redirect_uri`. |
| Действия вашей команды | В консоли можно отозвать одну сессию, выйти из всех сессий пользователя или заблокировать его. См. [руководство по консоли](https://docs.didit.me/ru/authentication/console.md#входы-и-сессии). |

Значения длительности сессии и тайм-аута бездействия можно изменить в разделе **Authentication > Security and sessions** или через API в [настройках приложения](https://docs.didit.me/ru/authentication/overview.md#настройки-приложения).

![Представление Active sessions в Didit Business Console: список активных сессий с устройством, местоположением, временем начала, последней активностью, временем окончания и кнопкой Revoke](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessions, с кнопкой Revoke в каждой сессии.

## Нативные приложения

Didit возвращает пользователей в нативное приложение только через HTTPS-перенаправление: пользовательские URL-схемы не поддерживаются.

* **iOS:** настройте перенаправление как связанный домен, добавив `webcredentials` в ваш `apple-app-site-association`.
* **Android:** настройте перенаправление как App Link с помощью вашего `assetlinks.json`.
* Зарегистрируйте каждый URL перенаправления в разделе **Authentication > Security and sessions**, как и веб-callback.

Чтобы использовать ключи доступа в вашем приложении, зарегистрируйте приложения, которые используют общие ключи доступа вашего приложения, с помощью `PUT native-apps/` в [API управления аутентификацией](https://docs.didit.me/ru/authentication/set-up-by-api.md).
Затем Didit добавит их в `apple-app-site-association` и `assetlinks.json`, которые он размещает на источнике входа вашего приложения.
`MANAGEMENT_BASE` указывает адрес API управления вашим приложением, а запрос можно выполнить с помощью API-ключа с областью `authentication` и уровнем доступа **write**.
Вызов заменяет оба списка, поэтому отправляйте оба:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| Поле | Правило |
| - | - |
| `ios_app_ids` | До 10 записей, каждая из которых содержит ваш Team ID и идентификатор пакета, например `ABCDE12345.com.example.app`. |
| `android_apps` | До 10 приложений, каждое с `package_name` и от 1 до 5 отпечатков SHA-256 сертификатов подписи. |

Быстрые старты для [iOS](https://docs.didit.me/ru/authentication/quickstarts/ios.md) и [Android](https://docs.didit.me/ru/authentication/quickstarts/android.md) показывают настройку на стороне приложения.

## Подключение верификации личности и мониторинга транзакций

У каждого человека есть одно значение `vendor_data` в его токенах и сессии.
Используйте его как `vendor_data`, когда [создаёте сессию верификации](https://docs.didit.me/ru/sessions-api/create-session.md) или [отправляете транзакцию](https://docs.didit.me/ru/transaction-monitoring/transactions.md), и консоль показывает входы в систему, верификации и транзакции одного и того же человека.

* Чтобы проверять людей при регистрации или повторно перед выплатой без создания собственного процесса верификации, используйте [верификацию личности](https://docs.didit.me/ru/authentication/verified-identity.md).
* События входа автоматически попадают в [правила событий](https://docs.didit.me/ru/transaction-monitoring/event-rules.md) и разделы по мошенничеству. Не отправляйте собственные события `auth.login` для тех же входов.
* Успешный вход никогда не одобряет верификацию или транзакцию: решение по каждому продукту принимайте отдельно.

См. [как сохранить одного и того же человека во всех продуктах](https://docs.didit.me/ru/authentication/overview.md#сохраняйте-одного-человека-между-продуктами).

## Получение событий входа

Подпишите [адрес назначения webhook](https://docs.didit.me/ru/integration/webhooks.md) на типы `auth.*`, которые вам нужны, например `auth.new_device` или `auth.account_locked`.
Дедуплицируйте события по `auth_event.event_id` и проверяйте подпись так же, как для любого webhook от Didit.
Все типы и их payload описаны в разделе [события и webhook](https://docs.didit.me/ru/authentication/events-and-webhooks.md).

## Перенос существующих пользователей

Если ваши пользователи уже имеют учётные записи на другой платформе идентификации или в вашей базе данных, [импортируйте их](https://docs.didit.me/ru/authentication/migration.md) до переключения входа.
Импортируйте хеши паролей, если исходная система их предоставляет, сохраняйте привязки к социальным сетям и сохраняйте собственные идентификаторы пользователей как `external_id`, который становится их `vendor_data`.
Для пользователей ничего не меняется, пока вы не переключите приложение на Didit.

## Чек-лист перед запуском в продакшн

1. Аутентификация включена для вашего Live-приложения на странице **Products**.
2. Ваши продакшн-URL перенаправления `https://` и разрешённые origin зарегистрированы в Live-приложении. Live-приложение не принимает адреса `http://`.
3. Каждый метод входа через социальные сети использует идентификатор клиента и секрет вашего собственного приложения: тестовые учётные данные Didit работают только в песочнице.
4. В вашей продакшн-конфигурации указаны публикуемый ключ Live (`pk_live_`) и ваш издатель для Live.
5. Политика MFA, время жизни сессии, тайм-аут бездействия, длина пароля и политика регистрации соответствуют вашим требованиям. См. [настройки приложения](https://docs.didit.me/ru/authentication/overview.md#настройки-приложения).
6. [Защита от ботов](https://docs.didit.me/ru/authentication/bot-protection.md) включена, вместе с проверкой скомпрометированных паролей.
7. Ваш бэкенд проверяет каждый токен доступа и вызывает `GET /session/` перед чувствительными действиями.
8. Брендинг, тексты страниц и ссылки на условия использования и политику конфиденциальности настроены. Если вы планируете [пользовательский домен](https://docs.didit.me/ru/authentication/branding-and-custom-domain.md#собственный-домен), активируйте его до того, как пользователи начнут добавлять ключи доступа.
9. Для адреса назначения webhook настроена подписка на типы `auth.*`, которые вы обрабатываете.
10. Вы протестировали на Live-приложении регистрацию, повторный вход, отмену, восстановление пароля, MFA, истечение сессии, выход и отозванную сессию.

## Устранение неполадок

| Симптом | Причина и решение |
| - | - |
| Каждый маршрут среды выполнения отвечает `404` | Аутентификация отключена для приложения, или адрес одновременно использует origin песочницы и origin продакшн-среды. Включите её на странице **Products** и используйте origin, который указан в вашем публикуемом ключе. |
| Страница входа отвечает `400` и просит зарегистрировать адрес, или `POST /authorize/` отвечает `invalid_redirect_uri` | `redirect_uri` зарегистрирован неточно: схема, хост, порт, путь и строка запроса должны совпадать посимвольно. См. [URL перенаправления](https://docs.didit.me/ru/authentication/overview.md#url-перенаправления). |
| Браузерный вызов к вашему origin для входа отвечает `403` с `origin_not_allowed` | Ваш веб-origin не добавлен в **Allowed origins**. Добавьте его без пути и без завершающего слеша. |
| `POST /token/` отвечает `invalid_grant` | Код уже использован, старше 60 секунд или отправлен с другим верификатором PKCE или `redirect_uri`. При обновлении токена уже использован токен обновления, что завершает сессию. Начните вход заново. |
| Вход по паролю отвечает `invalid_credentials` при верном пароле | Email не подтверждён, или аккаунт заблокирован или заблокирован системой безопасности. Didit намеренно даёт тот же ответ. Проверьте пользователя в **Users**. |
| `GET /session/` отвечает `401` | Сессия отозвана, стала неактивной или истекла, пользователь заблокирован, токен заменён при обновлении, или сессия больше не соответствует вашей политике MFA. Обновите токен или войдите пользователя заново. |
| Добавление ключа доступа или аутентификатора отвечает `403 reauthentication_required` | Для этого нужна сессия, созданная не более 5 минут назад. Сначала войдите пользователя заново. |
| Код по телефону отвечает `503 delivery_unavailable` | Код не удалось доставить. Дайте пользователю повторить попытку или предложите другой способ. |
| Вызов отвечает `429` | Вы превысили лимит запросов. Повторите запрос после времени, указанного в `Retry-After`. См. [лимиты запросов](https://docs.didit.me/ru/authentication/bot-protection.md#ограничения-частоты-запросов). |
| Вызов настройки с API-ключом отвечает `409 product_disabled` | Аутентификация отключена для приложения. Её включает пользователь в консоли. |
| Вызов отвечает `403 plan_required` | Функция, например пользовательские роли или ссылки на настройку SSO компании, требует тариф Scale или Enterprise. В приложениях в песочнице эта функция доступна на любом тарифе. |
| Токены не проходят проверку после активации пользовательского домена | Изменились издатель и публикуемый ключ. Скопируйте новый ключ в приложение и обновите издателя, которого проверяет ваш бэкенд. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.