Email Code

Email Codeは、ユーザーのメールアドレスに短時間だけ有効な確認コードを送信する認証方式です。現在のブラウザ向けフローは Direct Auth と Web SDK を中心に実装されています。

概要

sequenceDiagram
    participant User as ユーザー
    participant App as アプリ
    participant Authrim
    participant Email as Email Notifier

    User->>App: メールアドレスを入力
    App->>Authrim: PKCE challenge付きでコード送信を依頼
    Authrim->>Email: 確認コードを送信
    Email->>User: コードを配信
    User->>App: コードを入力
    App->>Authrim: PKCE verifier付きでコードを検証
    Authrim->>App: Direct Auth artifactを返却
    App->>Authrim: artifactをトークン/セッションに交換

特徴

• パスワードレス: パスワードの記憶や保存が不要
• Direct Auth対応: ブラウザクライアントがホスト型リダイレクトなしで認証可能
• PKCEバインド: 送信と検証がS256 challengeで結び付けられる
• 単一使用コード: 検証に成功するとサーバー側challengeを消費
• ユーザー作成対応: 検証済みメールアドレスから新しいエンドユーザーを作成可能
• 招待対応: invite_tokenで招待先テナントや割り当てにルーティング可能

設定

Email Code の配信には、notifier.email capability を持つ notifier plugin を使用します。Cloudflare Email や Resend などの組み込み email notifier、またはカスタム notifier plugin を設定してください。

# email notifier plugin が使用する送信元メタデータ
EMAIL_FROM=noreply@example.com
EMAIL_FROM_NAME=Authrim

# メールコードのハッシュ化に使う任意のHMAC secret
OTP_HMAC_SECRET=replace-with-random-secret

現在の Direct Auth 実装では、6桁コード、5分TTLを使用します。送信リクエストはテナントとメールアドレス単位で、検証リクエストはコード試行単位でレート制限されます。

API使用方法

Step 1: Email Codeを送信

POST /api/v1/auth/direct/email-code/send
Content-Type: application/json

{
  "client_id": "your-client-id",
  "email": "user@example.com",
  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "code_challenge_method": "S256",
  "channel": "browser",
  "scope": "openid profile email",
  "locale": "ja"
}

任意フィールドとして、招待サインアップ用のinvite_tokenや登録フィールド用のcustom_fieldsを指定できます。

レスポンス:

{
  "attempt_id": "7d6ad739-0d19-4e90-b352-8e8b6d7d81ac",
  "expires_in": 300,
  "masked_email": "u***r@example.com"
}

Step 2: Email Codeを検証

POST /api/v1/auth/direct/email-code/verify
Content-Type: application/json

{
  "attempt_id": "7d6ad739-0d19-4e90-b352-8e8b6d7d81ac",
  "code": "123456",
  "code_verifier": "original-pkce-code-verifier",
  "channel": "browser"
}

レスポンス:

{
  "direct_auth_artifact": "daa_...",
  "expires_in": 300,
  "is_new_user": false
}

Direct Auth artifact は中間資格情報です。Web SDK はこの artifact を Direct Auth token exchange に渡し、標準の session、user、token payload を返します。

レガシーEmail Codeエンドポイント

Authrim はホスト型UIやレガシー統合向けに、/api/auth/email-codes/send と /api/auth/email-codes/verify も公開しています。新しいブラウザアプリでは Direct Auth エンドポイントまたは Web SDK を推奨します。

Web SDK使用例

import { createAuthrim } from '@authrim/web';

const authrim = createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'your-client-id',
});

const sendResult = await authrim.emailCode.send('user@example.com', {
  locale: 'ja',
});

if (sendResult.ok) {
  console.log(sendResult.data.maskedEmail);
}

const verifyResult = await authrim.emailCode.verify('user@example.com', '123456');

if (verifyResult.ok) {
  console.log(verifyResult.data.session);
}

SDK は保留中のattemptIdとPKCE verifierをメモリ上に保持し、hasPendingVerification()、getRemainingTime()を提供します。成功または期限切れ時には保留状態をクリアします。

セキュリティ考慮事項

コードの取り扱い

• コードはサーバー側で生成され、APIレスポンスには含まれません。
• コード検証では、テナント、メール、attempt の文脈を含むHMACベースのハッシュを使用します。
• challenge state はサーバー側に保存され、検証時に消費されます。
• メールアドレスは検証前に検索・ルーティング用に正規化されます。

レート制限

制限	現在の挙動
送信リクエスト	テナント/メールアドレスごとに15分あたり3回
検証試行	コードTTL内でattemptごとに5回
コードTTL	5分
コード形式	6桁の数字

悪用防止

• Direct Auth の送信ではcode_challenge_method: "S256"が必須です。
• 検証リクエストでは対応するcode_verifierが必須です。
• 検証時のchannelは送信時のchannelと一致する必要があります。
• 本番環境で有効化する前に、実際に送信できる email notifier を設定してください。
• フォールバック値に頼らず、高エントロピーなOTP_HMAC_SECRETを設定してください。

メールテンプレート

組み込み Direct Auth メールは、設定済みの email notifier と送信元メタデータを使います。本番向けのブランディングが必要な場合は、カスタム email notifier plugin を提供するか、アクティブな notifier で任意のテンプレートをレンダリングしてください。

他の方式との比較

方式	セキュリティ	使いやすさ	必要なもの
Email Code	高	高	メールアクセス
パスワード	中	中	パスワード保存とリセットUX
TOTP	高	中	認証アプリ
Passkey	非常に高	高	対応デバイス
SMS OTP	中	高	電話番号

トラブルシューティング

コードが届かない:

• email notifier plugin がインストールされ、有効化されているか確認
• EMAIL_FROMとプロバイダー固有設定を確認
• プロバイダーの配信ログと迷惑メールフォルダを確認
• レート制限を超えていないか確認

コードが期限切れまたは無効:

• 期限切れ後に新しいコードをリクエスト
• SDKがPKCE verifierを保持できるよう、同じブラウザセッションで検証
• ユーザーが最新の6桁コードを入力しているか確認

試行回数が多すぎる:

• ユーザーに新しいコードのリクエストを案内
• 監査ログと診断ログで連続失敗を確認