JWT 검증과 JWKS: Didit Authentication 토큰

• 라이브 애플리케이션: https://<name>.auth.didit.me
• 샌드박스 애플리케이션: https://<name>.sandbox.auth.didit.me
• 또는 활성화된 후의 사용자 지정 도메인

​

디스커버리 및 키

• 응답 유형 code, 응답 모드 query.
• 권한 부여 유형 authorization_code 및 refresh_token.
• PKCE 방식은 S256만 지원합니다. 클라이언트는 공개 클라이언트입니다. 클라이언트 시크릿은 없으며, client_id는 애플리케이션 ID입니다.
• 서명 알고리즘 ES256(P-256 키).
• 스코프 openid, email, phone, profile, offline_access.

​

캐싱과 교체

• 각 키에는 kid가 있으며, 새 키 ID는 k_로 시작합니다. 모든 token은 kid 헤더에 자신의 키를 명시합니다.
• 키는 30일마다 교체됩니다. Didit은 다음 키가 서명을 시작하기 하루 전에 공개하고, 이전 키는 서명을 중단한 뒤에도 하루 동안 계속 공개합니다. 따라서 5분 동안 캐시된 JWKS는 교체 시점에도 계속 검증에 사용할 수 있습니다.
• kid로 키를 캐시하십시오. token이 명시한 kid를 보유하고 있지 않으면 JWKS를 다시 가져오되, 최대 1분에 한 번만 가져오십시오. 그래도 키가 없으면 token을 거부하십시오.
• Didit이 노출된 키를 폐기하면 JWKS에서 해당 키를 즉시 제거하며, GET /session/은 그 키가 서명한 모든 token을 거부합니다. 대체 키는 하루 전 공개 없이 즉시 서명을 시작합니다. 최대 5분 전에 캐시된 JWKS는 여전히 폐기된 키를 허용하고 대체 키는 아직 알지 못합니다. 따라서 캐시가 갱신되기 전까지 새 token이 오프라인 검증에 실패할 수 있습니다.

​

로그인 시작

{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"
}

​

액세스 토큰 클레임

​

서버에서 토큰 검증

1. alg는 ES256이고 typ는 at+jwt여야 합니다. none을 포함해 그 밖의 알고리즘은 모두 거부합니다.
2. kid가 애플리케이션의 JWKS에 있어야 하고, 서명이 검증되어야 합니다.
3. iss가 설정된 발급자와 같아야 하고, aud가 애플리케이션 ID와 같아야 합니다.
4. exp와 iat이 유효해야 합니다. 시계 차이는 최대 60초까지 허용합니다. sub, sid, jti가 있어야 합니다.
5. act는 null이어야 합니다. AI 에이전트의 액세스 토큰도 같은 키로 서명되며 같은 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"}'

• 리프레시 토큰은 무작위 문자열이며, 세션이 끝날 때까지 유효합니다.
• 재사용하면 세션이 종료됩니다. 이미 사용된 리프레시 토큰이 다시 들어오면 Didit은 이를 토큰 도용의 신호로 보고 세션을 취소하며 400 {"error": "invalid_grant"}를 반환합니다. 세션의 토큰은 모두 작동을 멈춥니다. 이전 리프레시로 받은 토큰도 포함됩니다. 이들의 리프레시 토큰은 실패하고, 액세스 토큰은 GET /session/에서 즉시 실패합니다. 다만 오프라인 검증은 만료될 때까지, 최대 5분 동안 여전히 통과합니다.
• 세션마다 한 번에 하나의 리프레시만 실행하십시오. 탭, 기기, 서버 인스턴스가 여러 개여도 마찬가지입니다. 세 가지 토큰은 함께 교체해야 합니다.
• 리프레시가 400으로 실패하거나 응답이 없으면 다시 로그인을 시작하십시오. 무조건 재시도하지 마십시오. 리프레시가 실제로 성공한 뒤의 재시도는 재사용이 됩니다.
• 503 {"error": "temporarily_unavailable"}는 리프레시가 수행되지 않았다는 뜻이며, 리프레시 토큰은 여전히 유효합니다. 백오프를 두고 재시도하십시오.
• Didit은 리프레시를 실행하기 전에 429를 반환합니다. 따라서 Retry-After만큼 기다린 뒤 재시도하십시오. 토큰 엔드포인트는 IP 주소당 분당 30회, 시간당 300회까지 허용합니다. 이에 더해, 애플리케이션의 모든 POST와 DELETE는 봇 방지 버킷을 공유합니다. 이 엔드포인트들을 합쳐 IP 주소당 분당 60회, 기기당 분당 30회입니다. 애플리케이션 전체로는 리프레시에 분당 6,000회 버킷이 있고, 그 밖의 모든 POST와 DELETE(브라우저와 로그인 단계 포함)에는 분당 3,000회 버킷이 있습니다. 따라서 리프레시가 로그인 한도를 소진하지 않습니다.
• 액세스 토큰이 5분이면, 시간당 300회의 리프레시로 활동 중인 사용자 약 25명을 감당할 수 있습니다. 서버 한 곳의 IP 주소에서 많은 사용자를 리프레시한다면, 요청에 새 토큰이 필요할 때에만 리프레시하고, 가능하면 브라우저나 앱에서 리프레시하십시오.

​

로그아웃

• session_lifetime(기본값 30일) 또는 idle_timeout(기본값 1일)을 초과한 경우,
• 여러 세션 허용이 꺼진 상태에서 사용자가 다시 로그인한 경우,
• revoke_on_password_change가 켜져 있는 상태에서 사용자가 비밀번호를 재설정한 경우,
• 귀하의 팀이 콘솔에서 세션을 취소하거나 사용자를 차단한 경우,
• 이미 사용된 리프레시 토큰이 다시 전송된 경우.

​

수명

​

목적에 따른 자격 증명 저장

• 인증 API 키와 콘솔 토큰은 서버에 보관하십시오.
• 브라우저 액세스 토큰은 가능한 한 메모리에 보관하십시오. 서버 렌더링 앱의 경우 보안 HttpOnly 쿠키를 사용하고, 쿠키로 인증된 요청은 CSRF에 대비하여 보호하십시오.
• 모바일 리프레시 토큰은 플랫폼이 보호하는 저장소에 보관하십시오. 로그아웃 후에는 로컬 상태를 삭제하십시오.
• 토큰을 URL이나 로그에 절대 포함하지 마십시오.