メインコンテンツまでスキップ

ID（ユーザー）管理

概要​

idp-server はテナント単位で ID（ユーザー） を管理します。

ID（ユーザー）を複数テナントで所持することはできません。別テナントで作成したID（ユーザー）を利用したい場合は、フェデレーションを実施します。

登録​

idp-server はOIDCの認可コードフローをベースに、2つのユーザー登録機能を提供します。

  1. idp-server へのユーザー登録
  2. 外部IdPとのフェデレーションによるユーザー登録

登録シーケンス​

idp-server へのユーザー登録​

外部IdPとのフェデレーションによるユーザー登録​

外部IdP（Google、Azure AD等）との連携によるユーザー登録の詳細は、フェデレーション（外部IdP連携）を参照してください。

データ構造​

ユーザーID（sub）​

  • 各ユーザーには一意（UUID）な ユーザーID（sub）が割り当てられます。
  • テナントごとにID空間を分離する（tenant_id + sub）

外部ID（provider_id）とのマッピング​

  • 外部IdP（Google, AzureADなど）との連携時には provider_id に基づく一意性を保持
  • 内部IDと外部IDをペアで管理し、Federated Account Mapping を実現

IDポリシー（Identity Policy）​

概要​

IDポリシーは、テナントごとに「どのユーザー属性を一意識別子・ログイン認証情報として使用するか」を制御します。

このポリシーに基づき、ユーザー作成時に自動的に preferred_username が設定されます。

ポリシータイプ​

ポリシータイプ一意性の基準用途・ユースケース
USERNAMEname（ユーザー名）社内システム（従業員IDベース）
USERNAME_OR_EXTERNAL_USER_IDname または external_user_id社内システム + 外部IdP連携
EMAILemail（メールアドレス）一般向けWebサービス・SaaS
EMAIL_OR_EXTERNAL_USER_IDemail または external_user_idデフォルト。一般向け + 外部IdP連携（Google等）
PHONEphone_number（電話番号）モバイルアプリ・SMS認証ベースサービス
PHONE_OR_EXTERNAL_USER_IDphone_number または external_user_idモバイルアプリ + 外部IdP連携
EXTERNAL_USER_IDexternal_user_id完全フェデレーション（外部IdPのみでユーザー管理）

デフォルトポリシー​

テナント作成時のデフォルトは EMAIL_OR_EXTERNAL_USER_ID です。

  • idp-server直接登録: email が preferred_username に設定される
  • 外部IdP連携: external_user_id が preferred_username に設定される

preferred_username の自動設定​

ユーザー作成時（Initial Registration / Management API）、IDポリシーに従って 自動的に preferred_username が設定されます。

設定の仕組み​

  • USERNAME系ポリシー: name が preferred_username に設定される
  • EMAIL系ポリシー: email が preferred_username に設定される
  • PHONE系ポリシー: phone_number が preferred_username に設定される
  • EXTERNAL_USER_ID: external_user_id が preferred_username に設定される

フォールバック動作（_OR_EXTERNAL_USER_ID ポリシー）:

  • 主要属性（email/phone/name）が設定されていない場合、external_user_id にフォールバックします

Password Grant との関係​

Password Grant でのユーザー検索には preferred_username が使用されます。

つまり、トークンリクエストの username パラメータには、IDポリシーで設定された preferred_username の値を指定する必要があります。

例: EMAIL_OR_EXTERNAL_USER_ID ポリシーの場合​

ユーザー作成方法preferred_username に設定される値Password Grant での username パラメータ
Initial Registrationemail (例: user@example.com)user@example.com
Google連携external_user_id (例: google-sub-12345)google-sub-12345

ポリシー変更時の注意事項​

⚠️ 既存ユーザーへの影響

  • IDポリシー変更は 新規登録ユーザーのみ に適用されます
  • 既存ユーザーの preferred_username は変更されません
  • 既存ユーザーのログインに影響を与えないよう、慎重に変更してください

ユーザー属性​

項目型説明取得用スコープ
substringSubject - Issuer における End-User の識別子openid (必須)
provider_idstring外部IdPと連携した場合のID識別子claims:provider_id
external_user_idstring外部IdPのユーザーID(sub)claims:ex_sub
external_user_original_payloadobject外部IdPのユーザークレーム （JSONオブジェクト）claims:external_user_original_payload
namestringEnd-User の表示用フルネーム。肩書きや称号 (suffix) を含むこともあるprofile
given_namestring名（Given Name）profile
family_namestring姓（Family Name）profile
middle_namestringミドルネームprofile
nicknamestringニックネームprofile
preferred_usernamestringEnd-User の選好するユーザー名（例：janedoe）
Password Grantでのログイン識別子として使用		profile
profilestringプロフィールページのURLprofile
picturestringプロフィール画像のURLprofile
websitestringEnd-User のWebサイトURLprofile
emailstringEnd-User の選好するEmailアドレスemail
email_verifiedbooleanEmailアドレスが検証済みかどうかemail
genderstring性別（例：male, female）profile
birthdatestring生年月日（例：1990-01-01）profile
zoneinfostringタイムゾーン情報profile
localestringロケール（例：ja-JP）profile
phone_numberstring電話番号（E.164形式が推奨）phone
phone_number_verifiedboolean電話番号が検証済みかどうかphone
addressobject郵送先住所（JSONオブジェクト）address
statusstringアカウントの状態（ACTIVE, LOCKEDなど）claims:status
custom_propertiesobjectカスタムのユーザークレーム（JSONオブジェクト）claims:custom_properties
credentialsobject資格情報 （JSON配列）claims:credentials
hashed_passwordobjectハッシュ化済みのパスワード- (セキュリティ上取得不可)
authentication_devicesobjectFIDO認証などが実施可能な認証デバイス（JSON配列）claims:authentication_devices
verified_claimsobject身元確認済みのクレームverified_claims:*
rolesarrayユーザーの役割一覧（JSON配列） ← 追加claims:roles
permissionsarrayユーザーの権限一覧（JSON配列） ← 追加claims:permissions
current_tenant_idstring現在選択中のテナントID ← 追加claims:current_tenant_id
assigned_tenantsarrayアクセス可能なテナントID一覧（JSON配列） ← 追加claims:assigned_tenants
current_organization_idstring現在選択中の組織ID ← 追加claims:current_organization_id
assigned_organizationsarray所属組織ID一覧（JSON配列） ← 追加claims:assigned_organizations
created_atstringアカウント作成日時（ISO 8601形式） ← 追加profile
updated_atnumber最終更新日時（UNIXタイムスタンプ）profile

スコープによる属性取得について​

OIDC標準スコープ

  • openid: 必須。subクレームを含む
  • profile: 基本プロフィール情報（name, given_name, family_name等）
  • email: メールアドレス関連（email, email_verified）
  • phone: 電話番号関連（phone_number, phone_number_verified）
  • address: 住所情報（address）

idp-server独自スコープ

  • claims:<属性名>: 特定の属性を個別に取得（例：claims:roles, claims:permissions）
  • verified_claims:*: 身元確認済みクレーム取得

使用例

scope=openid profile email claims:roles claims:assigned_tenants

この場合、標準プロフィール＋メール＋ロール情報＋所属テナント一覧が取得可能になります。

注意事項

  • claims:スコープはcustom_claims_scope_mapping=trueの設定が必要
  • セキュリティ上、hashed_passwordは取得できません
  • 管理者権限が必要な属性もあります

ステータス​

ステータス説明
UNREGISTEREDアカウント未作成
INITIALIZEDユーザーがアカウントを初期化した状態
FEDERATED外部IdPとフェデレーション済み
REGISTERED登録済み
IDENTITY_VERIFICATION_REQUIRED身元確認（eKYC）が必要な状態
IDENTITY_VERIFIED身元確認済み
LOCKED失敗により一時的にロックされた状態
DISABLEDユーザーまたは管理者により無効化された状態
SUSPENDEDポリシー違反により停止された状態
DEACTIVATED無効化リクエスト済み、猶予期間中
DELETED_PENDING猶予期間後に削除予定
DELETED完全削除済み
UNKNOWN不明

ステータス遷移例​

UNREGISTERED
   ↓ 初期化
INITIALIZED
   ↓ 登録
REGISTERED
   ↓ 身元確認完了
IDENTITY_VERIFIED
   ↓ ポリシー違反
SUSPENDED
   ↓ 無効化リクエスト
DEACTIVATED
   ↓ 猶予期間経過
DELETED_PENDING
   ↓ 削除実行
DELETED

ステータスによるアクセス制御​

ユーザーステータスは、各種エンドポイントでのアクセス制御に使用されます。

アクティブと判定されるステータス​

以下のステータスのユーザーのみがアクティブとして扱われます：

ステータス説明
INITIALIZEDアカウント初期化済み
FEDERATED外部IdP連携済み
REGISTERED登録完了
IDENTITY_VERIFICATION_REQUIRED身元確認待ち
IDENTITY_VERIFIED身元確認済み
非アクティブと判定されるステータス​

以下のステータスのユーザーはアクセスが拒否されます：

ステータス説明影響
LOCKED認証失敗によるロックトークン発行・更新・Userinfo不可
DISABLED管理者による無効化トークン発行・更新・Userinfo不可
SUSPENDEDポリシー違反による停止トークン発行・更新・Userinfo不可
DEACTIVATED退会申請による無効化トークン発行・更新・Userinfo不可
DELETED_PENDING削除処理中トークン発行・更新・Userinfo不可
DELETED完全削除済み全アクセス不可
エンドポイント別のステータスチェック​
エンドポイントGrant Typeステータスチェック理由
Token Endpointauthorization_codeなし認可時点でユーザー認証済みのため
Token Endpointrefresh_tokenあり長期間有効なトークンのため、更新時に再検証
Token Endpointpasswordありユーザー認証を含むため
Token Introspection Endpoint-ありトークン有効性検証時にユーザー状態も検証
Userinfo Endpoint-ありユーザー情報取得時に検証
エラーレスポンス​

非アクティブなユーザーでアクセスした場合、以下のエラーが返されます：

Token Endpoint（refresh_token / password）

{
  "error": "invalid_grant",
  "error_description": "user is not active (id: user-123, status: LOCKED)"
}

Token Introspection Endpoint

RFC 7662に準拠し、非アクティブなユーザーのトークンはactive: falseとして返されます（HTTPステータスは200）。

{
  "active": false
}

Userinfo Endpoint

{
  "error": "invalid_token",
  "error_description": "user is not active (id: user-123, status: DISABLED)"
}

削除​

ユーザー削除は物理的にデータを削除します。

以下のデータを削除：

  • 発行済みトークン／認可情報（grant, token）
  • 認証情報（FIDO, Password 等）