Entra ID・Okta・Google でのシングルサインオン

社内 ERP や業務アプリでは、ID はすでに社内ディレクトリ（Microsoft Entra ID・Okta・Google Workspace）に存在し、アカウント・グループ・MFA・条件付きアクセスが一元管理されているのが普通です。Kozou には別建ての消費者向けログインではなく、その ディレクトリを使ってほしいはずです。

できます。Kozou は identity を委譲 します。既存の OpenID Connect (OIDC) プロバイダに向けるだけで、Kozou はそのプロバイダが発行するトークンを検証します。仕組みはどのプロバイダでも同じで、社内利用では社内ディレクトリに向けるだけです。

本ガイドはまず Entra ID を扱い、Okta と Google の対応値も併記します。背後のコマンドは kozou dev、概念的な全体像は 認証と認可 を参照してください。

どう噛み合うか

3 者がそれぞれ 1 つの役割を担います。

1. ID プロバイダがユーザーをサインインさせ（パスワード・MFA・条件付きアクセス）、誰でどのロールかを示す署名付き OIDC JWT を発行する。
2. Kozou がそのトークンをプロバイダの公開鍵で検証し、リクエストをトランザクション内で SET LOCAL ROLE <claim の role> の下で実行する。
3. PostgreSQL の RLS — あなた自身の行レベルセキュリティポリシー — が、そのロールに何を読み書きさせるか決める。

Kozou は resource server / 施行層です。トークンを検証して role を切り替えますが、ユーザーをサインインさせることはなく、policy も書きません。これにより identity はそれを守るために作られたシステムに、アクセス制御はすべての client に適用されるデータベースに置かれます。

はじめる前に

• アプリ登録済みの OIDC ID プロバイダ — Entra ID・Okta・Google Workspace のいずれか。
• アプリが必要とするロール用の PostgreSQL ロールと RLS ポリシー（例: app_admin・app_editor・app_author・app_viewer）。Kozou はこれらのロールに切り替え、あなたの policy が施行します。database.url のログインロールは各ロールへの membership を GRANT されている必要があります。
• トークンをリクエストに届ける手段。 Kozou は bearer トークンを検証しますが、ブラウザのサインイン自体は行いません — 後述のサインインフローを参照。

Kozou を ID プロバイダに向ける

kozou.config.yaml に auth ブロックを追加します。Kozou はプロバイダの JWKS エンドポイントから鍵を取得し（kid で選択・キャッシュ・ローテーション追従）、issuer と audience を検証します。Entra ID の場合:

auth:
  jwt:
    jwksUri: https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys
    issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
    audience: <application-client-id>   # API アプリの client ID / App ID URI
    algorithms: [RS256]
  roleClaim: role
  allowedRoles: [app_admin, app_editor, app_author, app_viewer]
  defaultRole: app_viewer

エンドポイントはプロバイダごとに違いますが、形は同じです。

プロバイダ	jwksUri	issuer
Microsoft Entra ID	https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys	https://login.microsoftonline.com/<tenant-id>/v2.0
Okta	https://<org>.okta.com/oauth2/<server-id>/v1/keys	https://<org>.okta.com/oauth2/<server-id>
Google Workspace	https://www.googleapis.com/oauth2/v3/certs	https://accounts.google.com

プロバイダの v2.0 / OIDC エンドポイントを使ってください（Entra ID では上記の v2.0 issuer であり、旧 v1.0 ではありません）。Kozou 側に秘密鍵は不要で、検証は公開鍵のみで行われます。

ID を PostgreSQL ロールに対応付ける

ここが注意の要る唯一のステップです。Kozou は assume する PostgreSQL ロールを 名指しする 単一の claim（roleClaim、既定 role）を読み、その下でリクエストを実行します。一方、社内ディレクトリは membership を異なる形で表します。

• Entra ID は app role を roles 配列、グループ membership を groups（GUID の配列）で出します。
• Okta / Google はグループやカスタム claim を、やはり配列で出すことがあります。

そこで、プロバイダ側で PostgreSQL ロール名そのものを値とする単一スカラー claim を出させます。Entra ID では、アプリ登録に App Roles（例: app_editor）を定義してユーザーやグループを割り当て、選ばれたロールを roleClaim に一致する名前のスカラー claim として出す（app role → claim、またはオプション/マップド claim 設定）よう構成します。そのうえで:

  roleClaim: role            # DB ロールを名指しするスカラー claim
  allowedRoles: [app_admin, app_editor, app_author, app_viewer]
  defaultRole: app_viewer    # token が claim を欠くときのロール
  # anonRole: web_anon       # token が無いリクエスト用のロール（無ければ 401）

ロールが allowedRoles に無い token は 403。token の無いリクエストは 401 ですが、anonRole を設定するとその匿名ロールで空 claims のまま実行され、何を見せるかは RLS が決めます。

現状の Kozou はこのスカラー role claim を前提とします。roles 配列の消費や groups → role の直接マッピングは将来の拡張候補です。それまでは上記の App Role → スカラー claim マッピングが経路になります。

サインインフロー: Kozou の前段にプロキシを置く

Kozou はトークンを検証しますが、OIDC の認可コードによるサインインやブラウザセッションの保持は 行いません。社内デプロイでは、そのフローは Kozou の前段のレイヤーが担います。

• OIDC 対応のリバースプロキシ（例: oauth2-proxy、または Microsoft Entra Application Proxy）が Entra ID でユーザーを認証し、得た bearer トークンを Kozou の API に転送する、または
• 自前のアプリシェルがサインインを行い、トークン付きで API を呼ぶ。

同梱の参照 Admin UI（kozou dev）は trusted-token モデル向けです。外部 ID プロバイダ下では、自前で対話ログインを行うのではなく、auth.ui.token（または環境変数 KOZOU_ADAPTER_TOKEN）で渡される 用意済みトークンを送ります。完全な対話的社内サインインには、上記いずれかのレイヤーを前段に置いてください。

プロバイダ別メモ

• Microsoft Entra ID・Okta・Google Workspace は JWKS エンドポイントを持つ OIDC プロバイダで、上記の auth.jwt 設定でそのまま動きます。
• GitHub は汎用の OIDC ログインプロバイダではありません（OAuth アプリは検証可能な OIDC JWT ではなく不透明トークンを出します）。「GitHub でサインイン」を提供するには、GitHub を social connector として扱える IdP — Microsoft Entra External ID・Auth0・Keycloak — を経由してブリッジし、Kozou はその IdP の JWKS に向けてください。

次はどこへ

• 認証と認可 — Kozou が施行するものと委譲するもの。
• REST API ガイド — トークン検証後の SET LOCAL ROLE + RLS のフロー。
• kozou.config.yaml — auth ブロックが置かれる設定ファイル。