JWT検証とJWKS：Didit AuthenticationのJWTを検証する

• 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_で始まります。すべてのトークンはkidヘッダーで署名に使用したキーを示します。
• キーは30日ごとにローテーションされます。Diditは次のキーを署名開始の1日前に公開し、以前のキーは署名停止後も1日間公開し続けます。そのため、5分間キャッシュしたJWKSはローテーションをまたいでも検証を続けられます。
• キーはkidごとにキャッシュしてください。手元にないkidをトークンが示している場合はJWKSを再取得し(最大で1分に1回)、それでもキーが見つからなければトークンを拒否してください。
• 侵害されたキーをDiditが失効させると、そのキーは直ちにJWKSから削除され、GET /session/はそのキーで署名されたすべてのトークンを拒否します。代替キーは1日前の事前公開なしで、直ちに署名を開始します。最大5分前にキャッシュされたJWKSは失効したキーをまだ受け入れ、代替キーもまだ認識していないため、キャッシュが更新されるまで新しいトークンはオフライン検証に失敗する可能性があります。

​

サインインの開始

{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. 最大60秒の時刻のずれを許容したうえでexpとiatが有効であり、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分以内）はオフラインでは引き続き検証に成功します。
• タブ、デバイス、サーバーインスタンスをまたいで、1つのセッションにつきリフレッシュは一度に1つだけ実行し、3つのトークンはまとめて置き換えてください。
• リフレッシュが400で失敗した場合や応答がない場合は、サインインをやり直してください。やみくもに再試行しないでください。実際には成功していたリフレッシュの後に再試行すると、再利用とみなされます。
• 503 {"error": "temporarily_unavailable"}は、リフレッシュが実行されておらず、お客様のリフレッシュトークンが引き続き使用できることを意味します。バックオフを入れて再試行してください。
• Diditはリフレッシュの実行前に429を返すため、Retry-Afterの後に再試行してください。トークンエンドポイントでは、IPアドレスごとに1分あたり30リクエスト、1時間あたり300リクエストまで許可されます。さらに、お客様のアプリケーションのすべてのPOSTとDELETEはボット対策のバケットを共有します。上限は、これらのエンドポイント全体でIPアドレスごとに1分あたり60リクエスト、デバイスごとに1分あたり30リクエスト、アプリケーション全体で1分あたり1,000リクエストで、ブラウザとサインインステップも含まれます。
• アクセストークンの有効期間が5分の場合、1時間あたり300回のリフレッシュで、アクティブな状態が続く約25人に対応できます。サーバーが1つのアドレスから多数の人物のためにリフレッシュする場合は、リクエストで新しいトークンが必要なときにのみリフレッシュし、可能な場合はブラウザやアプリでリフレッシュしてください。

​

サインアウト

• session_lifetime(デフォルトは30日)またはidle_timeout(デフォルトは1日)を経過した場合
• 複数セッションが無効な状態で、ユーザーが再度サインインした場合
• revoke_on_password_changeが有効な状態で、ユーザーがパスワードをリセットした場合
• チームがコンソールでセッションを取り消すか、ユーザーをブロックした場合
• 使用済みのリフレッシュトークンが再送信された場合

​

有効期間

​

用途に応じた認証情報の保管

• 認証用のAPIキーとコンソールトークンはサーバー上に保管してください。
• ブラウザーのアクセストークンは、可能な限りメモリ上に保持してください。サーバーサイドでレンダリングされるアプリでは、Secure属性とHttpOnly属性を付けたCookieを使用し、Cookieで認証するリクエストをCSRFから保護してください。
• モバイルのリフレッシュトークンは、プラットフォームが保護するストレージに保存してください。サインアウト後はローカルの状態を消去してください。
• トークンをURLやログに含めてはいけません。