チュートリアル: Microsoft Entra ID の SCIM エンドポイントにプロビジョニングの開発と計画
アプリケーション開発者はクロスドメイン 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) ライブラリとコード サンプルを使用してエンドポイントを構築します。 これらのサンプルは参考とテストのみを目的としています。実稼働アプリの依存関係として使用することはお勧めしません。
Microsoft Entra プロビジョニング サービスとSCIM エンドポイントを統合します。 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 属性 |
|---|---|---|
| loginName | userName | userPrincipalName |
| firstName | name.givenName | givenName |
| lastName | name.familyName | surName |
| workMail | emails[type eq "work"].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 の属性も含まれています。
これによって /User と /Group を分類し、Microsoft Entra ID で既定のユーザー属性を SCIM RFC にマッピングできるようになります。「Microsoft Entra ID と SCIM エンドポイントの間でカスタマイズされた属性がマッピングされる方法」を参照してください。
次のテーブルには、ユーザー属性の例がリストされています。
| Microsoft Entra ユーザー | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
|---|---|
| IsSoftDeleted | アクティブ |
| 部署 | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department |
| displayName | displayName |
| employeeId | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber |
| Facsimile-TelephoneNumber | phoneNumbers[type eq "fax"].value |
| givenName | name.givenName |
| jobTitle | タイトル |
| メール | emails[type eq "work"].value |
| mailNickname | externalId |
| 管理者 | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager |
| モバイル | phoneNumbers[type eq "mobile"].value |
| postalCode | addresses[type eq "work"].postalCode |
| プロキシ アドレス | emails[type eq "other"].Value |
| physical-Delivery-OfficeName | addresses[type eq "other"].Formatted |
| streetAddress | addresses[type eq "work"].streetAddress |
| surname | name.familyName |
| telephone-Number | phoneNumbers[type eq "work"].value |
| user-PrincipalName | userName |
次のテーブルには、グループ属性の例がリストされています。
| Microsoft Entra グループ | urn:ietf:params:scim:schemas:core:2.0:Group |
|---|---|
| displayName | displayName |
| メンバー | メンバー |
| objectId | externalId |
ノート
ユーザーとグループの両方をサポートする必要はありません。ここに記載されているすべての属性をサポートする必要もありません。これはあくまで参考として、Microsoft Entra ID の属性が頻繁に SCIM プロトコルでプロパティにマッピングされる方法を示したものです。
SCIM RFC でいくつかのエンドポイントが定義されています。 /User エンドポイントで開始してそこから展開できます。 次のテーブルには、いくつかの SCIM エンドポイントがリストされています。
| エンドポイント | 説明 |
|---|---|
| /User | ユーザー オブジェクトに CRUD 操作を実行します。 |
| /Group | グループ オブジェクトに CRUD 操作を実行します。 |
| /Schemas | 各クライアントとサービス プロバイダーでサポートされている一連の属性は、異なる場合があります。 あるサービス プロバイダーには name、title、emails が含まれる一方、別のサービス プロバイダーには name、title、phoneNumbers が使用される場合があります。 スキーマ エンドポイントは、サポートされている属性を検出できるようにします。 |
| /Bulk | 一括操作を使用すると、1 回の操作でリソース オブジェクトの大きなコレクションに対して操作を実行できます (たとえば、大きなグループのメンバーシップの更新)。 |
| /ServiceProviderConfig | サポートされているリソースや認証方法など、サポートされている SCIM 基準の機能についての詳細を提示します。 |
| /ResourceTypes | 各リソースに関するメタデータを指定します。 |
ノート
カスタム属性をサポートするか、スキーマが頻繁に変更される場合、/Schemas エンドポイントを使用してください。これにより、クライアントが最新のスキーマを自動的に取得できます。 /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 の認証と認可のために 1 つのベアラー トークンを承諾します。 |
SCIM エンドポイントを実装して Microsoft Entra ID との互換性を確保するとき、次の一般的なガイドラインに従ってください。
全般
idは、すべてのリソースの必須プロパティです。 リソースを返すすべての応答は、要素が 0 のListResponseを除き、各リソースにこのプロパティが含まれることを確認する必要があります。- 送信された値は、送信時と同じ形式で格納する必要があります。 無効な値は、わかりやすくてアクション可能なエラー メッセージを付けて拒否する必要があります。 データの変換は、Microsoft Entra ID のデータと SCIM アプリケーションに格納されたデータの間で行うことはできません。 (たとえば、 55555555555 として送信された電話番号は、+5 (555) 555-5555 として保存または返すことはできません)
- PATCH 応答にリソース全体を含める必要はありません。
- セクション 3.5.2 で定義されているとおり、特に PATCH
op操作値の場合、SCIM の構造要素に対して大文字と小文字を区別した一致を要求しないでください。 Microsoft Entra ID は、opの値を追加、置き換え、削除削除 として出力します。 - エンドポイントと認証情報が有効であることを確認するため、Microsoft Entra ID はランダムなユーザーとグループをフェッチする要求を行います。 テスト接続フローの一部としても行われます。
- SCIM エンドポイントで HTTPS をサポートします。
- カスタムの複合属性と複数値属性がサポートされますが、はこのような場合、Microsoft Entra ID にはデータのプル元となる複雑なデータ構造が多く存在しません。 名前/値の属性は簡単にマッピングできますが、3 つ以上のサブ属性で複雑な属性へのデータの流れはサポートされていません。
- 複数値を持つ複合属性の "type" サブ属性の値は一意である必要があります。 たとえば、"work" サブタイプには 2 つの異なるメール アドレスを使用することはできません。
- すべての応答のヘッダーは、application/scim+json のコンテンツ タイプである必要があります
リソースの取得
- クエリ/フィルター要求への応答は常に
ListResponseである必要があります。 - Microsoft Entra は、
eqとandの演算子のみを使用します。 - リソースのクエリできる属性は、アプリケーション上で照合属性として設定する必要があります。「ユーザー プロビジョニング属性マッピングのカスタマイズ」を参照してください。
/Users:
- エンタイトルメント属性はサポートされていません。
- ユーザーの一意性のために使用される属性は、フィルター処理されたクエリの一部として使用できる必要があります。 (たとえば、ユーザーの一意性が、「userName」と「emails[type eq "work"]」の両方で評価される場合、フィルターを使用した「GET to /Users」は、「userName eq "user@contoso.com"」クエリと「emails[type eq "work"].value eq "user@contoso.com"」クエリの両方を許可する必要があります。
/Groups:
- グループはオプションですが、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 つの点でユーザーのメッセージとは異なっています。
- グループを取得する要求では、要求に対する応答で提示されるリソースから、メンバー属性が除外されるように指定しています。
- 参照属性に特定の値があるかどうかを判別する要求は、メンバー属性に関する要求です。
次の図では、グループのプロビジョニング解除シーケンスが示されています。
SCIM プロトコルの要求と応答
この記事では、Microsoft Entra プロビジョニング サービスによって出力される SCIM 要求の例、ならびに予想される応答の例について説明します。 最良の結果を得るには、アプリをコーディングし、これらの要求をこの形式で処理して予想される応答を出力します。
重要
Microsoft Entra ユーザー プロビジョニング サービスが例で示す操作を出力する方法とタイミングの詳細については、「プロビジョニングの仕組み」の「プロビジョニング サイクル: 初回と増分」セクションを参照してください。
- ユーザーの作成 (要求 / 応答)
- ユーザーの取得 (要求 / 応答)
- クエリでユーザーの取得 (要求 / 応答)
- クエリでユーザーの取得 - 0 件の結果 (要求 / 応答)
- ユーザーの更新 [複数値のプロパティ] (要求 / 応答)
- ユーザーの更新 [単一値のプロパティ] (要求 / 応答)
- ユーザーの無効化 (要求 / 応答)
- ユーザーの削除 (要求 / 応答)
- グループの作成 (要求 / 応答)
- グループの取得 (要求 / 応答)
- displayName でグループの取得 (要求 / 応答)
- グループの更新 [非メンバー属性] (要求 / 応答)
- グループの更新 [メンバーの追加] (要求 / 応答)
- グループの更新 [メンバーの削除] (要求 / 応答)
- グループの削除 (要求 / 応答)
ユーザー操作
userNameまたはemails[type eq "work"]属性を使用してユーザーにクエリを実行します。
ユーザーの作成
要求
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 No Content
グループの操作
- グループは、空のメンバー リストで作成されます。
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 No Content
グループの更新 [メンバーの追加]
要求
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 No Content
グループの更新 [メンバーの削除]
要求
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 No Content
グループの削除
要求
DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1
応答
HTTP/1.1 204 No Content
スキーマ検出
スキーマの検出
要求
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 アプリケーションです。 サンプル コードをスタンドアロンとして展開し、コンテナーまたはインターネット インフォメーション サービス内でホストすることができます。 Microsoft.SCIM.IProvider インターフェイスも実装し、クラスをサンプル ID ストアとしてメモリに保持します。
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
- Comodo
- CyberTrust
- DigiCert
- GeoTrust
- GlobalSign
- Go Daddy
- VeriSign
- WoSign
- DST Root 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 です。 1 つのテナントで登録されているアプリケーションは、同じ
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
- parameters.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);
要求の例では、ユーザーの現在の状態を取得するため、パラメーター引数の値として指定されたオブジェクトのプロパティ値は次のとおりです。
- 識別子: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
- SchemaIdentifier:
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
例 4. 更新する参照属性の値にクエリ実行
Microsoft Entra ID は、ID ストアの現在の属性値を更新する前に確認します。 ただし、ユーザーに対してはマネージャー属性のみが最初に確認されます。 次の内容は、ユーザー オブジェクトの マネージャー 属性に特定の値があるかどうかを判別する要求の例です。サンプル コードでは、要求はサービス プロバイダーの QueryAsync メソッドへの呼び出しに変換されます。 パラメーター引数の値として指定されたオブジェクトのプロパティ値は次のとおりです。
- 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"
- parameters.AlternateFilters.ElementAt(y).AttributePath: "manager"
- parameters.AlternateFilters.ElementAt(y).ComparisonOperator: ComparisonOperator.Equals
- parameters.AlternateFilter.ElementAt(y).ComparisonValue: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
- parameters.RequestedAttributePaths.ElementAt(0): "ID"
- parameters.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-e1e1e1e1e1e1" |
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 プロビジョニング サービスと統合
Microsoft Entra ID は、割り当てられたユーザーとグループが SCIM 2.0 プロトコルの特定プロファイルを実装するアプリケーションに自動的にプロビジョニングされるように構成できます。 プロファイルの仕様については、「Microsoft Entra SCIM 実装について理解する」に記載されています。
これらの要件との互換性に関する記述については、アプリケーション プロバイダー、またはアプリケーション プロバイダーのドキュメントを確認してください。
重要
Microsoft Entra SCIM 実装は、Microsoft Entra とターゲット アプリケーション間でユーザーを常に同期するように設計された Microsoft Entra ユーザー プロビジョニング サービスの上に構築され、非常に特化した一連の標準操作を実装しています。 Microsoft Entra プロビジョニング サービスの動作を理解するには、これらの動作を把握しておくことが重要です。 詳細については、「プロビジョニングの仕組み」の「プロビジョニング サイクル: 初回と増分」を参照してください。
概要
ヒント
この記事の手順は、開始点のポータルによって若干異なる場合があります。
この記事で説明した SCIM プロファイルをサポートするアプリケーションは、Microsoft Entra アプリケーション ギャラリーの "ギャラリー以外のアプリケーション" 機能を使用して Microsoft Entra ID に接続できます。 接続すると、Microsoft Entra ID は同期プロセスを実行します。 このプロセスは 40 分ごとに実行されます。 このプロセスは、割り当てられたユーザーとグループをアプリケーションの SCIM エンドポイントでクエリ実行し、割り当ての詳細に応じてユーザーとグループを作成または変更します。
SCIM をサポートするアプリケーションを接続する方法
アプリケーション管理者以上の権限で Microsoft Entra 管理センターにログインします。
[ID]>[アプリケーション]>[エンタープライズ アプリケーション] の順に移動します。
ギャラリーから追加されたアプリを含め、構成されたすべてのアプリのリストが表示されます。
[+ 新しいアプリケーション]>[+ 独自のアプリケーションの作成] を選択します。
アプリケーションの名前を入力したら、[ギャラリーで見つからないその他のアプリケーションの統合] オプションを選択して [追加] を選択し、アプリ オブジェクトを作成します。 新しいアプリがエンタープライズ アプリケーションのリストに追加され、アプリの管理画面が開かれます。
次のスクリーンショットは、Microsoft Entra アプリケーション ギャラリーを示しています。
アプリの管理画面で、左側のパネルにある [プロビジョニング] を選択します。
[プロビジョニング モード] メニューで [自動] を選択します。
次のスクリーンショットは、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 エンドポイントのクエリを実行します。 想定される適切な応答は、空の SCIM ListResponse メッセージを持つ HTTP 200 OK です。
アプリケーションへの接続の試行が成功した場合、[保存] を選択して管理者の認証情報を保存します。
[マッピング] セクションには、選択可能な属性マッピングのセットが 2 つあります。1 つはユーザー オブジェクト用で、もう一方はグループ オブジェクト用です。 それぞれ選択し、Microsoft Entra ID からアプリに同期されている属性を確認します。 [照合] プロパティとして選択されている属性は、更新処理にアプリのユーザーとグループを照合するために使用されます。 [保存] を選択してすべての変更をコミットします。
ノート
必要に応じて [グループ] マッピングを無効にすることにより、グループ オブジェクトの同期を無効にできます。
[設定] の [範囲] フィールドは、どのユーザーとグループが同期されるか定義します。 [割り当てられたユーザーとグループのみの同期] (推奨) を選択すると、[ユーザーとグループ] タブに割り当てられたユーザーとグループのみが同期されます。
構成が完了したら、[プロビジョニング状態] を [オン] に設定します。
[保存] を選択して Microsoft Entra プロビジョニング サービスを開始します。
割り当てられたユーザーとグループのみを同期 (推奨) する場合、[ユーザーとグループ] タブを選択します。その後、同期するユーザーとグループを割り当てます。
初期サイクルが開始されたら、左側のパネルにある [プロビジョニング ログ] を選択して進行状況を監視できます。プロビジョニング サービスがアプリに実行したすべてのアクションが表示されます。 Microsoft Entra プロビジョニング ログの読み方の詳細については、「自動ユーザー アカウント プロビジョニングのレポート」を参照してください。
ノート
初期サイクルは以降の同期より長くかかります。サービスが実行されている限り、以降の同期は約 40 分ごとに実行されます。
Microsoft Entra アプリケーション ギャラリーにアプリケーションの発行
複数のテナントによって使用されるアプリケーションを構築する場合、Microsoft Entra アプリケーション ギャラリーで利用可能にできます。 組織が簡単にアプリケーションを見つけてプロビジョニングを構成することができます。 Microsoft Entra ギャラリーにアプリを公開し、他のユーザーがプロビジョニングできるようにすることは簡単です。 手順は、「こちら」で確認してください。 Microsoft はユーザーと協力し、アプリケーションをギャラリーに統合、エンドポイントのテスト、顧客用にオンボーディングドキュメントのリリースを行います。
ギャラリーのオンボーディング チェックリスト
チェックリストを使用してアプリケーションをすばやくオンボードすると、顧客にスムーズな展開エクスペリエンスをもたらします。 ギャラリーにオンボードする際、ユーザーから情報が収集されます。
- SCIM 2.0 のユーザーとグループ エンドポイントをサポート (必要なのは 1 つだけですが、両方とも推奨されます)
- ユーザーとグループが遅延なく確実にプロビジョニングとプロビジョニング解除されるため、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 コードの付与フロー
プロビジョニング サービスは認可コードの付与をサポートしています。ギャラリーでアプリを発行する要求を送信した後、当社のチームは次の情報を収集するためにユーザーに協力します。
認可 URL は、ユーザー エージェントのリダイレクトによってリソース所有者から承認を取得するため、クライアントが発行した URL。 ユーザーは、アクセスを承認するためにこの URL にリダイレクトされます。
トークン交換 URL は、アクセス トークンの認可付与を交換するためにクライアントが発行した URL であり、通常はクライアント認証を使用します。
クライアント ID は、承認サーバーが登録したクライアントに発行するクライアント識別子であり、クライアントが提示する登録情報を表す一意の文字列です。 クライアント識別子はシークレットではありません。リソース所有者に公開されて、クライアント認証に単独で使用してはなりません。
クライアント シークレット は、承認サーバーによって生成されるシークレットであり、承認サーバーにのみ認識される一意の値である必要があります。
ノート
現在、認可 URL とトークン交換 URL はテナントごとに構成することはできません。
ノート
OAuth v1 は、クライアント シークレットの暴露の恐れがあるため、サポートされていません。 OAuth v2 はサポートされています。
OAuth コードの付与フローを使用すると、プロビジョニング インスタンスを設定するときに各顧客が独自のクライアント ID とクライアント シークレットを送信するモデルをサポートする必要があります。 1 つのアプリ全体のクライアント ID とクライアント シークレットのペアはサポートされていません。
OAuth コードの付与フローを設定する方法
アプリケーション管理者以上の権限で Microsoft Entra 管理センターにログインします。
[ID]>[アプリケーション]>[エンタープライズ アプリケーション]>[アプリケーション]>[プロビジョニング] に移動し、[承認] を選択します。
アプリケーション管理者以上の権限で Microsoft Entra 管理センターにログインします。
[ID]>[アプリケーション]>[エンタープライズ アプリケーション] の順に移動します。
アプリケーションを選択して [プロビジョニング] へ移動します。
[承認] を選択します。
ユーザーは承認 URL (サード パーティ アプリのサインイン ページ) にリダイレクトされます。
管理者は、サード パーティ アプリケーションに承認情報を提供します。
サード パーティ アプリは、ユーザーをリダイレクトで戻して付与コードを提示します
プロビジョニング サービスは、トークン URL を呼び出して付与コードを提示します。 サード パーティ アプリケーションは、アクセス トークン、更新トークン、有効期限が含めて応答します
プロビジョニング サイクルが開始されると、サービスは現在のアクセス トークンが有効かどうかを確認し、必要に応じて新しいトークンと交換します。 アクセス トークンは、アプリに対して実行された各要求に提供され、要求の有効性は各要求の前に確認されます。
ノート
ギャラリー以外のアプリケーションで OAuth を設定することはできませんが、承認サーバーからアクセス トークンを手動で生成し、ギャラリー以外のアプリケーションにシークレット トークンとして入力することができます。 これにより、OAuth コードの付与がサポートされるアプリ ギャラリーにオンボードする前に、SCIM サーバーと Microsoft Entra プロビジョニング サービスの互換性を確認できます。
有効期間が長い OAuth ベアラー トークン: アプリケーションが OAuth 承認コードの付与フローをサポートしていない場合、代わりに管理者がプロビジョニング統合のセットアップに使用できる有効期間が長い OAuth ベアラー トークンを生成してください。 トークンは永続的である必要があります。そうでない場合、トークンの有効期限が切れるとプロビジョニング ジョブが検疫されます。
認証と承認方法の詳細については、UserVoice でご連絡ください。
ギャラリーの市場進出リリースのチェックリスト
共同統合の認識と需要を促進するため、既存のドキュメントを更新し、お使いのマーケティング チャネルの統合を拡充することをお勧めします。 リリースをサポートするには、次のチェックリストを完了することをお勧めします。
- 販売チームとカスタマー サポート チームが統合の機能を認識、準備、それについて説明できるようにしてください。 チームとブリーフィングをしてよく寄せられる質問をし、統合内容を販売資料に盛り込みます。
- 共同統合、メリット、開始方法について説明するブログ投稿やプレス リリースを作成します。 例: Imprivata と Microsoft Entra のプレス リリース
- X、Facebook、LinkedIn などのソーシャル メディアを活用し、顧客の統合を促します。 当社が投稿をリツイートできるように、必ず @Microsoft Entra ID を含めてください。 例: Imprivata の X のポスト
- マーケティングのページや Web サイト (統合ページ、パートナーのページ、価格ページなど) を作成または更新し、共同統合を利用できる時期を含めてください。 例: Pingboard の統合ページ、Smartsheet の統合ページ、Monday.com の価格ページ
- 顧客が開始できる方法に関するヘルプ センターの記事またはテクニカル ドキュメントを作成します。 例: Envoy + Microsoft Entra の統合。
- 顧客とのコミュニケーション (月刊ニュースレター、メール キャンペーン、製品リリースのメモ) を通じて、新しい統合について顧客に通知します。