コンテンツにスキップ

IAMオンボーディングガイド

IAM(認証・ユーザー・組織)に初めて触れる開発者向けの文書。手順や設計判断の理由はここには書かない。全体像を掴んでから、必要な文書へ進めるようにする。

文書読者内容
本書本リポジトリの開発者IAMの全体像
実装ガイドライン同上手順(RLSを足す、認証を有効化する、など)
docs/iam/design/同上設計判断とその理由、却下した代替案
認証連携ガイドフロントエンド・API利用者APIの繋ぎ方
  • Auth0(本番)/mock-oauth2-server(ローカル開発): ログインを行うIdP
  • auth-service: IdPのトークンを検証し、内部トークンへ置き換えるGoのリバースプロキシ
  • Spring: 業務API。内部トークンだけを信頼し、RLSで組織ごとにデータを分離する
  • PostgreSQL: iamスキーマにユーザー・組織・所属・IdP接続を持つ
erDiagram
    organizations ||--o{ org_memberships : "has"
    users ||--o{ org_memberships : "belongs to"
    users ||--o{ idp_connections : "has"

    organizations {
        uuid id
        string name
    }
    users {
        uuid id
        string name
        string email
    }
    org_memberships {
        uuid id
        uuid user_id
        uuid organization_id
    }
    idp_connections {
        uuid id
        uuid user_id
        string provider
        string subject
    }

所属は最初から多対多(org_memberships)で作ってある。1ユーザーが将来複数組織に属するようになってもテーブル構造を変えずに済むようにするためである。ただし現在の実装は単一所属を前提にしており、2件以上所属するとOrganizationMember.ofがエラーにする。

idp_connectionsはIdPごとのsubjectの形の違い(Auth0はauth0|xxx)を吸収する。1ユーザーが複数のIdPを持てるようにするための分離でもある。

IAMのデータモデルはutm-design-docsのdocs/data-model/data-model.mdにある。ロール・権限・SCP(Service Control Policy)・招待・イベントテーブルによる状態導出・個人組織の自動プロビジョニング・SystemOperatorを持つ、より広いモデルである。

上記の設計はこれを狭めたものであり、別設計ではなくサブセットである。後から足すときの多くは既存テーブルを変えない追加(列追加・テーブル追加)になるよう設計してある。 削った理由と拡張の道筋はdocs/iam/design/2026-08-10-iam-minimum-design-decisions.mdに書いてある。

sequenceDiagram
    participant B as ブラウザ
    participant IdP as Auth0/mock-oauth2-server
    participant AS as auth-service (:9000)
    participant Spring as Spring (:8080)
    participant PG as PostgreSQL

    B->>IdP: ログイン、access_token取得
    B->>AS: Authorization: Bearer <access_token>
    AS->>AS: JWKSで署名検証、iss/aud/expを検証
    alt L1キャッシュヒット
        AS->>AS: userIdをキャッシュから取得
    else L1キャッシュミス
        AS->>IdP: GET /userinfo(同じaccess_tokenを転送)
        IdP-->>AS: email, email_verified
        AS->>Spring: POST /api/v1/internal/auth/resolve(M2Mトークン)
        Spring->>PG: idp_connectionsを引く。無ければemailで引き当てて作る
        Spring-->>AS: userId(または403)
        AS->>AS: userIdをL1へ格納
    end
    AS->>AS: 内部トークンを発行(sub=userId)
    AS->>Spring: Authorizationを内部トークンへ置換して転送
    Spring->>PG: SessionContextを確立、組織を解決、GUCを設定
    Spring-->>B: レスポンス

POST /api/v1/internal/auth/resolve(ResolveIdentityUseCase)はIdPのsubjectを内部のuserIdへ変換する。呼び出すのはauth-serviceだけである。

  1. idp_connectionsに(provider, subject)の行があれば、そのままuserIdを返す
  2. なければ、検証済み(email_verified)のメールアドレスでusersを引き当て、idp_connectionsの行を作る。初回ログイン時のアカウントリンクの実体はここにある
  3. メールアドレスが未登録、または未検証なら403(IdentityNotLinkableException)

email_verifiedを必須にする理由は、Auth0のデータベース接続では誰でも任意のメールアドレスを名乗って自己サインアップできるためである。未検証を許すと他人のメールアドレスを騙って既存アカウントを乗っ取れる。

/resolveは組織Contextが確定する前の処理なのでSessionContext.none()で実行する。iamスキーマのテーブルにRLSをかけていないのはこのためである。組織が定まる前に読み書きする唯一の操作であり、RLSの対象にすると自己矛盾する。

認証必須のAPIが呼ばれると、内部トークンのsub(userId)からSessionContext.UserSessionが作られる。

sequenceDiagram
    participant H as Handler
    participant TM as TransactionManager
    participant RSI as RlsSessionInitializer
    participant PG as PostgreSQL

    H->>TM: execute(UserSession(userId), ...)
    TM->>RSI: initializeSession(context)
    RSI->>PG: 所属組織を読む
    RSI->>PG: SET LOCAL ROLE utm_app
    RSI->>PG: set_config('app.user_id', userId)
    RSI->>PG: set_config('app.org_id', organizationId)
    Note over PG: 以降のSELECT/UPDATEはRLSポリシーが<br/>iam.current_org_id()(app.org_idをuuidで読む)で絞る

組織所有テーブルのポリシーは次の形になる(iam.rls_reference_examplesが実装例)。

CREATE POLICY xxx_tenant ON xxx
FOR ALL
USING (organization_id = (SELECT iam.current_org_id()))
WITH CHECK (organization_id = (SELECT iam.current_org_id()));

ポリシーはGUCをcurrent_settingで直接読まず、iam.current_org_id()(db/schema/00_iam_functions.sql)を呼ぶ。app.org_idが未設定・空文字ならこの関数がエラーで落ちる。(SELECT …)で包むのは、行ごとではなく文ごとに1回だけ評価させるためである。

SET LOCAL ROLE utm_appはNoSessionでも必ず実行する。アプリの接続プールが使うDBユーザーはスーパーユーザーとして作られており、ロールを切り替えなければRLSがそもそも適用されないためである。

組織を読むのはロールを落とす前、SET LOCAL ROLEより前である。権限を落としたあとでは読めなくなる。

APIはSecurityPathsで4分類される。

分類意味
PUBLIC認証不要と契約で定めた経路(/actuator/**など)
MIGRATING認証の有効化を待っている。無認証で到達できる
PROTECTED認証必須。aud=utm-backend
INTERNAL内部API専用。aud=utm-backend-internal、ポートも別
  • 手順(RLS対応テーブルの追加、認証の有効化、auth-serviceのローカル起動): 実装ガイドライン
  • 設計判断とその理由: docs/iam/design/
  • フロントエンド・API利用者向けの契約: 認証連携ガイド