認証・ミドルウェア仕様

概要

BFF には2種類の認証方式があります。

認証方式	対象	ヘッダー
JWT Bearer 認証	GraphQL エンドポイント（/graphql）	Authorization: Bearer <token>
API キー認証	REST コールバック（/api/v1/DrivingReport/GenerateCallback）	x-api-key: <key>

GraphQL の場合、すべてのフィールドが認証必須ではなく、@isAuthenticated ディレクティブが付いているフィールドのみ認証が行われます。

---

JWT 認証（GraphQL）

フロー

sequenceDiagram
    participant FE as フロントエンド
    participant DIR as @isAuthenticated ディレクティブ
    participant AUTH as AuthenticationHandler
    participant MLOCA as mloca-api

    FE->>DIR: GraphQL リクエスト<br/>Authorization: Bearer <token>
    DIR->>AUTH: Authorization(ctx)

    AUTH->>AUTH: Authorization ヘッダーの存在確認
    AUTH->>AUTH: "Bearer " プレフィックスの確認

    AUTH->>MLOCA: 公開鍵取得（JWK）
    MLOCA-->>AUTH: RSA 公開鍵（PEM形式）

    AUTH->>AUTH: JWT 署名検証（RS256）
    AUTH->>AUTH: クレーム検証

    alt 検証失敗
        AUTH-->>DIR: UnAuthenticated エラー
        DIR-->>FE: GraphQL エラーレスポンス
    else 検証成功
        AUTH->>AUTH: auth_user をコンテキストに格納
        DIR->>DIR: next resolver へ処理を委譲
        DIR-->>FE: GraphQL レスポンス
    end

リクエスト仕様

Authorization: Bearer <JWT トークン>

• Bearer プレフィックスが必須（スペースを含む）
• ヘッダーが存在しない、または Bearer で始まらない場合は即座に認証エラー

トークン検証仕様

項目	内容
署名アルゴリズム	RS256
公開鍵取得元	mloca-api（リクエストごとに動的取得）
公開鍵形式	PEM 形式（RSA 公開鍵）

クレーム検証仕様

必須クレーム

クレーム	検証内容
preferred_username	空文字でないこと
org:id	空文字でないこと
iss または aud	環境変数 TOKEN_ISSUSERS（カンマ区切り）に含まれること
region	空文字でないこと

任意クレーム

クレーム	型	説明
is_admin	Boolean	管理者フラグ。未指定の場合は false
loggedin_id	String	代理ログイン時のログインID
chat_id	String	チャットサービスのユーザーID

認証後のコンテキスト

認証成功後、以下の AuthUser 構造体がリクエストコンテキストに auth_user キーで格納され、各リゾルバーから参照できます。

フィールド	型	JWTクレーム	説明
MlocaUser	string	preferred_username	モバロケのユーザー名
Org	string	org:id	組織（顧客）コード
Issuser	string	iss	JWT 発行元
Region	string	region	リージョン
IsAdmin	bool	is_admin	管理者フラグ（デフォルト: false）
LoggedInId	*string	loggedin_id	代理ログイン時のID（任意）
ChatId	*string	chat_id	チャットユーザーID（任意）

---

API キー認証（REST）

リクエスト仕様

x-api-key: <API キー>

項目	内容
対象エンドポイント	POST /api/v1/DrivingReport/GenerateCallback POST /api/v1/UserAccount/BulkOperationCallback POST /api/v1/Mobile/BulkUpdateCallback
キーの設定場所	環境変数 TASK_CALLBACK_API_KEY
認証失敗時	401 Unauthorized を返しリクエストを中断

---

GraphQL ディレクティブ @isAuthenticated

定義

directive @isAuthenticated on FIELD_DEFINITION

動作

@isAuthenticated が付いた Query / Mutation フィールドへのリクエスト時に JWT 認証が実行されます。認証失敗の場合はリゾルバーは呼ばれず、エラーレスポンスが返ります。

認証不要のフィールド一覧

以下のフィールドは @isAuthenticated が付いておらず、JWT トークンなしでアクセスできます。

Mutation

フィールド	説明
userLogin	ログイン
refreshUserToken	リフレッシュトークンによるトークン更新
verifyOtp	OTP 認証
sendOtp	OTP 発行
sendTestOtp	OTP 発行（テスト用）

---

エラーレスポンス

JWT 認証エラー（GraphQL）

認証失敗時は GraphQL のエラーレスポンス形式で返ります。

{
  "errors": [
    {
      "message": "token is invalid",
      "path": ["<フィールド名>"],
      "extensions": {
        "code": "UnAuthenticated",
        "status": 400,
        "path": ["<フィールド名>"]
      }
    }
  ]
}

エラーパターン

状況	message	status
Authorization ヘッダーなし	Authorization header not set	400
Bearer プレフィックスなし	token is invalid	400
JWT 署名検証失敗	token is invalid	400
クレーム検証失敗	token is invalid	400

API キー認証エラー（REST）

{
  "message": "Unauthorized"
}

状況	HTTP ステータス
x-api-key が不正または欠落	401 Unauthorized