コンテンツにスキップ

認証連携ガイド

utm-backendにログイン画面はない。ログインはAuth0(本番)またはmock-oauth2-server(ローカル開発)が行い、フロントエンドはAuth0のSDKで取得したaccess_tokenをそのままAPIへ送る。

1. ブラウザ → Auth0 ログイン(Auth0 SDKが行う)
2. ブラウザ → Auth0 getAccessTokenSilently() でaccess_tokenを取得
3. ブラウザ → utm-backend Authorization: Bearer <access_token> を付けて呼ぶ
4. utm-backend トークンを検証し、内部ユーザーへ解決してから業務APIへ転送する
5. utm-backend → ブラウザ レスポンスを返す

フロントエンドが扱うのはAuth0のaccess_tokenだけであり、utm-backendが内部で発行・使用するトークンをフロントエンドが見たり送ったりすることはない。

ローカル開発(docker compose --profile auth up)ではhttp://localhost:9000。本番・ステージングのURLは別途案内する。

8080への直接アクセスも残っているが、認証を通すAPIは9000を経由する。

フロントエンドのAuth0 SDK設定に以下が必要。

項目値
audienceutm-backend用に登録したAPI(Resource Server)のidentifier
scopeopenid profile emailを含める

audienceを指定しないとAuth0はOpaque token(検証できない値)を返し、utm-backend側で拒否される。scopeにemail系が必要なのは、utm-backendがメールアドレスでユーザーを特定するためである。

ログインできても使えない場合

Section titled “ログインできても使えない場合”

認証必須のAPIは、次のいずれかに該当すると403を返す。

  • ログインしたemailがutm-backend側に登録されていない
  • Auth0側でそのemailがまだ確認(verify)されていない
    • @example.com のように確認メールが届かないメールアドレスは注意

両者は同じ403として返る。アカウントの存在有無を推測されないよう意図的に区別していない。

初回ログイン時、登録済みのemailと一致すればAuth0のアカウントと内部ユーザーの紐づけは自動で行われる。フロントエンドが特別な手順を踏む必要はない。

401・403はいずれもapplication/problem+json(RFC 9457)で返る。トークン切れ・署名不正・未登録emailのいずれも、フロントエンドから見た形は同じ(ステータスコードとtype/title/detail)。