認証連携ガイド
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側の設定
Section titled “Auth0側の設定”フロントエンドのAuth0 SDK設定に以下が必要。
| 項目 | 値 |
|---|---|
audience | utm-backend用に登録したAPI(Resource Server)のidentifier |
scope | openid 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)。
- API契約全体: APIリファレンス(Scalar)
- ローカルで一式立ち上げて試す手順: 実装ガイドライン