アプリケーション開発者はクロスドメイン ID 管理システム (SCIM) ユーザー管理 API を使用して、アプリケーションと Microsoft Entra ID の間のユーザーとグループの自動プロビジョニングを有効にできます。 この記事では、SCIM エンドポイントを構築し、Microsoft Entra プロビジョニング サービスと統合する方法について説明します。 SCIM 仕様では、プロビジョニングのための共通のユーザー スキーマが提供されます。 SAML や OpenID Connect などのフェデレーション標準とともに使用した場合、SCIM では エンドツーエンドの標準ベースのアクセス管理用ソリューションが管理者に提供されます。
SCIM 2.0 は、2 つのエンドポイント (/Users エンドポイントと /Groups エンドポイント) の標準化された定義です。 オブジェクトの作成、更新、および削除を行う共通の REST API エンドポイントを使用します。 SCIM は、グループ名、ユーザー名、名、姓、メール アドレスなどの一般的な属性の定義済みのスキーマで構成されています。
SCIM 2.0 REST API を提供するアプリでは、独自のユーザー管理 API を使用する煩わしさを軽減するか、なくすことができます。 たとえば、準拠している SCIM クライアントは、JSON オブジェクトの HTTP POST を /Users エンドポイントに送信して新しいユーザー エントリを作成する方法を認識しています。 同じ基本的なアクションに対して若干異なる API を必要とするのではなく、SCIM 標準に準拠しているアプリでは、既存のクライアント、ツール、およびコードをすぐに利用できます。
SCIM 2.0 (RFC 7642、7643、7644) で定義されている管理用の標準ユーザー オブジェクト スキーマと rest API を使用すると、ID プロバイダーとアプリを相互に簡単に統合できます。 SCIM エンドポイントを構築するアプリケーション開発者は、カスタム作業を行わなくても、SCIM 準拠の任意のクライアントと統合できます。
アプリケーションへのプロビジョニングを自動化するには、Microsoft Entra プロビジョニング サービスによってアクセスされる SCIM エンドポイントを構築して統合する必要があります。 アプリケーションへのユーザーとグループのプロビジョニングを開始するには、次の手順を使用します。
ユーザーとグループのスキーマを設計 する - アプリケーションのオブジェクトと属性を特定して、Microsoft Entra SCIM 実装でサポートされているユーザーおよびグループ スキーマにマップする方法を決定します。
Microsoft Entra SCIM の実装について - SCIM プロトコル要求の処理と応答をモデル化するために Microsoft Entra プロビジョニング サービスがどのように実装されているかを理解します。
SCIM エンドポイントを構築 する - Microsoft Entra プロビジョニング サービスと統合するには、エンドポイントが SCIM 2.0 と互換性がある必要があります。 オプションとして、Microsoft 共通言語基盤 (CLI) ライブラリとコード サンプルを使用してエンドポイントを構築します。 これらのサンプルは、参照とテストのみを目的としています。実稼働アプリの依存関係として使用することはお勧めしません。
SCIM エンドポイントを Microsoft Entra プロビジョニング サービスと統合します。 Microsoft Entra ID では、SCIM 2.0 を実装する複数のサードパーティ アプリケーションがサポートされています。 これらのアプリのいずれかを使用すると、ユーザーとグループのプロビジョニングとプロビジョニング解除の両方をすばやく自動化できます。
[省略可能] アプリケーションを Microsoft Entra アプリケーション ギャラリーに発行 する - 顧客がアプリケーションを簡単に検出し、プロビジョニングを簡単に構成できるようにします。
ユーザーとグループのスキーマを設計する
アプリケーションはそれぞれ、ユーザーまたはグループを作成するためのさまざまな属性を必要とします。 アプリケーションで必要なオブジェクト (ユーザー、グループ) および属性 (名前、マネージャー、役職など) を特定して、統合を開始します。
SCIM 標準では、ユーザーとグループを管理するためのスキーマが定義されています。
コア ユーザー スキーマに必要な属性は 3 つだけです (他のすべての属性は省略可能です)。
-
id(サービス プロバイダーが定義した識別子) -
userName(ユーザーの一意識別子。通常、Microsoft Entra ユーザー プリンシパル名にマップされます) -
meta、サービス プロバイダーによって管理される 読み取り専用 メタデータ
SCIM 標準では、 コア ユーザー スキーマに加えて、アプリケーションのニーズに合わせてユーザー スキーマを拡張するためのモデルを持つ エンタープライズ ユーザー拡張機能を定義します。
たとえば、アプリケーションでユーザーの電子メールとユーザーのマネージャーの両方が必要な場合は、 コア スキーマを使用してユーザーの電子メールを収集し、 エンタープライズ ユーザー スキーマを使用してユーザーのマネージャーを収集します。
スキーマを設計するには、次の手順に従います。
アプリケーションに必要な属性を一覧表示し、認証に必要な属性 (loginName や電子メールなど) として分類します。 属性は、ユーザーのライフサイクル (状態やアクティブなど) と、アプリケーションの動作に必要なその他すべての属性 (マネージャー、タグなど) を管理するために必要です。
属性がコア ユーザー スキーマまたはエンタープライズ ユーザー スキーマで既に定義されているかどうかを確認します。 定義されていない場合は、欠けている属性をカバーする拡張機能をユーザー スキーマに対して定義する必要があります。 ユーザー
tagをプロビジョニングできるようにする、ユーザーに対する拡張機能についての例を参照してください。SCIM 属性を Microsoft Entra ID のユーザー属性にマップします。 SCIM エンドポイントで定義した属性のいずれにも、Microsoft Entra ユーザー スキーマに明確に対応するものがない場合、テナント管理者にスキーマの拡張を求めるか、例に示す拡張属性を
tagsプロパティに使用します。
次の表に、必要な属性の例を示します。
| アプリの必須属性と例 | 対応する SCIM の属性 | 対応する Microsoft Entra の属性 |
|---|---|---|
| ログイン名 | userName | ユーザープリンシパル名 |
| ファーストネーム | 名前.名 | givenName |
| 苗字 | 名前.姓 | 名字 |
| ワークメール | emails[type eq "仕事"].value | 郵便 |
| マネージャー | マネージャー | マネージャー |
| タグ | urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag |
extensionAttribute1 |
| ステータス | 活動中 | isSoftDeleted (ユーザーに格納されない計算値) |
次の JSON ペイロードは、SCIM スキーマの例を示しています。
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User"],
"userName":"bjensen@testuser.com",
"id": "48af03ac28ad4fb88478",
"externalId":"bjensen",
"name":{
"familyName":"Jensen",
"givenName":"Barbara"
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"manager": "123456"
},
"urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {
"tag": "701984",
},
"meta": {
"resourceType": "User",
"created": "2010-01-23T04:56:22Z",
"lastModified": "2011-05-13T04:42:34Z",
"version": "W\/\"3694e05e9dff591\"",
"location":
"https://example.com/v2/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}
}
注
アプリケーションに必要な属性に加えて、JSON の表現には、必要な id、externalId、meta の各属性も含まれています。
これは、microsoft Entra ID の既定のユーザー属性を SCIM RFC にマップするために、 /User と /Group の間で分類するのに役立ちます。 Microsoft Entra ID と SCIM エンドポイントの間でカスタマイズ属性がどのようにマップされるかを参照してください。
次の表に、ユーザー属性の例を示します。
| Microsoft Entra ユーザー | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
|---|---|
| ソフト削除済みかどうか | 活動中 |
| 部門 | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department |
| 表示名 | 表示名 |
| 従業員ID | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber |
| Facsimile-TelephoneNumber | phoneNumbers[type eq "ファックス"].value |
| givenName | 名前.名 |
| 職務タイトル | タイトル |
| 郵便 | emails[type eq "仕事"].value |
| メールニックネーム | エクスターナルID |
| マネージャー | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager |
| 携帯電話 | 電話番号[タイプ eq "携帯"].値 |
| 郵便番号 | addresses[タイプ eq "work"].郵便番号 |
| プロキシ-アドレス | emails[type eq "other"].値 |
| フィジカル-Delivery-OfficeName | addresses[type eq "other"].整形済み |
| 住所 | アドレス[タイプ eq "作業"].ストリートアドレス |
| 名字 | 名前.姓 |
| 電話番号 | phoneNumbers[タイプが "職場" の場合].値 |
| user-PrincipalName | userName |
次の表に、グループ属性の例を示します。
| Microsoft Entra グループ | urn:ietf:params:scim:schemas:core:2.0:Group |
|---|---|
| 表示名 | 表示名 |
| メンバー | メンバー |
| objectId | エクスターナルID |
注
ユーザーとグループの両方をサポートする必要はありません。ここに記載されているすべての属性をサポートする必要もありません。これはあくまで参考として、Microsoft Entra ID の属性が多くの場合どのように SCIM プロトコルのプロパティにマップされるかを示したものです。
SCIM RFC では複数のエンドポイントが定義されています。
/User エンドポイントで開始し、そこから展開できます。 次の表に、いくつかの SCIM エンドポイントを示します。
| エンドポイント | 説明 |
|---|---|
| /利用者 | ユーザー オブジェクトに対して CRUD 操作が実行されます。 |
| /Group | グループ オブジェクトに対して CRUD 操作が実行されます。 |
| /スキーマ | 各クライアントおよびサービス プロバイダーによってサポートされている属性のセットは、異なる場合があります。 たとえば、あるサービス プロバイダーに name、title、emails が含まれ、別のサービス プロバイダーに name、title、phoneNumbers が使用されることがあります。 スキーマ エンドポイントにより、サポートされている属性を検出できます。 |
| /大量 | 一括操作を使用すると、1 回の操作でリソース オブジェクトの大きなコレクションに対する操作を実行できます (たとえば、大きなグループのメンバーシップの更新)。 現在、SCIM /Bulk はサポートされていませんが、これはパフォーマンスの向上に役立つ将来のサポートを目的としています。 |
| /ServiceProviderConfig | サポートされているリソースや認証方法など、サポートされている SCIM 標準の機能についての詳細が提供されます。 |
| /ResourceTypes | 各リソースに関するメタデータを指定します。 |
注
カスタム属性をサポートする場合やスキーマが頻繁に変更される場合は、/Schemas エンドポイントを使用してください。クライアントで最新のスキーマを自動的に取得できます。 グループをサポートするには、/Bulk エンドポイントを使用します。 現在、/Bulk エンドポイントはサポートされていませんが、これはパフォーマンスの向上に役立つ将来のサポートを目的としています。
Microsoft Entra SCIM 実装について理解する
Microsoft Entra プロビジョニング サービスは、SCIM 2.0 ユーザー管理 API をサポートするように設計されています。
重要
Microsoft Entra SCIM の実装の動作は、2018 年 12 月 18 日に最終更新が行われました。 変更の詳細については、 Microsoft Entra ユーザー プロビジョニング サービスの SCIM 2.0 プロトコルコンプライアンスを参照してください。
SCIM 2.0 プロトコル仕様の中で、アプリケーションは次の要件をサポートする必要があるとされています。
| 要件 | 参考 (SCIM プロトコル) |
|---|---|
| ユーザーを (必要に応じてグループも) 作成する | セクション 3.3 |
| PATCH 要求でユーザーまたはグループを変更する | セクション 3.5.2. サポートにより確実に、パフォーマンスの高い方法でグループとユーザーがプロビジョニングされます。 |
| 以前に作成したユーザーまたはグループの既知のリソースを取得する | セクション 3.4.1 |
| ユーザーまたはグループを照会する |
セクション 3.4.2. 既定では、ユーザーの取得には id、ユーザーのクエリには username と externalId、グループのクエリには displayName が使用されます。 |
| グループ リソースをクエリするときのフィルター excludedAttributes=members | セクション 3.4.2.2 |
| ユーザーの一覧表示とページ番号付けをサポートする | セクション 3.4.2.4. |
ユーザー active=false の論理削除とユーザー active=true の復元を行う |
ユーザーがアクティブかどうかに関係なく、要求でユーザー オブジェクトが返される必要があります。 ユーザーが返されないのは、アプリケーションから完全削除されているときです。 |
| /Schemas エンドポイントをサポートする | セクション 7 スキーマ検出エンドポイントは、さらに多くの属性を検出するために使用されます。 |
| アプリケーションに対する Microsoft Entra ID の認証と認可のために、単一のベアラー トークンを受け入れる。 |
Microsoft Entra ID との互換性を確保するために、SCIM エンドポイントの実装時は次の一般的なガイドラインに従ってください。
全般:
-
idは、すべてのリソースの必須のプロパティです。 リソースを返すすべての応答において、メンバーが 0 のListResponseを除き、各リソースにこのプロパティが含まれるようにする必要があります。 - 送信された値は、送信時と同じ形式で格納する必要があります。 無効な値は、わかりやすいアクション可能なエラー メッセージを付けて拒否する必要があります。 データの変換は、Microsoft Entra ID からのデータと SCIM アプリケーションの格納データの間で行うことはできません。 (例: (55555555555 として送信された電話番号は、+5 (555) 555-5555 として保存または返すことはできません)
- PATCH 応答にリソース全体を含める必要はありません。
- SCIM の構造要素、特に PATCH
op操作値については、大文字と小文字の区別は不要です。セクション 3.5.2 で定義されています。 Microsoft Entra ID は、opの値を Add、 Replace、Remove として出力 します。 - Microsoft Entra ID では、エンドポイントと資格情報が有効であることを確認するため、ランダムなユーザーとグループをフェッチする要求を行います。 これは、 テスト接続 フローの一部としても行われます。
- SCIM エンドポイントで HTTPS をサポートします。
- カスタムの複合属性と複数値属性がサポートされますが、このような場合のデータのプル元となる複雑なデータ構造は、Microsoft Entra ID には多くありません。 名前/値属性は簡単に にマップできますが、3 つ以上のサブ属性を持つ複雑な属性へのデータのフローはサポートされていません。
- 複数値を持つ複合属性の "type" サブ属性の値は一意である必要があります。 たとえば、サブタイプが "work" の 2 つの異なるメール アドレスを使用することはできません。
- すべての応答のヘッダーは、content-Type: application/scim+json である必要があります
リソースの取得:
- クエリ/フィルター要求への応答は常に
ListResponseである必要があります。 - Microsoft Entra では、演算子として
eqとandのみが使用されます。 - リソースを照会できる属性は、アプリケーションで一致する属性として設定する必要があります。 ユーザー プロビジョニング属性マッピングのカスタマイズを参照してください。
/ユーザー：
- エンタイトルメント属性はサポートされていません。
- ユーザーの一意性のために使用される属性が、フィルター選択されたクエリの一部として使用できる必要があります。 (たとえば、userName と emails[type eq "work"] の両方に対してユーザーの一意性が評価される場合、フィルターを持つ /Users に対する GET では、 userName eq "user@contoso.com" クエリと emails[type eq "work"].value eq "user@contoso.com" クエリの両方を許可する必要があります。
/グループ：
- グループは省略可能ですが、SCIM 実装で PATCH 要求がサポートされている場合にのみサポートされます。
- Microsoft Entra ID および SCIM アプリケーションと一致させるには、グループが一意の "displayName" 値を持っている必要があります。 この一意性は、SCIM プロトコルの要件ではありませんが、SCIM エンドポイントを Microsoft Entra ID に統合するための要件です。
/Schemas (スキーマ検出):
- 要求/応答のサンプル
- スキーマ検出は、特定のギャラリー アプリケーションで使用されています。 スキーマ検出は、既存のギャラリー SCIM アプリケーションのスキーマに属性を追加するための唯一の手段です。 スキーマ検出は、現在、ギャラリー以外のカスタム SCIM アプリケーションではサポートされていません。
- 値が存在しない場合は、null 値を送信しないでください。
- プロパティ値はキャメル ケース (例: readWrite) にする必要があります。
- リストの応答を返す必要があります。
- プロビジョニング構成を保存すると、Microsoft Entra プロビジョニング サービスによって /schemas 要求が行われます。 この要求は、プロビジョニングの編集ページを開いたときにも行われます。 その他の検出された属性は、[対象の属性] リストにある属性マッピングでお客様に示されます。 スキーマ検出では、対象の属性が新たに追加されるだけです。 属性は削除されません。
ユーザーのプロビジョニングとプロビジョニング解除
次の図は、アプリケーションの ID ストア内にあるユーザーのライフサイクルを管理するために Microsoft Entra ID から SCIM エンドポイントに送信されるメッセージを示しています。
グループのプロビジョニングとプロビジョニング解除
グループのプロビジョニングとプロビジョニング解除はオプションです。 実装され有効にされている場合、次の図は、アプリケーションの ID ストア内にあるグループのライフサイクルを管理するために Microsoft Entra ID から SCIM エンドポイントに送信されるメッセージを示しています。 それらのメッセージは、次の 2 つの点でユーザーに関するメッセージと異なっています。
- グループを取得する要求では、要求に対する応答の中で提示されるリソースから、members 属性が除外されるように指定しています。
- 参照属性に特定の値があるかどうかを判別する要求は、members 属性に関する要求になります。
次の図は、グループのプロビジョニング解除シーケンスを示しています。
SCIM プロトコル要求と応答
この記事では、Microsoft Entra プロビジョニング サービスによって出力される SCIM 要求の例と、予想される応答の例を示します。 最良の結果を得るには、このような要求をこの形式で処理し、想定される応答を出力するよう、アプリをコーディングしてください。
重要
この例で説明した操作を Microsoft Entra ユーザー プロビジョニング サービスが出力する方法とタイミングについては、「プロビジョニングのしくみ」の「 プロビジョニング サイクル: 初期と増分 」セクション を参照してください。
- Create User (Request / Response)
- ユーザー取得 (リクエスト / 応答)
- クエリでユーザーを取得 する (Request / Response)
- クエリでユーザーを取得する - ゼロの結果 (Request / Response)
- ユーザーの更新 [複数値のプロパティ] (Request / Response)
- ユーザーの更新 [単一値プロパティ] (Request / Response)
- ユーザーの無効化 (要求 / Response)
- ユーザーの削除 (要求 / Response)
- グループの作成 (要求 / Response)
- グループの取得 (要求 / Response)
- DisplayName によるグループ化の取得 (Request / Response)
- グループの更新 [メンバー以外の属性] (Request / Response)
- グループの更新 [メンバーの追加] (要求 / Response)
- グループの更新 [メンバーの削除] (Request / Response)
- グループの削除 (要求 / Response)
ユーザー操作
-
userNameまたはemails[type eq "work"]属性を使用してユーザーにクエリを実行します。
[Create User]
リクエスト
POST /Users
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
"externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"active": true,
"emails": [{
"primary": true,
"type": "work",
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com"
}],
"meta": {
"resourceType": "User"
},
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName"
},
"roles": []
}
[応答]
HTTP/1.1 201 Created
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "48af03ac28ad4fb88478",
"externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName",
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}
ユーザーの取得
リクエスト
GET /Users/5d48a0a8e9f04aa38008
応答 (ユーザー検出)
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "5d48a0a8e9f04aa38008",
"externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName",
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}
リクエスト
GET /Users/5171a35d82074e068ce2
応答 (ユーザーが見つかりません。詳細は必要なく、状態のみです)。
HTTP/1.1 404 が見つかりません
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "404",
"detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}
クエリによるユーザーの取得
リクエスト
GET /Users?filter=userName eq "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
[応答]
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"Resources": [{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "2441309d85324e7793ae",
"externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"familyName": "familyName",
"givenName": "givenName"
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}],
"startIndex": 1,
"itemsPerPage": 20
}
クエリによるユーザーの取得 - 0 件の結果
リクエスト
GET /Users?filter=userName eq "non-existent user"
[応答]
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 0,
"Resources": [],
"startIndex": 1,
"itemsPerPage": 20
}
ユーザーの更新 [複数値のプロパティ]
リクエスト
PATCH /Users/6764549bef60420686bc HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "Replace",
"path": "emails[type eq \"work\"].value",
"value": "updatedEmail@microsoft.com"
},
{
"op": "Replace",
"path": "name.familyName",
"value": "updatedFamilyName"
}
]
}
[応答]
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "6764549bef60420686bc",
"externalId": "6c75de36-30fa-4d2d-a196-6bdcdb6b6539",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"formatted": "givenName updatedFamilyName",
"familyName": "updatedFamilyName",
"givenName": "givenName"
},
"active": true,
"emails": [{
"value": "updatedEmail@microsoft.com",
"type": "work",
"primary": true
}]
}
ユーザーの更新 [単一値のプロパティ]
リクエスト
PATCH /Users/5171a35d82074e068ce2 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Replace",
"path": "userName",
"value": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com"
}]
}
[応答]
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "5171a35d82074e068ce2",
"externalId": "aa1eca08-7179-4eeb-a0be-a519f7e5cd1a",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com",
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName",
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}
ユーザーの無効化
リクエスト
PATCH /Users/5171a35d82074e068ce2 HTTP/1.1
{
"Operations": [
{
"op": "Replace",
"path": "active",
"value": false
}
],
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
]
}
[応答]
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "CEC50F275D83C4530A495FCF@834d0e1e5d8235f90a495fda",
"userName": "deanruiz@testuser.com",
"name": {
"familyName": "Harris",
"givenName": "Larry"
},
"active": false,
"emails": [
{
"value": "gloversuzanne@testuser.com",
"type": "work",
"primary": true
}
],
"addresses": [
{
"country": "ML",
"type": "work",
"primary": true
}
],
"meta": {
"resourceType": "Users",
"location": "/scim/5171a35d82074e068ce2/Users/CEC50F265D83B4530B495FCF@5171a35d82074e068ce2"
}
}
ユーザーの削除
リクエスト
DELETE /Users/5171a35d82074e068ce2 HTTP/1.1
[応答]
HTTP/1.1 204 コンテンツなし
グループ操作
- グループは、空のメンバーのリストで作成されます。
-
displayName属性を使用してグループのクエリを実行します。 - グループ PATCH 要求に更新すると、応答に HTTP 204 No Content が生成されます。 全メンバーのリストを含めて本文を返すことはお勧めできません。
- グループの全メンバーを返すことをサポートする必要はありません。
グループの作成
リクエスト
POST /Groups HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/2.0/Group"],
"externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
"displayName": "displayName",
"meta": {
"resourceType": "Group"
}
}
[応答]
HTTP/1.1 201 Created (作成された)
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "927fa2c08dcb4a7fae9e",
"externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
"meta": {
"resourceType": "Group",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"displayName": "displayName",
"members": []
}
グループの取得
リクエスト
GET /Groups/40734ae655284ad3abcc?excludedAttributes=members HTTP/1.1
[応答]
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "40734ae655284ad3abcc",
"externalId": "60f1bb27-2e1e-402d-bcc4-ec999564a194",
"meta": {
"resourceType": "Group",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"displayName": "displayName",
}
displayName でのグループの取得
リクエスト
GET /Groups?excludedAttributes=members&filter=displayName eq "displayName" HTTP/1.1
[応答]
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"Resources": [{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "8c601452cc934a9ebef9",
"externalId": "0db508eb-91e2-46e4-809c-30dcbda0c685",
"meta": {
"resourceType": "Group",
"created": "2018-03-27T22:02:32.000Z",
"lastModified": "2018-03-27T22:02:32.000Z",
},
"displayName": "displayName",
}],
"startIndex": 1,
"itemsPerPage": 20
}
グループの更新 [非メンバー属性]
リクエスト
PATCH /Groups/fa2ce26709934589afc5 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Replace",
"path": "displayName",
"value": "1879db59-3bdf-4490-ad68-ab880a269474updatedDisplayName"
}]
}
[応答]
HTTP/1.1 204 コンテンツなし
グループの更新 [メンバーの追加]
リクエスト
PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Add",
"path": "members",
"value": [{
"$ref": null,
"value": "f648f8d5ea4e4cd38e9c"
}]
}]
}
[応答]
HTTP/1.1 204 コンテンツなし
グループの更新 [メンバーの削除]
リクエスト
PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Remove",
"path": "members",
"value": [{
"$ref": null,
"value": "f648f8d5ea4e4cd38e9c"
}]
}]
}
[応答]
HTTP/1.1 204 コンテンツなし
グループの削除
リクエスト
DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1
[応答]
HTTP/1.1 204 コンテンツなし
スキーマ検出
スキーマの検出
リクエスト
GET /Schemas
[応答]
HTTP/1.1 200 OK
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"itemsPerPage": 50,
"startIndex": 1,
"totalResults": 3,
"Resources": [
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
"id" : "urn:ietf:params:scim:schemas:core:2.0:User",
"name" : "User",
"description" : "User Account",
"attributes" : [
{
"name" : "userName",
"type" : "string",
"multiValued" : false,
"description" : "Unique identifier for the User, typically
used by the user to directly authenticate to the service provider.
Each User MUST include a non-empty userName value. This identifier
MUST be unique across the service provider's entire set of Users.
REQUIRED.",
"required" : true,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "server"
},
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
}
},
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
"id" : "urn:ietf:params:scim:schemas:core:2.0:Group",
"name" : "Group",
"description" : "Group",
"attributes" : [
{
"name" : "displayName",
"type" : "string",
"multiValued" : false,
"description" : "A human-readable name for the Group.
REQUIRED.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
}
},
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
"id" : "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"name" : "EnterpriseUser",
"description" : "Enterprise User",
"attributes" : [
{
"name" : "employeeNumber",
"type" : "string",
"multiValued" : false,
"description" : "Numeric or alphanumeric identifier assigned
to a person, typically based on order of hire or association with an
organization.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
}
}
]
}
セキュリティ要件
TLS プロトコルのバージョン
許容されるプロトコル のバージョンは TLS 1.2 のみです。 他の SSL/TLS バージョンは許可されていません。
- RSA キーは、2,048 ビット以上である必要があります。
- ECC キーは 256 ビット以上で、承認された楕円曲線を使用して生成されている必要があります
キーの長さ
すべてのサービスでは、十分な長さの暗号化キーを使用して生成された X.509 証明書が使用されている必要があります。
暗号スイート
すべてのサービスは、以下の暗号スイートを、例に示す厳密な順序で使用するように構成する必要があります。 RSA 証明書だけがある場合は、ECDSA 暗号スイートをインストールしても何の影響もありません。
TLS 1.2 暗号スイートの最低条件:
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
IP 範囲
Microsoft Entra プロビジョニング サービスは、現在、 ここに記載されている Microsoft Entra ID の IP 範囲で動作します。
AzureActiveDirectory タグにリストされている IP 範囲を追加し、Microsoft Entra プロビジョニング サービスからアプリケーションにトラフィックを許可できます。 計算されたアドレスには、IP 範囲のリストを注意深く確認する必要があります。 '40.126.25.32' などのアドレスは、IP 範囲の一覧では '40.126.0.0/18' として表されることがあります。 次の API を使用して、IP 範囲の一覧をプログラムで取得することもできます。
また、Microsoft Entra ID は、プライベート ネットワーク (オンプレミス、Azure でホストされている、AWS でホストされているなど) 内のアプリケーションへの接続を提供するエージェント ベースのソリューションもサポートします。 お客様は、プライベート ネットワーク内のサーバーで、受信ポートを開くことなく Microsoft Entra ID への接続を提供する軽量のエージェントをデプロイできます。 詳細については 、こちらをご覧ください。
SCIM エンドポイントを構築する
これでスキーマを設計し、Microsoft Entra SCIM の実装を理解したので、SCIM エンドポイントの開発を開始できます。 最初から開始して完全に独自の実装を構築するのではなく、SCIM コミュニティによって発行された多数のオープンソース SCIM ライブラリを使用できます。
例を含む SCIM エンドポイントを構築する方法のガイダンスについては、「 サンプル SCIM エンドポイントの開発」を参照してください。
Microsoft Entra プロビジョニング チームによって公開されているオープン ソースの .NET Core 参照コード例 は、開発をすぐに開始できるそのようなリソースの 1 つです。 SCIM エンドポイントを構築し、 提供されたサンプル要求/応答を実行してテストします。
注
参照コードは、SCIM エンドポイントのビルドを開始するためのものであり、"現状のまま" 提供されます。コードのビルドと保守に役立つため、コミュニティからの貢献が歓迎されます。
このソリューションは、 Microsoft.SCIM と Microsoft.SCIM.WebHostSample の 2 つのプロジェクトで構成 されています。
Microsoft.SCIM プロジェクトは、SCIM 仕様に準拠する Web サービスのコンポーネントを定義するライブラリです。 これは 、インターフェイス Microsoft.SCIM.IProvider を宣言し、要求はプロバイダーのメソッドの呼び出しに変換されます。これは、ID ストアで動作するようにプログラムされます。
Microsoft.SCIM.WebHostSample プロジェクトは、空のテンプレートに基づく ASP.NET Core Web アプリケーションです。 これにより、サンプル コードをスタンドアロンとしてデプロイし、コンテナーまたはインターネット インフォメーション サービス内でホストすることができます。 また、サンプル ID ストアとしてメモリ内のクラスを保持する Microsoft.SCIM.IProvider インターフェイスも実装します。
public class Startup
{
...
public IMonitor MonitoringBehavior { get; set; }
public IProvider ProviderBehavior { get; set; }
public Startup(IWebHostEnvironment env, IConfiguration configuration)
{
...
this.MonitoringBehavior = new ConsoleMonitor();
this.ProviderBehavior = new InMemoryProvider();
}
...
カスタム SCIM エンドポイントの構築
SCIM エンドポイントには、HTTP アドレスと、ルート証明機関が次のいずれかの名前であるサーバー認証証明書が設定されている必要があります。
- CNNIC
- コモド
- CyberTrust
- DigiCert
- GeoTrust
- GlobalSign
- パパに行く
- VeriSign
- WoSign
- DST ルート CA X3
.NET Core SDK には、開発時に使用される HTTPS 開発証明書が含まれています。 この証明書は、最初の実行エクスペリエンスの一環としてインストールされます。 ASP.NET Core Web アプリケーションの実行方法に応じて、異なるポートがリッスンされます。
- Microsoft.SCIM.WebHostSample:
https://localhost:5001 - IIS Express:
https://localhost:44359
ASP.NET Core の HTTPS の詳細については、次のリンクを使用します。 ASP.NET Core での HTTPS の適用
エンドポイント認証の処理
Microsoft Entra プロビジョニング サービスからの要求には、OAuth 2.0 のベアラー トークンが含まれます。 承認サーバーがベアラー トークンを発行します。 Microsoft Entra ID は、信頼される承認サーバーの一例です。 次のいずれかのトークンを使用するように Microsoft Entra プロビジョニング サービスを構成します。
有効期間が長いベアラー トークン SCIM エンドポイントで Microsoft Entra ID 以外の発行者からの OAuth ベアラー トークンが必要な場合は、必要な OAuth ベアラー トークンをオプションの [シークレット トークン ] フィールドにコピーします。 開発環境では、
/scim/tokenエンドポイントからのテスト トークンを使用できます。 運用環境ではテスト トークンを使用しないでください。Microsoft Entra ベアラー トークン。 [シークレット トークン] フィールドが空白の場合、Microsoft Entra ID には、各要求で Microsoft Entra ID から発行された OAuth ベアラー トークンが含まれます。 ID プロバイダーとして Microsoft Entra ID を使用するアプリは、この Microsoft Entra ID によって発行されたトークンを検証できます。
- 要求を受け取るアプリケーションは、トークンの発行元が想定される Microsoft Entra テナントとしての Microsoft Entra ID であることを検証する必要があります。
- トークンの発行者は、
iss要求によって識別されます。 たとえば、"iss":"https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/"のようにします。 この例では、要求値のベース アドレスhttps://sts.windows.net、発行者として Microsoft Entra ID を識別しますが、相対アドレス セグメント aaaabbbb-0000-cccc-1111-dddd2222eeee は、トークンが発行された Microsoft Entra テナントの一意識別子です。 - トークンの対象ユーザーは、ギャラリー内のアプリケーションのアプリケーション ID です 。 単一のテナントに登録されているアプリケーションは、同じ
iss要求を SCIM 要求と共に受信します。 すべてのカスタム アプリのアプリケーション ID は 8adf8e6e-67b2-4cf2-a259-e3dc5476c621 です。 Microsoft Entra ID によって生成されたトークンは、テストにのみ使用する必要があります。 運用環境では使用しないでください。
このサンプル コードでは、要求は Microsoft.AspNetCore.Authentication.JwtBearer パッケージを使用して認証されます。 次のコードは、すべてのサービスのエンドポイントに対する要求が、Microsoft Entra ID が指定テナントに発行したベアラー トークンを使用して認証されるようにします。
public void ConfigureServices(IServiceCollection services)
{
if (_env.IsDevelopment())
{
...
}
else
{
services.AddAuthentication(options =>
{
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
options.Authority = " https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";
options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
...
});
}
...
}
public void Configure(IApplicationBuilder app)
{
...
app.UseAuthentication();
app.UseAuthorization();
...
}
サンプル コードは ASP.NET Core 環境を使用し、開発段階で認証オプションを変更して自己署名トークンを使用できるようにします。
ASP.NET Core の複数の環境の詳細については、「 ASP.NET Core で複数の環境を使用する」を参照してください。
次のコードでは、あらゆるサービスのエンドポイントに対する要求が、カスタム キーを使用して署名されたベアラー トークンを使用して認証されるようになります:
public void ConfigureServices(IServiceCollection services)
{
if (_env.IsDevelopment())
{
services.AddAuthentication(options =>
{
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
options.TokenValidationParameters =
new TokenValidationParameters
{
ValidateIssuer = false,
ValidateAudience = false,
ValidateLifetime = false,
ValidateIssuerSigningKey = false,
ValidIssuer = "Microsoft.Security.Bearer",
ValidAudience = "Microsoft.Security.Bearer",
IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"))
};
});
}
...
トークン コントローラーに GET 要求を送信して有効なベアラー トークンを取得します。 GenerateJSONWebToken メソッドは、開発用に構成されたパラメーターと一致するトークンを作成します。
private string GenerateJSONWebToken()
{
// Create token key
SymmetricSecurityKey securityKey =
new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"));
SigningCredentials credentials =
new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);
// Set token expiration
DateTime startTime = DateTime.UtcNow;
DateTime expiryTime = startTime.AddMinutes(120);
// Generate the token
JwtSecurityToken token =
new JwtSecurityToken(
"Microsoft.Security.Bearer",
"Microsoft.Security.Bearer",
null,
notBefore: startTime,
expires: expiryTime,
signingCredentials: credentials);
string result = new JwtSecurityTokenHandler().WriteToken(token);
return result;
}
ユーザーのプロビジョニングとプロビジョニング解除の処理
例 1.一致するユーザーのサービスに対してクエリを実行する
Microsoft Entra ID は、Microsoft Entra ID 内のユーザーの mailNickname 属性値に一致する externalId 属性値を持つユーザーをサービスに照会します。 クエリは次の例のようなハイパーテキスト転送プロトコル (HTTP) 要求として表現されます。jyoung は Microsoft Entra ID 内のユーザーの mailNickname 例です。
注
これは一例です。 すべてのユーザーに mailNickname 属性があるわけではありません。また、ユーザーが持つ値はディレクトリ内で一意ではない場合もあります。 また、照合に使用される属性 (この場合は externalId) は 、Microsoft Entra 属性マッピングで構成できます。
GET https://.../scim/Users?filter=externalId eq jyoung HTTP/1.1
Authorization: Bearer ...
このサンプル コードでは、要求はサービスのプロバイダーの QueryAsync メソッドへの呼び出しに変換されます。 このメソッドのシグネチャを次に示します。
// System.Threading.Tasks.Tasks is defined in mscorlib.dll.
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.Resource is defined in
// Microsoft.SCIM.Schemas.
// Microsoft.SCIM.IQueryParameters is defined in
// Microsoft.SCIM.Protocol.
Task<Resource[]> QueryAsync(IRequest<IQueryParameters> request);
externalId 属性に特定の値を持つユーザーのサンプル クエリでは、QueryAsync メソッドに渡される引数の値は次のようになります。
- parameters.AlternateFilters.Count:1
- パラメーター・AlternateFilters・ElementAt(0)・AttributePath: "externalId"
- parameters.AlternateFilters.ElementAt(0).ComparisonOperator:ComparisonOperator.Equals
- parameters.AlternateFilter.ElementAt(0).ComparisonValue: "jyoung"
例 2.ユーザーをプロビジョニングする
ユーザーの mailNickname 属性値に一致する externalId 属性値を持つユーザーを SCIM エンドポイントに照会したときに、応答でユーザーが返されなかった場合、Microsoft Entra ID は、Microsoft Entra ID 内のユーザーに対応するユーザーをプロビジョニングするようにサービスに要求します。 このような要求の例を次に示します。
POST https://.../scim/Users HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
"schemas":
[
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0User"],
"externalId":"jyoung",
"userName":"jyoung@testuser.com",
"active":true,
"addresses":null,
"displayName":"Joy Young",
"emails": [
{
"type":"work",
"value":"jyoung@Contoso.com",
"primary":true}],
"meta": {
"resourceType":"User"},
"name":{
"familyName":"Young",
"givenName":"Joy"},
"phoneNumbers":null,
"preferredLanguage":null,
"title":null,
"department":null,
"manager":null}
このサンプル コードでは、要求はサービスのプロバイダーの CreateAsync メソッドへの呼び出しに変換されます。 このメソッドのシグネチャを次に示します。
// System.Threading.Tasks.Tasks is defined in mscorlib.dll.
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.Resource is defined in
// Microsoft.SCIM.Schemas.
Task<Resource> CreateAsync(IRequest<Resource> request);
ユーザー プロビジョニングの要求では、リソース引数の値は Microsoft.SCIM.Core2EnterpriseUser クラスのインスタンスです。 このクラスは、Microsoft.SCIM.Schemas ライブラリで定義されています。 ユーザーをプロビジョニングする要求が成功すると、メソッドの実装は Microsoft.SCIM.Core2EnterpriseUser クラスのインスタンスを返すことが予想されます。
Identifier プロパティの値に新たにプロビジョニングされたユーザーの一意識別子が設定されます。
例 3.ユーザーの現在の状態を照会する
Microsoft Entra ID では、次のような要求により、指定されたユーザーの現在の状態をサービスに要求します。
GET ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
このサンプル コードでは、要求はサービスのプロバイダーの RetrieveAsync メソッドへの呼び出しに変換されます。 このメソッドのシグネチャを次に示します。
// System.Threading.Tasks.Tasks is defined in mscorlib.dll.
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.Resource and
// Microsoft.SCIM.IResourceRetrievalParameters
// are defined in Microsoft.SCIM.Schemas
Task<Resource> RetrieveAsync(IRequest<IResourceRetrievalParameters> request);
ユーザーの現在の状態を取得する要求の例では、parameters 引数の値として指定されたオブジェクトのプロパティ値は次のようになります。
- 識別子: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
- スキーマ識別子:
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
例 4.更新する参照属性の値を照会する
Microsoft Entra ID は、ID ストア内の現在の属性値を、更新する前に確認します。 ただし、ユーザーに対して最初に確認されるのはマネージャー属性のみです。 ユーザー オブジェクトの マネージャー 属性に特定の値があるかどうかを判別する要求の例を次に示します。このサンプル コードでは、要求はサービスのプロバイダーの QueryAsync メソッドへの呼び出しに変換されます。 parameters 引数の値として指定されたオブジェクトのプロパティ値は次のようになります。
- parameters.AlternateFilters.Count:2
- parameters.AlternateFilters.ElementAt(x).AttributePath:"ID"
- parameters.AlternateFilters.ElementAt(x).ComparisonOperator:ComparisonOperator.Equals
- parameters.AlternateFilter.ElementAt(x).ComparisonValue: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
- パラメーター。AlternateFilters.ElementAt(y)。AttributePath: "manager"
- parameters.AlternateFilters.ElementAt(y).ComparisonOperator:ComparisonOperator.Equals
- パラメーター。AlternateFilter.ElementAt(y)。ComparisonValue: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
- parameters.RequestedAttributePaths.ElementAt(0):"ID"
- パラメーター SchemaIdentifier:
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
インデックス x の値として 0 を指定し、インデックス y の値として 1 を指定することができます。 または、x の値をとして 1 を指定し、y の値として 0 を指定することもできます。 これはフィルター クエリ パラメーターの式の順序によって異なります。
例 5.ユーザーを更新するために Microsoft Entra ID から SCIM エンドポイントに要求する
次に Microsoft Entra ID から SCIM エンドポイントにユーザーの更新を要求する例を示します。
PATCH ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
"schemas":
[
"urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":
[
{
"op":"Add",
"path":"manager",
"value":
[
{
"$ref":"http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"value":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee"}]}]}
このサンプル コードでは、要求はサービスのプロバイダーの UpdateAsync メソッドへの呼び出しに変換されます。 このメソッドのシグネチャを次に示します。
// System.Threading.Tasks.Tasks and
// System.Collections.Generic.IReadOnlyCollection<T> // are defined in mscorlib.dll.
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.IPatch,
// is defined in Microsoft.SCIM.Protocol.
Task UpdateAsync(IRequest<IPatch> request);
ユーザーを更新する要求の例では、patch 引数の値として指定されたオブジェクトのプロパティ値は次のようになります。
| 引数 | 価値 |
|---|---|
ResourceIdentifier.Identifier |
"a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1e1" |
ResourceIdentifier.SchemaIdentifier |
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
(PatchRequest as PatchRequest2).Operations.Count |
1 |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).OperationName |
OperationName.Add |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Path.AttributePath |
マネージャー |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count |
1 |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference |
http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value |
00aa00aa-bb11-cc22-dd33-44ee44ee44ee |
例 6.ユーザーのプロビジョニング解除
SCIM エンドポイントによってアクセスされる ID ストアからユーザーのプロビジョニングを解除するために、Microsoft Entra ID は次のような要求を送信します。
DELETE ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
このサンプル コードでは、要求はサービスのプロバイダーの DeleteAsync メソッドへの呼び出しに変換されます。 このメソッドのシグネチャを次に示します。
// System.Threading.Tasks.Tasks is defined in mscorlib.dll.
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.IResourceIdentifier,
// is defined in Microsoft.SCIM.Protocol.
Task DeleteAsync(IRequest<IResourceIdentifier> request);
ユーザーのプロビジョニングを解除する要求の例では、resourceIdentifier 引数の値として指定されたオブジェクトのプロパティ値は次のようになります。
- ResourceIdentifier.Identifier: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
- ResourceIdentifier.SchemaIdentifier:
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
SCIM エンドポイントを Microsoft Entra プロビジョニング サービスと統合する
割り当てられたユーザーとグループを 、SCIM 2.0 プロトコルの特定のプロファイルを実装するアプリケーションに自動的にプロビジョニングするように Microsoft Entra ID を構成できます。 プロファイルの詳細については、「 Microsoft Entra SCIM の実装について」を参照してください。
これらの要件との互換性に関する記述については、アプリケーション プロバイダー、またはアプリケーション プロバイダーのドキュメントを確認してください。
重要
Microsoft Entra SCIM 実装は、Microsoft Entra とターゲット アプリケーション間でユーザーを常に同期するように設計された Microsoft Entra ユーザー プロビジョニング サービスの上に構築され、固有の標準操作セットを実装しています。 Microsoft Entra プロビジョニング サービスの動作を理解するには、これらの動作を把握しておくことが重要です。 詳細については、「 プロビジョニングサイクル: プロビジョニングのしくみ」の「初期および増分 」セクション を参照してください。
作業の開始
この記事で説明した SCIM プロファイルをサポートするアプリケーションは、Microsoft Entra ID アプリケーション ギャラリーの "ギャラリー以外のアプリケーション" 機能を使用して Microsoft Entra ID に接続できます。 接続すると、Microsoft Entra ID によって同期プロセスが実行されます。 このプロセスは 40 分ごとに実行されます。 このプロセスでは、割り当て済みのユーザーとグループをアプリケーションの SCIM エンドポイントに照会し、割り当ての詳細に従ってユーザーとグループを作成または変更します。
SCIM をサポートするアプリケーションを接続するには:
Microsoft Entra 管理センターに、少なくともアプリケーション管理者としてサインインします。
Entra ID>Enterprise アプリに移動します。
ギャラリーから追加されたアプリを含む、構成済みのすべてのアプリの一覧が表示されます。
[ + 新しいアプリケーション>+ 独自のアプリケーションを作成する] を選択します。
アプリケーションの名前を入力し、[ギャラリーに見つからない他のアプリケーションを統合する] オプションを選択し、[ 追加] を選択してアプリ オブジェクトを作成します。 新しいアプリがエンタープライズ アプリケーションの一覧に追加され、そのアプリの管理画面が開きます。
次のスクリーンショットは、Microsoft Entra アプリケーション ギャラリーを示しています。
アプリの管理画面で、左側のパネルで [ プロビジョニング ] を選択します。
[ + 新しい構成] を選択します。
[ テナント URL ] フィールドに、アプリケーションの SCIM エンドポイントの URL を入力します。 例:
https://api.contoso.com/scim/SCIM エンドポイントで Microsoft Entra ID 以外の発行者からの OAuth ベアラー トークンが必要な場合は、必要な OAuth ベアラー トークンをオプションの [シークレット トークン ] フィールドにコピーします。 このフィールドを空白のままにすると、Microsoft Entra ID では各要求に Microsoft Entra ID を発行元とする OAuth ベアラー トークンを含めます。 ID プロバイダーとして Microsoft Entra ID を使用するアプリは、この Microsoft Entra ID によって発行されたトークンを検証できます。
注
このフィールドを空白のままにし、Microsoft Entra ID によって生成されたトークンに依存することはお勧 めしません 。 このオプションは、主にテスト目的で使用できます。
Microsoft Entra ID で SCIM エンドポイントへの接続を試行するには、[ 接続のテスト ] を選択します。 試行に失敗した場合は、エラー情報が表示されます。
注
テスト接続 では、Microsoft Entra 構成で選択された照合プロパティとしてランダム GUID を使用して、存在しないユーザーの SCIM エンドポイントに対してクエリを実行します。 想定される適切な応答は、HTTP 200 OK と空の SCIM ListResponse メッセージです。
アプリケーションへの接続が成功した場合は、[ 作成 ] を選択してプロビジョニング ジョブを作成します。
割り当てられたユーザーとグループのみを同期する場合 (推奨)、[ ユーザーとグループ ] タブを選択します。次に、同期するユーザーまたはグループを割り当てます。
左側のパネルで [属性マッピング ] を選択します。
属性マッピングには、ユーザー オブジェクト用とグループ オブジェクト用の 2 つの選択可能なセットがあります。 Microsoft Entra ID からアプリに同期されている属性を確認するには、それぞれを選択します。 [照合プロパティ] として選択されている属性は、更新操作のためにアプリ内のユーザーとグループを照合するために使用されます。 [ 保存] を 選択して変更をコミットします。 必要に応じて [グループ] マッピングを無効にすることで、グループ オブジェクトの同期を無効にできます。
左側のパネルで [オンデマンドのプロビジョニング] を選択します。 プロビジョニングのスコープ内にあるユーザーを検索し、オンデマンドでプロビジョニングします。 他のユーザーとプロビジョニングのテストを繰り返します。
構成が完了したら、左側のパネルで [概要 ] を選択します。
[プロパティ] を選択します。
鉛筆を選択してプロパティを編集します。 通知メールを有効にし、検疫メールを受信する電子メールを提供します。 誤削除防止を有効にします。 [ 適用 ] をクリックして変更を保存します。
[ プロビジョニングの開始] を選択して、Microsoft Entra プロビジョニング サービスを開始します。
最初のサイクルが開始されたら、左側のパネルで [プロビジョニング ログ ] を選択して進行状況を監視し、アプリでプロビジョニング サービスによって実行されたすべてのアクションが表示されます。 Microsoft Entra プロビジョニング ログを読み取る方法の詳細については、「 自動ユーザー アカウント プロビジョニングに関するレポート」を参照してください。
注
初期サイクルは、サービスが実行されている限り約 40 分ごとに実行される以降の同期よりも、実行に時間がかかります。
Microsoft Entra アプリケーション ギャラリーにアプリケーションを発行する
複数のテナントによって使用されるアプリケーションを作成する場合は、Microsoft Entra アプリケーション ギャラリーで使用可能にできます。 組織で簡単にアプリケーションを見つけて、プロビジョニングを構成することができます。 簡単に、Microsoft Entra ギャラリーにアプリを発行し、他のユーザーがプロビジョニングできるようにすることができます。 手順については、こちらをご覧ください。 Microsoft はお客様と協力して、アプリケーションをギャラリーに統合し、エンドポイントをテストし、顧客向けのオンボード ドキュメント をリリースします。
ギャラリーのオンボードのチェックリスト
アプリケーションを迅速にオンボードし、スムーズなデプロイ エクスペリエンスを顧客に提供するために、チェックリストを使用します。 ギャラリーにオンボードする際に、ご自身から情報が収集されます。
- SCIM 2.0 ユーザーおよびグループ エンドポイントをサポートする (1 つだけが必要ですが、両方が推奨されます)
- ユーザーとグループが遅延なく確実にプロビジョニングされ、プロビジョニング解除されるよう、テナントあたり、少なくとも毎秒 25 件の要求をサポートする (必須)
- 顧客のギャラリー オンボード後のガイドを行うエンジニアリングとサポートの連絡先を確立する (必須)
- アプリケーションの 3 つの無期限のテスト資格情報 (必須)
- 例に示すように、OAuth 承認コードの付与または有効期間が長いトークンをサポートする (必須)
- OIDC アプリには、少なくとも 1 つのロール (カスタムまたは既定) が定義されている必要があります
- 顧客のギャラリー オンボード後のサポートを行うエンジニアリングとサポートの連絡先を確立する (必須)
- スキーマ検出のサポート (必須)
- 1 つの PATCH で複数のグループ メンバーシップの更新をサポートする
- SCIM エンドポイントを公開文書化する
アプリケーション ギャラリーでプロビジョニング コネクタを認可する
SCIM 仕様では、SCIM 固有の認証と認可のスキームは定義されておらず、既存の業界標準の使用に依存しています。
| 承認方法 | 長所 | 短所 | サポート |
|---|---|---|---|
| ユーザー名とパスワード (推奨されないか、Microsoft Entra ID でサポートされていません) | 簡単に実装できます | 不安定 - あなたのパスワードに意味はありません | 新しいギャラリー アプリまたはギャラリー外のアプリではサポートされません。 |
| 有効期間が長いベアラー トークン | 有効期間が長いトークンでは、ユーザーが存在している必要はありません。 プロビジョニングを設定する場合、管理者はこれらを簡単に使用できます。 | 有効期間が長いトークンは、メールのようにセキュリティで保護されていない方法を使用しないと、管理者と共有するのが困難です。 | ギャラリー アプリとギャラリー以外のアプリでサポートされます。 |
| OAuth 認証コードの付与 | アクセス トークンの有効期間はパスワードよりも短く、有効期間が長いベアラー トークンにはない自動更新メカニズムがあります。 初期承認中に実際のユーザーが存在する必要があり、アカウンタビリティのレベルを追加します。 | ユーザーが存在している必要があります。 ユーザーが組織からいなくなる場合、トークンは無効になり、承認を再度完了する必要があります。 | ギャラリー アプリでサポートされていますが、ギャラリー以外のアプリではサポートされていません。 ただし、短期的なテストのために、UI のアクセス トークンをシークレット トークンとして提供することができます。 ギャラリー アプリに対する構成可能な認証 URL またはトークン URL のサポートに加え、ギャラリー以外での OAuth コードの付与に対するサポートもバックログに入っています。 |
| OAuth クライアント資格情報の付与 | アクセス トークンの有効期間はパスワードよりも短く、有効期間が長いベアラー トークンにはない自動更新メカニズムがあります。 承認コードの付与とクライアント資格情報の付与の両方で、同じ種類のアクセス トークンが作成されるため、これらの方法間の移動は API に対して透過的です。 プロビジョニングは自動化することができ、ユーザーの介入なしに新しいトークンを自動的に要求することができます。 | ギャラリー アプリでサポートされていますが、ギャラリー以外のアプリではサポートされていません。 ただし、短期的なテストのために、UI のアクセス トークンをシークレット トークンとして提供することができます。 ギャラリー以外での OAuth クライアント資格情報の付与に対するサポートはバックログに入っています。 |
注
Microsoft Entra プロビジョニング構成のカスタム アプリ UI では、トークン フィールドを空白のままにすることはお勧めしません。 生成されたトークンは、主にテスト目的で使用できます。
OAuth コード付与フロー
プロビジョニング サービスは 承認コードの付与 をサポートしており、ギャラリーでアプリを発行するための要求を送信した後、Microsoft のチームが協力して次の情報を収集します。
承認 URL。ユーザー エージェント リダイレクトを介してリソース所有者から承認を取得するためのクライアントによる URL。 ユーザーは、アクセスを承認するためにこの URL にリダイレクトされます。
トークン交換 URL。通常はクライアント認証を使用して、アクセス トークンの承認許可を交換するためのクライアントによる URL。
クライアント ID は、承認サーバーが登録済みクライアントにクライアント識別子を発行します。これは、クライアントが提供する登録情報を表す一意の文字列です。 クライアント識別子はシークレットではありません。リソース所有者に公開され、クライアント認証に単独で使用 することはできません 。
クライアント シークレット。承認サーバーによって生成されるシークレット。承認サーバーのみが認識する一意の値である必要があります。
注
現在、承認 URL とトークン交換 URL はテナントごとに構成できません。
注
OAuth v1 は、クライアント シークレットの露出が原因でサポートされていません。 OAuth v2 はサポートされています。
OAuth コード付与フローを使用する場合は、プロビジョニング インスタンスを設定するときに、各顧客が独自のクライアント ID とクライアント シークレットを送信するモデルをサポートする必要があります。 1 つのアプリ全体のクライアント ID とクライアント シークレットのペアはサポートされていません。
OAuth コード付与フローをセットアップする方法
Microsoft Entra 管理センターに、少なくともアプリケーション管理者としてサインインします。
Entra ID>Enterprise apps>Application>Provisioning に移動し、[承認] を選択します。
Microsoft Entra 管理センターに、少なくともアプリケーション管理者としてサインインします。
Entra ID>エンタープライズ アプリを参照します。
アプリケーションを選択し、[ プロビジョニング] に移動します。
[ 承認] を選択します。
ユーザーは承認 URL (サード パーティのアプリのサインイン ページ) にリダイレクトされます。
管理者は、サード パーティのアプリケーションに資格情報を提供します。
サード パーティのアプリによってユーザーがリダイレクトし戻され、付与コードが提供されます
プロビジョニング サービスによって、トークン URL が呼び出され、付与コードが提供されます。 サード パーティのアプリケーションから、アクセス トークン、更新トークン、有効期限が含まれた応答が返されます。
プロビジョニング サイクルが開始されると、サービスによって現在のアクセス トークンが有効かどうかが確認され、必要に応じて新しいトークンと交換されます。 アクセス トークンは、アプリに対して行われた各要求で提供され、要求の有効性は各要求の前に確認されます。
注
ギャラリー以外のアプリケーションで OAuth を設定することはできませんが、認可サーバーからアクセス トークンを手動で生成し、ギャラリー以外のアプリケーションにシークレット トークンとして入力することができます。 これにより、OAuth コード付与がサポートされるアプリ ギャラリーにオンボードする前に、SCIM サーバーと Microsoft Entra プロビジョニング サービスとの互換性を確認できます。
有効期間が長い OAuth ベアラー トークン: アプリケーションが OAuth 承認コード付与フローをサポートしていない場合は、代わりに、管理者がプロビジョニング統合の設定に使用できる有効期間の長い OAuth ベアラー トークンを生成します。 トークンは永続的である必要があります。そうしないと、トークンの有効期限が切れるとプロビジョニング ジョブが 検疫 されます。
その他の認証方法と承認方法については、 UserVoice でお知らせください。
ギャラリーの Go-To-Market Launch チェックリスト
共同統合の認識と需要を促進するために、既存のドキュメントを更新し、お使いのマーケティング チャネルにおける統合を拡充することをお勧めします。 Launch をサポートするために、次のチェックリストを完了することをお勧めします。
- 販売チームとカスタマー サポート チームが統合の機能を認識し、準備し、それについて説明できるようにします。 チームに概要を伝え、FAQ を提供し、統合を販売資料に含めます。
- 共同統合、利点、および開始方法について説明するブログ投稿やプレス リリースを作成します。 例: Imprivata と Microsoft Entra Press Release
- X、Facebook、LinkedIn などのソーシャル メディアを活用し、顧客の統合を促します。 当社が投稿をリツイートできるように、必ず @Microsoft Entra ID を含めてください。 例: Imprivata X Post
- マーケティングのページや Web サイト (統合ページ、パートナーのページ、価格ページなど) を作成または更新し、共同統合を利用できる時期を含めてください。 例: Pingboard 統合ページ、 Smartsheet 統合ページ、 Monday.com 価格ページ
- 顧客がどのように開始できるかに関するヘルプ センターの記事またはテクニカル ドキュメントを作成します。 例: Envoy + Microsoft Entra 統合。
- 顧客とのコミュニケーション (月次のニュースレター、メールによるキャンペーン、製品のリリース ノート) を通じて、新しい統合を顧客に通知します。