SSO / OAuth2 サーバー機能 — 中央会員管理 & SSO ヘブ

1. ドキュメントの目的

このドキュメントは、Membership Hub が実行する SSO / OAuth2 サーバー機能の仕様を説明します。SSO ヘブは、Identity Provider (IdP) として機能し、SaaS エコシステム内のアプリケーションに認証トークンを発行します。

2. Membership Hub の OAuth2 サーバー機能

Membership Hub は、OAuth2 Authorization Code Flow with PKCE を実装して、認証標準を提供しています。

Hub の役割は次のとおりです。
├── Authorization Server  →  認証コード & トークンを発行
├── Identity Provider     →  メンバーの ID を保存 & 検証
└── Resource Server       →  メンバーのプロフィール & ライセンス情報を提供

各 SaaS アプリケーションは、エコシステムに参加することで、次の役割を担います。

SaaS アプリケーションは次の役割を担います。
└── OAuth2 クライアント (Relying Party)  →  メンバーの behalf でアクセスを要求

3. OAuth2 エンドポイント

3.1 主要エンドポイントの一覧

3.2 /oauth/authorize — 認証エンドポイント

リクエスト:

GET /oauth/authorize
  ?client_id=CLIENT_ID
  &redirect_uri=https://app.noto.com/auth/callback
  &response_type=code
  &scope=profile:read license:read
  &state=RANDOM_CSRF_STATE
  &code_challenge=PKCE_CODE_CHALLENGE
  &code_challenge_method=S256

パラメーター:

成功レスポンス — リダイレクト先の URI:

https://app.noto.com/auth/callback
  ?code=AUTH_CODE
  &state=RANDOM_CSRF_STATE

失敗レスポンス — エラーを含むリダイレクト先の URI:

https://app.noto.com/auth/callback
  ?error=access_denied
  &error_description=License+not+found
  &state=RANDOM_CSRF_STATE

3.3 /oauth/token — トークンエンドポイント

3.3.1 認証コードをトークンに交換する

リクエスト:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://app.noto.com/auth/callback
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&code_verifier=PKCE_CODE_VERIFIER

レスポンス:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_token_string",
  "scope": "profile:read license:read"
}

3.3.2 リフレッシュトークンを使用してアクセストークンを更新する

リクエスト:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET

レスポンス: トークンを新しく取得した場合と同じです。

3.4 /oauth/userinfo — ユーザー情報エンドポイント

リクエスト:

GET /oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

レスポンス:

{
  "sub": "member_id_123",
  "name": "Budi Santoso",
  "email": "budi@email.com",
  "email_verified": true,
  "picture": null
}

4. JWT アクセストークンの構造

JWT は RS256 (RSA Signature with SHA-256) で署名されています。

4.1 ヘッダー

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-001"
}

4.2 ペイロード (クレーム)

{
  "sub": "member_id_123",
  "name": "Budi Santoso",
  "email": "budi@email.com",
  "email_verified": true,
  "product": "NTO",
  "license_id": "NTO-A1B2-C3D4-E5F6",
  "tier": "free",
  "license_status": "active_free",
  "expires_at": null,
  "iss": "https://hub.domain.com",
  "aud": "noto-client-id",
  "iat": 1720000000,
  "exp": 1720003600,
  "jti": "unique-token-id"
}

4.3 クレームの説明

5. 利用可能なスコープ

6. OAuth2 クライアント (SaaS アプリケーション) の登録

エコシステムに参加する各 SaaS アプリケーションは、OAuth2 クライアントとして登録する必要があります。

6.1 必要な情報