IAMオンボーディングガイド
IAM(認証・ユーザー・組織)に初めて触れる開発者向けの文書。手順や設計判断の理由はここには書かない。全体像を掴んでから、必要な文書へ進めるようにする。
文書の使い分け
Section titled “文書の使い分け”| 文書 | 読者 | 内容 |
|---|---|---|
| 本書 | 本リポジトリの開発者 | IAMの全体像 |
| 実装ガイドライン | 同上 | 手順(RLSを足す、認証を有効化する、など) |
docs/iam/design/ | 同上 | 設計判断とその理由、却下した代替案 |
| 認証連携ガイド | フロントエンド・API利用者 | APIの繋ぎ方 |
- Auth0(本番)/mock-oauth2-server(ローカル開発): ログインを行うIdP
auth-service: IdPのトークンを検証し、内部トークンへ置き換えるGoのリバースプロキシ- Spring: 業務API。内部トークンだけを信頼し、RLSで組織ごとにデータを分離する
- PostgreSQL:
iamスキーマにユーザー・組織・所属・IdP接続を持つ
データモデル
Section titled “データモデル”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を持てるようにするための分離でもある。
将来設計との関係
Section titled “将来設計との関係”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: レスポンス
/resolveの役目
Section titled “/resolveの役目”POST /api/v1/internal/auth/resolve(ResolveIdentityUseCase)はIdPのsubjectを内部のuserIdへ変換する。呼び出すのはauth-serviceだけである。
idp_connectionsに(provider, subject)の行があれば、そのままuserIdを返す- なければ、検証済み(
email_verified)のメールアドレスでusersを引き当て、idp_connectionsの行を作る。初回ログイン時のアカウントリンクの実体はここにある - メールアドレスが未登録、または未検証なら403(
IdentityNotLinkableException)
email_verifiedを必須にする理由は、Auth0のデータベース接続では誰でも任意のメールアドレスを名乗って自己サインアップできるためである。未検証を許すと他人のメールアドレスを騙って既存アカウントを乗っ取れる。
/resolveは組織Contextが確定する前の処理なのでSessionContext.none()で実行する。iamスキーマのテーブルにRLSをかけていないのはこのためである。組織が定まる前に読み書きする唯一の操作であり、RLSの対象にすると自己矛盾する。
RLSとの関係
Section titled “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より前である。権限を落としたあとでは読めなくなる。
認証を有効化する単位
Section titled “認証を有効化する単位”APIはSecurityPathsで4分類される。
| 分類 | 意味 |
|---|---|
PUBLIC | 認証不要と契約で定めた経路(/actuator/**など) |
MIGRATING | 認証の有効化を待っている。無認証で到達できる |
PROTECTED | 認証必須。aud=utm-backend |
INTERNAL | 内部API専用。aud=utm-backend-internal、ポートも別 |