SCIM 2.0

SCIM 2.0 ユーザープロビジョニング

Authrimは、自動化されたユーザーおよびグループプロビジョニングのためにSCIM 2.0（System for Cross-domain Identity Management）をサポートしています。

概要

• 標準: RFC 7643（コアスキーマ）, RFC 7644（プロトコル）
• ステータス: 完全実装
• ベースURL: /scim/v2

サポートされる機能

• ユーザーCRUD操作（作成、読み取り、更新、削除）
• グループCRUD操作
• Discoveryエンドポイント: /ServiceProviderConfig, /ResourceTypes, /Schemas
• /BulkによるBulk操作
• SCIMクエリ構文によるフィルタリング
• startIndexとcountによるページネーション
• ETagによるリソースバージョニング
• PATCH操作による部分更新
• Enterprise User拡張
• Bearerトークン認証

認証

SCIMプロビジョニングリクエストにはBearerトークンが必要です:

Authorization: Bearer YOUR_SCIM_TOKEN

/scim/v2/ServiceProviderConfig、/scim/v2/ResourceTypes、/scim/v2/Schemas配下のDiscoveryエンドポイントは、SCIMクライアントがサーバー機能を検出できるようBearerトークンなしで利用できます。

SCIMトークンの作成

1. Admin UI > SCIMトークンに移動、またはPOST /api/admin/scim-tokensを呼び出す
2. 説明を入力（例：「Okta SCIM統合」）
3. expiresInDaysを設定（デフォルト: 365、最大: 3650）
4. トークンをすぐにコピー（再表示されません）

Admin APIエンドポイント:

Method	Endpoint	説明
GET	/api/admin/scim-tokens	SCIMトークンメタデータを一覧取得
POST	/api/admin/scim-tokens	SCIMトークンを作成
DELETE	/api/admin/scim-tokens/{tokenHash}	SCIMトークンを失効

APIリファレンス

ユーザー

ユーザー一覧取得

GET /scim/v2/Users

クエリパラメータ:

パラメータ	型	説明	例
filter	string	SCIMフィルター式	userName eq "john@example.com"
sortBy	string	ソート属性	userName
sortOrder	string	ascendingまたはdescending	ascending
startIndex	integer	1ベースのページネーションインデックス	1
count	integer	結果数（最大1000）	100

レスポンス:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 250,
  "startIndex": 1,
  "itemsPerPage": 100,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "user-123",
      "userName": "john@example.com",
      "name": {
        "givenName": "John",
        "familyName": "Doe"
      },
      "emails": [{"value": "john@example.com", "primary": true}],
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2024-01-01T00:00:00Z",
        "lastModified": "2024-01-02T00:00:00Z",
        "location": "https://auth.example.com/scim/v2/Users/user-123",
        "version": "W/\"1704153600000\""
      }
    }
  ]
}

ユーザー作成

POST /scim/v2/Users
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "john@example.com",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "emails": [{"value": "john@example.com", "primary": true}],
  "active": true
}

ユーザー更新（PATCH）

PATCH /scim/v2/Users/{id}
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {"op": "replace", "path": "name.givenName", "value": "Jane"},
    {"op": "replace", "path": "active", "value": false}
  ]
}

サポートされる操作:

• add - 新しい属性を追加
• replace - 既存の属性を置換
• remove - 属性を削除

ユーザー削除

DELETE /scim/v2/Users/{id}

グループ

グループ一覧取得

GET /scim/v2/Groups

グループ作成

POST /scim/v2/Groups
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "members": [
    {"value": "user-123", "type": "User"}
  ]
}

Discovery

GET /scim/v2/ServiceProviderConfig
GET /scim/v2/ResourceTypes
GET /scim/v2/Schemas
GET /scim/v2/Schemas/{schemaId}

ServiceProviderConfigでは、PATCH、Bulk、フィルタリング、ソート、ETag、OAuth Bearer token認証の対応状況を公開します。

Bulk操作

POST /scim/v2/Bulk
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
  "Operations": [
    {
      "method": "POST",
      "bulkId": "user1",
      "path": "/Users",
      "data": {
        "userName": "jane@example.com",
        "active": true
      }
    }
  ]
}

Bulkのデフォルト上限は100 operations、1 MB payloadです。KVのSCIM_BULK_MAX_OPERATIONSとSCIM_BULK_MAX_PAYLOAD_SIZEで変更できます。

フィルタリング

SCIMは標準化されたクエリ構文を使用した複雑なフィルタリングをサポートしています。

フィルター演算子

演算子	説明	例
eq	等しい	userName eq "john@example.com"
ne	等しくない	active ne false
co	含む	userName co "john"
sw	で始まる	userName sw "john"
ew	で終わる	userName ew "example.com"
pr	存在する	phoneNumber pr
gt	より大きい	meta.created gt "2024-01-01"
lt	より小さい	meta.created lt "2024-12-31"

論理演算子

演算子	説明	例
and	論理AND	userName eq "john" and active eq true
or	論理OR	userName eq "john" or userName eq "jane"
not	論理NOT	not (active eq false)

例

# メールでユーザーを検索
GET /scim/v2/Users?filter=userName eq "john@example.com"

# アクティブなユーザーを検索
GET /scim/v2/Users?filter=active eq true

# 複合フィルター
GET /scim/v2/Users?filter=(userName co "john" or userName co "jane") and active eq true

ページネーション

SCIMはstartIndexとcountパラメータで1ベースのページネーションを使用します。

# 最初のページ（アイテム1-100）
GET /scim/v2/Users?startIndex=1&count=100

# 2番目のページ（アイテム101-200）
GET /scim/v2/Users?startIndex=101&count=100

リソースバージョニング（ETag）

SCIMは楽観的同時実行制御のためにETagをサポートしています:

# ETag付きでユーザーを取得
GET /scim/v2/Users/user-123
Response: ETag: W/"1704153600000"

# ETag付きで更新
PUT /scim/v2/Users/user-123
If-Match: W/"1704153600000"

エラーレスポンス

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "400",
  "scimType": "invalidValue",
  "detail": "userNameは必須です"
}

scimType	HTTPステータス	説明
invalidFilter	400	無効なフィルター構文
invalidValue	400	無効な属性値
uniqueness	409	リソースが既に存在
mutability	400	読み取り専用属性の変更試行
noTarget	404	リソースが見つからない
invalidVers	412	ETag不一致

統合ガイド

Okta

1. Authrim Admin UIでSCIMトークンを生成
2. Oktaアプリを設定:
   • SCIM Base URL: https://YOUR_DOMAIN/scim/v2
   • 認証: HTTPヘッダー
   • Authorization: Bearer YOUR_TOKEN
3. プロビジョニングを有効化:
   • ユーザー作成
   • ユーザー属性更新
   • ユーザー無効化

Azure AD (Entra ID)

1. エンタープライズアプリケーションを追加（非ギャラリー）
2. プロビジョニングを設定:
   • プロビジョニングモード: 自動
   • テナントURL: https://YOUR_DOMAIN/scim/v2
   • シークレットトークン: YOUR_TOKEN
3. 接続をテストして属性マッピングを設定

OneLogin

1. Applications > Add App > SCIM Provisioner
2. 設定:
   • SCIM Base URL: https://YOUR_DOMAIN/scim/v2
   • SCIM Bearer Token: YOUR_TOKEN
   • API Connection: SCIM 2.0

属性マッピング

ユーザー属性

SCIM属性	Authrim canonical storage	型
id	identity_accounts.legacy_user_id projection	string（読み取り専用）
externalId	identity_accounts.external_id	string
userName	preferred_username sensitive attribute、なければprimary email	string（必須）
name.givenName	profile_attribute_values + identity_sensitive_values	string
name.familyName	profile_attribute_values + identity_sensitive_values	string
emails[primary].value	contact_points + identity_sensitive_values	string（必須）
phoneNumbers[primary].value	contact_points + identity_sensitive_values	string
active	identity_accounts.lifecycle_state projection	boolean
locale	sensitive profile attribute	string
timezone	zoneinfo sensitive profile attribute	string

SCIMはcanonical runtime identity projectionを通じて読み書きします。PII DBが設定されている場合、PII値はPII DBに保存され、lookup hashやlifecycle stateはcore DBに保持されます。

ベストプラクティス

セキュリティ

• トークンを定期的にローテーション（例：90日ごと）
• 統合ごとに別々のトークンを使用
• 監査ログでトークン使用状況を監視
• すべてのSCIMリクエストにHTTPSを使用

パフォーマンス

• フィルタリングを使用してレスポンスサイズを削減
• 大きなデータセットにページネーションを実装
• 不要な更新を避けるためにETagを使用

エラー処理

• 指数バックオフでリトライロジックを実装
• 429（レート制限）レスポンスを処理
• トラブルシューティングのためにすべてのエラーをログ

レート制限

• 通常のSCIM操作は設定済みのmoderate rate-limit profileを使用
• /scim/v2/Bulkは設定済みのstrict rate-limit profileを使用
• 超過時は429 Too Many Requestsを返し、可能な場合はRetry-Afterヘッダーを含める

参考資料

• RFC 7643 - SCIM Core Schema
• RFC 7644 - SCIM Protocol