Проверка JWT и JWKS: Didit Authentication tokens

• https://<name>.auth.didit.me для продакшн-приложения,
• https://<name>.sandbox.auth.didit.me для приложения в песочнице,
• или ваш собственный домен, после его активации.

​

Discovery и ключи

• Тип ответа code и режим ответа query.
• Типы грантов authorization_code и refresh_token.
• Только метод PKCE S256. Клиенты публичные: client secret отсутствует, а client_id равен ID вашего приложения.
• Алгоритм подписи ES256 (ключи P-256).
• Области действия openid, email, phone, profile и offline_access.

​

Кеширование и ротация

• У каждого ключа есть kid; идентификаторы новых ключей начинаются с k_. Каждый token называет свой ключ в заголовке kid.
• Ключи меняются каждые 30 дней. Didit публикует следующий ключ за день до начала подписи и держит предыдущий опубликованным ещё день после того, как он перестал подписывать. Поэтому JWKS, закешированный на 5 минут, позволяет проверять токены и во время ротации.
• Кешируйте ключи по kid. Если token называет kid, которого у вас нет, заново запросите JWKS не чаще раза в минуту и отклоняйте token, если ключ всё ещё отсутствует.
• Когда Didit отзывает скомпрометированный ключ, он сразу удаляет ключ из JWKS, а GET /session/ отклоняет каждый token, подписанный этим ключом. Замещающий ключ начинает подписывать сразу, без дня предварительной публикации. JWKS, закешированный до 5 минут назад, всё ещё принимает отозванный ключ и пока не знает о замещающем, поэтому новые tokens могут не проходить офлайн-проверку, пока кеш не обновится.

​

Начало входа

{issuer}/sign-in?redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256

​

Обмен кода

curl --fail-with-body "${DIDIT_AUTH_ISSUER}/token/" \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "code": "CODE_FROM_CALLBACK",
    "code_verifier": "YOUR_PKCE_VERIFIER",
    "redirect_uri": "https://app.example.com/auth/callback"
  }'

{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "id_token": "eyJhbGciOiJFUzI1NiIs...",
  "refresh_token": "N4yZTl6y24YKYq77X_SO...",
  "token_type": "Bearer",
  "expires_in": 299,
  "session_id": "c9abf6cc-2d64-4bf2-b31e-a4d09a070ab1"
}

​

Утверждения access-токена

​

Проверка токена на вашем сервере

1. alg равен ES256, а typ равен at+jwt. Отклоняйте любой другой алгоритм, включая none.
2. kid есть в JWKS вашего приложения, а подпись успешно проверяется.
3. iss совпадает с настроенным издателем, а aud совпадает с ID вашего приложения.
4. exp и iat корректны с допуском до 60 секунд расхождения часов, а sub, sid и jti присутствуют.
5. act равен null. Access-токен ИИ-агента подписан тем же ключом и имеет те же typ, iss и aud; отличает его только act. Отклоняйте его, если только эндпоинт не принимает агентов: тогда разрешайте только то, что разрешено act.scopes. GET /session/ всегда отклоняет токен агента.

// npm install jose
import { createRemoteJWKSet, jwtVerify } from "jose";

const ISSUER = process.env.DIDIT_AUTH_ISSUER; // https://<name>.auth.didit.me
const AUDIENCE = process.env.DIDIT_APPLICATION_ID;
// Cache keys for 5 minutes; refetch an unknown kid at most once a minute.
const jwks = createRemoteJWKSet(new URL(`${ISSUER}/.well-known/jwks.json`), {
  cacheMaxAge: 5 * 60 * 1000,
  cooldownDuration: 60 * 1000,
});

export async function verifyAccessToken(token) {
  const { payload } = await jwtVerify(token, jwks, {
    issuer: ISSUER,
    audience: AUDIENCE,
    algorithms: ["ES256"],
    typ: "at+jwt",
    clockTolerance: 60,
    maxTokenAge: "5m", // also rejects an iat in the future
    requiredClaims: ["sub", "sid", "jti", "exp", "iat"],
  });
  if (payload.act !== null) throw new Error("agent tokens are not accepted");
  return payload; // payload.vendor_data is the person across Didit products
}

# pip install "pyjwt[crypto]"
import os
import threading
import time

import jwt

ISSUER = os.environ["DIDIT_AUTH_ISSUER"]  # https://<name>.auth.didit.me
AUDIENCE = os.environ["DIDIT_APPLICATION_ID"]
jwks = jwt.PyJWKClient(f"{ISSUER}/.well-known/jwks.json", lifespan=300)
refresh_lock = threading.Lock()
last_refresh = 0.0


def signing_key(kid: str | None) -> jwt.PyJWK:
    # PyJWKClient refetches for every unknown kid: limit it to once a minute.
    global last_refresh
    keys = {key.key_id: key for key in jwks.get_signing_keys()}
    if kid not in keys:
        with refresh_lock:
            if time.monotonic() - last_refresh >= 60:
                last_refresh = time.monotonic()
                fresh = jwks.get_signing_keys(refresh=True)
                keys = {key.key_id: key for key in fresh}
    if kid not in keys:
        raise jwt.InvalidTokenError("unknown signing key")
    return keys[kid]


def verify_access_token(token: str) -> dict:
    header = jwt.get_unverified_header(token)
    if header.get("typ") != "at+jwt":
        raise jwt.InvalidTokenError("not an access token")
    claims = jwt.decode(
        token,
        signing_key(header.get("kid")).key,
        algorithms=["ES256"],
        audience=AUDIENCE,
        issuer=ISSUER,
        leeway=60,
        options={"require": ["iss", "aud", "sub", "sid", "jti", "exp", "iat"]},
    )
    if "act" not in claims or claims["act"] is not None:
        raise jwt.InvalidTokenError("agent tokens are not accepted")
    return claims

​

Проверка сессии

curl --fail-with-body "${DIDIT_AUTH_ISSUER}/session/" \
  -H "Authorization: Bearer $DIDIT_ACCESS_TOKEN"

​

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

curl --fail-with-body "${DIDIT_AUTH_ISSUER}/token/" \
  -H 'Content-Type: application/json' \
  -d '{"grant_type": "refresh_token", "refresh_token": "YOUR_REFRESH_TOKEN"}'

• Refresh-токен представляет собой случайную строку, которая действительна до окончания сессии.
• Повторное использование завершает сессию. Если использованный refresh-токен приходит повторно, Didit расценивает это как признак кражи: сессия отзывается, и возвращается 400 {"error": "invalid_grant"}. Токены сессии также перестают работать, включая токены, полученные при предыдущем обновлении: их refresh-токен перестаёт работать, а access-токен сразу перестаёт проходить GET /session/. Однако офлайн он ещё проверяется до истечения срока, то есть в течение 5 минут.
• Выполняйте одно обновление за раз для сессии, во всех вкладках, на всех устройствах и на всех экземплярах сервера, и заменяйте все три токена одновременно.
• Если запрос обновления завершился ошибкой 400 или на него не пришёл ответ, начните вход заново. Не повторяйте запрос вслепую: повтор после успешного обновления и есть повторное использование.
• Ответ 503 {"error": "temporarily_unavailable"} означает, что обновление не произошло и ваш refresh-токен всё ещё работает. Повторите запрос с увеличением интервала между попытками.
• Didit возвращает 429 до выполнения обновления, поэтому повторите запрос после Retry-After. Эндпоинт токенов допускает 30 запросов в минуту и 300 в час с одного IP-адреса. Кроме того, каждый POST и DELETE вашего приложения использует общие бакеты защиты от ботов: 60 запросов в минуту с одного IP-адреса на все эти эндпоинты и 30 в минуту с одного устройства. Для всего приложения обновления имеют бакет 6 000 в минуту, а все остальные POST и DELETE (включая браузеры и шаги входа) имеют бакет 3 000 в минуту, поэтому обновления не исчерпывают лимит входов.
• При 5-минутных access-токенах 300 обновлений в час хватает примерно на 25 активных людей. Если ваш сервер обновляет токены для многих людей с одного адреса, обновляйте только тогда, когда запросу нужен новый токен, и по возможности обновляйте в браузере или приложении.

​

Выход из системы

• она превышает session_lifetime (по умолчанию 30 дней) или idle_timeout (по умолчанию 1 день),
• пользователь входит снова, а несколько сессий отключены,
• пользователь меняет пароль, а revoke_on_password_change включён,
• ваша команда отзывает сессию или блокирует пользователя в консоли,
• использованный refresh token отправляется повторно.

​

Сроки действия

​

Хранение учётных данных по назначению

• Храните API-ключи для верификации и tokens консоли на своём сервере.
• По возможности храните access tokens браузера в памяти. В приложениях с серверным рендерингом используйте cookie с флагами Secure и HttpOnly и защищайте запросы с аутентификацией через cookie от CSRF.
• Храните refresh tokens мобильных приложений в защищённом хранилище платформы. После выхода очищайте локальное состояние.
• Никогда не помещайте tokens в URL или журналы.