チュートリアル: 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) ライブラリとコード サンプルを使用してエンドポイントを構築します。 これらのサンプルは、参照とテストのみを目的としています。実稼働アプリの依存関係として使用することはお勧めしません。
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 の属性 |
|---|---|---|
| loginName | userName | userPrincipalName |
| firstName | name.givenName | givenName |
| lastName | name.familyName | surName |
| workMail | emails[type eq "work"].value | |
| manager | manager | manager |
| tag | urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag |
extensionAttribute1 |
| status | active | 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"
}
}
Note
アプリケーションに必要な属性に加えて、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 | active |
| department | 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 | title |
| emails[type eq "work"].value | |
| mailNickname | externalId |
| manager | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager |
| mobile | phoneNumbers[type eq "mobile"].value |
| postalCode | addresses[type eq "work"].postalCode |
| proxy-Addresses | 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 |
| members | members |
| objectId | externalId |
Note
ユーザーとグループの両方をサポートする必要はありません。ここに記載されているすべての属性をサポートする必要もありません。これはあくまで参考として、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 の認証と認可のために、単一のベアラー トークンを受け入れる。 |
Microsoft Entra ID との互換性を確保するために、SCIM エンドポイントの実装時は次の一般的なガイドラインに従ってください。
全般:
idは、すべてのリソースの必須のプロパティです。 リソースを返すすべての応答において、メンバーが 0 のListResponseを除き、各リソースにこのプロパティが含まれるようにする必要があります。- 送信された値は、送信時と同じ形式で格納する必要があります。 無効な値は、わかりやすいアクション可能なエラー メッセージを付けて拒否する必要があります。 データの変換は、Microsoft Entra ID からのデータと SCIM アプリケーションの格納データの間で行うことはできません。 (例: (55555555555 として送信された電話番号は、+5 (555) 555-5555 として保存または返すことはできません)
- PATCH 応答には、リソース全体を含める必要はありません。
- セクション 3.5.2 に定義されているように、特に PATCH
op操作値の場合、SCIM 内の構造要素に対して大文字と小文字を区別した一致を要求しないでください。 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のみが使用されます。 - リソースの照会が可能な属性は、アプリケーション上の照合属性として設定される必要があります。ユーザー プロビジョニング属性マッピングのカスタマイズに関するページを参照してください。
/Users:
- エンタイトルメント属性はサポートされていません。
- ユーザーの一意性のために使用される属性が、フィルター選択されたクエリの一部として使用できる必要があります。 たとえば、ユーザーの一意性が、userName と emails[type eq "work"] の両方に対して評価される場合、フィルターを使用した /Users への GET は、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 つの点でユーザーに関するメッセージと異なっています。
- グループを取得する要求では、要求に対する応答の中で提示されるリソースから、members 属性が除外されるように指定しています。
- 参照属性に特定の値があるかどうかを判別する要求は、members 属性に関する要求になります。
次の図は、グループのプロビジョニング解除シーケンスを示しています。
SCIM プロトコル要求と応答
この記事では、Microsoft Entra プロビジョニング サービスによって出力される SCIM 要求の例と、予想される応答の例を示します。 最良の結果を得るには、このような要求をこの形式で処理し、想定される応答を出力するよう、アプリをコーディングしてください。
重要
Microsoft Entra ユーザー プロビジョニング サービスが例に示す操作を出力する方法とタイミングについては、プロビジョニングのしくみに関する記事の「プロビジョニング サイクル: 初回と増分」をご覧ください。
- ユーザーの作成 (要求 / 応答)
- ユーザーの取得 (要求 / 応答)
- クエリによるユーザーの取得 (要求 / 応答)
- クエリによるユーザーの取得 - 0 件の結果 (要求 / 応答)
- ユーザーの更新 [複数値のプロパティ] (要求 / 応答)
- ユーザーの更新 [単一値のプロパティ] (要求 / 応答)
- ユーザーの無効化 (要求 / 応答)
- ユーザーの削除 (要求 / 応答)
- グループの作成 (要求 / 応答)
- グループの取得 (要求 / 応答)
- displayName でのグループの取得 (要求 / 応答)
- グループの更新 [非メンバー属性] (要求 / 応答)
- グループの更新 [メンバーの追加] (要求 / 応答)
- グループの更新 [メンバーの削除] (要求 / 応答)
- グループの削除 (要求 / 応答)
ユーザー操作
userNameまたはemails[type eq "work"]属性を使用してユーザーにクエリを実行します。
[Create User]
Request
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": []
}
Response
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
}]
}
ユーザーの取得
Request
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
}]
}
Request
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 件の結果
Request
GET /Users?filter=userName eq "non-existent user"
Response
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 0,
"Resources": [],
"startIndex": 1,
"itemsPerPage": 20
}
ユーザーの更新 [複数値のプロパティ]
Request
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"
}
]
}
Response
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
}]
}
ユーザーの更新 [単一値のプロパティ]
Request
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"
}]
}
Response
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
}]
}
ユーザーの無効化
Request
PATCH /Users/5171a35d82074e068ce2 HTTP/1.1
{
"Operations": [
{
"op": "Replace",
"path": "active",
"value": false
}
],
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
]
}
Response
{
"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"
}
}
ユーザーの削除
Request
DELETE /Users/5171a35d82074e068ce2 HTTP/1.1
Response
HTTP/1.1 204 No Content
グループ操作
- グループは、空のメンバーのリストで作成されます。
displayName属性を使用してグループのクエリを実行します。- グループ PATCH 要求を更新すると、応答に HTTP 204 No Content が含まれることになります。 全メンバーのリストを含めて本文を返すことはお勧めできません。
- グループの全メンバーを返すことをサポートする必要はありません。
グループの作成
Request
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"
}
}
Response
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": []
}
グループの取得
Request
GET /Groups/40734ae655284ad3abcc?excludedAttributes=members HTTP/1.1
Response
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
}
グループの更新 [非メンバー属性]
Request
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"
}]
}
Response
HTTP/1.1 204 No Content
グループの更新 [メンバーの追加]
Request
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"
}]
}]
}
Response
HTTP/1.1 204 No Content
グループの更新 [メンバーの削除]
Request
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"
}]
}]
}
Response
HTTP/1.1 204 No Content
グループの削除
Request
DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1
Response
HTTP/1.1 204 No Content
スキーマ検出
スキーマの検出
Request
GET /Schemas
Response
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 エンドポイントを構築し、提供されるサンプルの要求/応答を介して実行してテストします。
Note
参照コードは、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 です。 単一のテナントに登録されているアプリケーションは、同じ
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 例です。
Note
これは一例です。 すべてのユーザーに 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);
ユーザーの現在の状態を取得する要求の例では、parameters 引数の値として指定されたオブジェクトのプロパティ値は次のようになります。
- 識別子: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
- SchemaIdentifier:
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"
- 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 引数の値として指定されたオブジェクトのプロパティ値は次のようになります。
| 引数 | Value |
|---|---|
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 |
Manager |
(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 ID アプリケーション ギャラリーの "ギャラリー以外のアプリケーション" 機能を使用して 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 によって発行されたトークンを検証できます。
Note
このフィールドを空白のままにして、Microsoft Entra ID によって生成されるトークンに依存することは推奨されません。 このオプションは、主にテスト目的で使用できます。
[テスト接続] を選択して、Microsoft Entra ID の SCIM エンドポイントへの接続を試みます。 試行に失敗した場合は、エラー情報が表示されます。
Note
テスト接続では、Microsoft Entra 構成で照合プロパティとして選択されたランダムな GUID を使用して、存在しないユーザー用の SCIM エンドポイントのクエリが実行されます。 想定される適切な応答は、HTTP 200 OK と空の SCIM ListResponse メッセージです。
アプリケーションへの接続の試行に成功した場合は、 [保存] を選択して管理者資格情報を保存します。
[マッピング] セクションには、選択可能な 2 つの属性マッピングのセットがあります。片方はユーザー オブジェクト用であり、他方はグループ オブジェクト用です。 Microsoft Entra ID からアプリに同期されている属性を確認するには、それぞれを選択します。 [Matching](照合) プロパティとして選択されている属性は、更新処理でアプリ内のユーザーとアカウントを照合するために使用されます。 すべての変更をコミットするには、 [保存] を選択します。
注意
必要に応じて [グループ] マッピングを無効にすることで、グループ オブジェクトの同期を無効にできます。
[設定] の [スコープ] フィールドは、どのユーザーおよびグループが同期されるかを定義します。 [割り当てられたユーザーとグループのみを同期する] (推奨) を選択すると、 [ユーザーとグループ] タブに割り当てられたユーザーとグループのみが同期されます。
構成が完了したら、 [プロビジョニング状態] を [オン] に設定します。
Microsoft Entra プロビジョニング サービスを開始するには、[保存] を選択します。
割り当てられたユーザーとグループのみを同期する (推奨) 場合は、[ユーザーとグループ] タブを選択し、同期するユーザーとグループを割り当てます。
初期サイクルが開始されたら、左側のパネルにある [プロビジョニング ログ] を選択して進行状況を監視できます。これにより、プロビジョニング サービスによって実行されたすべてのアクションがアプリで表示されます。 Microsoft Entra プロビジョニング ログの読み方の詳細については、「自動ユーザー アカウント プロビジョニングについてのレポート」を参照してください。
Note
初期サイクルは、サービスが実行されている限り約 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 クライアント資格情報の付与に対するサポートはバックログに入っています。 |
Note
Microsoft Entra プロビジョニング構成のカスタム アプリ UI では、トークン フィールドを空白のままにすることはお勧めしません。 生成されたトークンは、主にテスト目的で使用できます。
OAuth コード付与フロー
プロビジョニング サービスでは、認可コードの付与がサポートされています。ギャラリーにアプリを発行するための要求を送信した後、私たちのチームは次の情報を収集するためにお客様と協力します。
認可 URL: ユーザー エージェント リダイレクトによってリソース所有者から承認を取得するためのクライアントによる URL。 ユーザーは、アクセスを承認するためにこの URL にリダイレクトされます。
トークン交換 URL: アクセス トークンの認可付与を交換するためのクライアントによる URL。通常は、クライアント認証を使用します。
クライアント ID: 認可サーバーは、登録されたクライアントにクライアント識別子 (クライアントによって提供される登録情報を表す一意の文字列) を発行します。 クライアント識別子はシークレットではありません。これはリソースの所有者に公開されており、クライアント認証に単独で使用できません。
クライアント シークレット: 認可サーバーによって生成されるシークレット。これは認可サーバーにのみ認識される一意の値である必要があります。
Note
現在、認可 URL とトークン交換 URL をテナントごとに構成することはできません。
Note
OAuth v1 は、クライアント シークレットの露出が原因でサポートされていません。 OAuth v2 はサポートされています。
OAuth コード付与フローを使用する場合は、プロビジョニング インスタンスを設定するときに、各顧客が独自のクライアント ID とクライアント シークレットを送信するモデルをサポートする必要があります。 1 つのアプリ全体のクライアント ID とクライアント シークレットのペアはサポートされていません。
OAuth コード付与フローをセットアップする方法
アプリケーション管理者以上の権限で Microsoft Entra 管理センターにサインインします。
[ID]>[アプリケーション]>[エンタープライズ アプリケーション]>[アプリケーション]>[プロビジョニング] に移動し、[承認] を選択します。
アプリケーション管理者以上の権限で Microsoft Entra 管理センターにサインインします。
[ID]>[アプリケーション]>[エンタープライズ アプリケーション] の順に移動します。
アプリケーションを選択して、[プロビジョニング] へ移動します。
[承認] を選択します。
ユーザーは承認 URL (サード パーティのアプリのサインイン ページ) にリダイレクトされます。
管理者は、サード パーティのアプリケーションに資格情報を提供します。
サード パーティのアプリによってユーザーがリダイレクトし戻され、付与コードが提供されます
プロビジョニング サービスによって、トークン URL が呼び出され、付与コードが提供されます。 サード パーティのアプリケーションから、アクセス トークン、更新トークン、有効期限が含まれた応答が返されます。
プロビジョニング サイクルが開始されると、サービスによって現在のアクセス トークンが有効かどうかが確認され、必要に応じて新しいトークンと交換されます。 アクセス トークンは、アプリに対して行われた各要求で提供され、要求の有効性は各要求の前に確認されます。
Note
ギャラリー以外のアプリケーションで OAuth を設定することはできませんが、認可サーバーからアクセス トークンを手動で生成し、ギャラリー以外のアプリケーションにシークレット トークンとして入力することができます。 これにより、OAuth コード付与がサポートされるアプリ ギャラリーにオンボードする前に、SCIM サーバーと Microsoft Entra プロビジョニング サービスとの互換性を確認できます。
有効期間が長い OAuth ベアラー トークン: アプリケーションで OAuth 認可コード付与フローがサポートされていない場合は、管理者がプロビジョニング統合のセットアップに使用できる、有効期間が長い OAuth ベアラー トークンを生成してください。 トークンは永続的である必要があり、そうでない場合、トークンの有効期限が切れるとプロビジョニング ジョブが検疫されます。
追加の認証および承認方法については、UserVoice にご連絡ください。
ギャラリーの Go-To-Market Launch チェックリスト
共同統合の認識と需要を促進するために、既存のドキュメントを更新し、お使いのマーケティング チャネルにおける統合を拡充することをお勧めします。 Launch をサポートするために、次のチェックリストを完了することをお勧めします。
- 販売チームとカスタマー サポート チームが統合の機能を認識し、準備し、それについて説明できるようにします。 チームに概要を伝え、FAQ を提供し、統合を販売資料に含めます。
- 共同統合、利点、および開始方法について説明するブログ投稿やプレス リリースを作成します。 例: Imprivata と Microsoft Entra のプレス リリース
- X、Facebook、LinkedIn などのソーシャル メディアを活用し、顧客の統合を促します。 当社が投稿をリツイートできるように、必ず @Microsoft Entra ID を含めてください。 例: Imprivata の X のポスト
- マーケティングのページや Web サイト (統合ページ、パートナーのページ、価格ページなど) を作成または更新し、共同統合を利用できる時期を含めてください。 例:Pingboard の統合のページ、Smartsheet の統合のページ、Monday.com の価格ページ
- 顧客がどのように開始できるかに関するヘルプ センターの記事またはテクニカル ドキュメントを作成します。 例: Envoy と Microsoft Entra の統合。
- 顧客とのコミュニケーション (月次のニュースレター、メールによるキャンペーン、製品のリリース ノート) を通じて、新しい統合を顧客に通知します。