名前空間: microsoft.graph
重要
Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
アプリケーションまたは agentIdentityBlueprint の新しい federatedIdentityCredential オブジェクトを作成します。
Microsoft Entra アプリケーション登録またはエージェント ID ブループリントと、コンピューティング プラットフォームの ID プロバイダーの間に信頼関係を構成することで、そのプラットフォームによって発行されたトークンを使用して、Microsoft ID プラットフォームで認証し、Microsoft エコシステム内の API を呼び出すことができます。 アプリケーションまたはエージェントのIDブループリントには、最大20個のオブジェクトを追加できます。
この API は、次の国内クラウド展開で使用できます。
| グローバル サービス | 米国政府機関 L4 | 米国政府機関 L5 (DOD) | 21Vianet が運営する中国 |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
アクセス許可
この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。
アプリケーションのアクセス許可
| アクセス許可の種類 | 最小特権アクセス許可 | より高い特権のアクセス許可 |
|---|---|---|
| 委任 (職場または学校のアカウント) | Application.ReadWrite.All | 注意事項なし。 |
| 委任 (個人用 Microsoft アカウント) | Application.ReadWrite.All | 注意事項なし。 |
| アプリケーション | Application.ReadWrite.OwnedBy | Application.ReadWrite.All |
重要
職場または学校アカウントを使用してアクセスを委任するには、サインインしたユーザーに、サポートされている Microsoft Entra ロール、またはこの操作に必要なアクセス許可を付与するカスタム ロールが割り当てられている必要があります。 この操作では、必要最小限の特権のみを提供する次の組み込みロールがサポートされます。
- 既定のユーザー権限を持つ管理者以外のメンバー ユーザー (所有するアプリケーションの場合)
- アプリケーション開発者 - 所有しているアプリケーションの場合
- クラウド アプリケーション管理者
- アプリケーション管理者
agentIdentityBlueprint のアクセス許可
| アクセス許可の種類 | 最小特権アクセス許可 | より高い特権のアクセス許可 |
|---|---|---|
| 委任 (職場または学校のアカウント) | AgentIdentityBlueprint.Create | AgentIdentityBlueprint.ReadWrite.All, Directory.ReadWrite.All |
| 委任 (個人用 Microsoft アカウント) | サポートされていません。 | サポートされていません。 |
| アプリケーション | AgentIdentityBlueprint.Create | AgentIdentityBlueprint.ReadWrite.All, Directory.ReadWrite.All |
重要
- エージェント ID ブループリントまたはブループリント プリンシパルを作成したプリンシパルは、自動的に所有者として割り当てられます。
- 所有者は、エージェントIDロールを割り当てなくても、所有するブループリントに関連付けられたエージェントIDを作成および変更できます。
- 非所有者が委任されたシナリオで職場または学校アカウントを使用してこの API を呼び出すには、管理者にサポートされている Microsoft Entra ロールが割り当てられている必要があります。 この操作では、次の最小特権の組み込みロールがサポートされます。
HTTP 要求
アプリケーションの場合:
- アプリケーションは、 ID または appId のいずれかを使用してアドレス指定できます。 id と appId は、Microsoft Entra 管理センターでのアプリの登録において、それぞれオブジェクト ID とアプリケーション (クライアント) ID と呼ばれます。
POST /applications/{id}/federatedIdentityCredentials
POST /applications(appId='{appId}')/federatedIdentityCredentials
agentIdentityBlueprint の場合:
POST /applications/{id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials
要求ヘッダー
| 名前 | 説明 |
|---|---|
| Authorization | ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。 |
| Content-Type | application/json. 必須です。 |
要求本文
要求の本文で、 federatedIdentityCredential オブジェクトの JSON 表現を指定します。
次の表に、 federatedIdentityCredential を作成するときに必要なプロパティの一覧を示します。
| プロパティ | 型 | 説明 |
|---|---|---|
| 対象ユーザー | String collection | 必須です。 外部トークンに表示できる対象ユーザー。 このフィールドは必須であり、Microsoft Entra IDには api://AzureADTokenExchange に設定する必要があります。 これは、受信トークンの aud クレームで受け入れるMicrosoft ID プラットフォーム内容を示します。 この値は、外部 ID プロバイダーの Microsoft Entra ID を表し、ID プロバイダー間で固定された値はありません。このトークンの対象ユーザーとして機能するには、ID プロバイダーで新しいアプリケーション登録を作成する必要がある場合があります。 このフィールドは 1 つの値のみを受け入れることができ、600 文字の制限があります。 |
| claimsMatchingExpression | federatedIdentityExpression | Null 許容型。 既定値は null (設定されていない場合) になります。 指定された要求に対して式を一致させる要求の使用を有効にします。
claimsMatchingExpression が定義されている場合、subject は null である必要があります。 サポートされている式の構文と要求の一覧については、 フレキシブル FIC リファレンスを参照してください。 |
| 発行者 | String | 必須です。 外部 ID プロバイダーの URL であり、交換される外部トークンの発行者の要求と一致する必要があります。 発行者とサブジェクトの値の組み合わせは、アプリ上で一意である必要があります。 600 文字の制限があります。 |
| name | String | 必須です。 フェデレーション ID 資格情報の一意識別子。120 文字の制限があり、URL 対応である必要があります。 一度作成すると変更できません。 |
| subject | 文字列 | Null 許容型。 既定値は null (設定されていない場合) になります。 外部 ID プロバイダー内の外部ソフトウェア ワークロードの識別子。 対象ユーザーの値と同様に、各 ID プロバイダーが独自の形式 (GUID、コロンで区切られた識別子、任意の文字列) を使用するため、固定の形式はありません。 ここでの値は、Microsoft Entra ID に提示されたトークン内のサブ要求と一致する必要があります。 600 文字の制限があります。
発行者とサブジェクトの組み合わせは、アプリ上で一意である必要があります。
subject が定義されている場合は、claimsMatchingExpression がnullである必要があります。 |
応答
成功した場合、このメソッドは応答本文で 201 Created 応答コードと federatedIdentityCredential オブジェクトを返します。
例
例 1: アプリケーションのフェデレーション ID 資格情報の作成
要求
POST https://graph.microsoft.com/beta/applications/bcd7c908-1c4d-4d48-93ee-ff38349a75c8/federatedIdentityCredentials/
Content-Type: application/json
{
"name": "testing02",
"issuer": "https://login.microsoftonline.com/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/v2.0",
"subject": "a7d388c3-5e3f-4959-ac7d-786b3383006a",
"audiences": [
"api://AzureADTokenExchange"
]
}
応答
注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。
HTTP/1.1 201 Created
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#applications('bcd7c908-1c4d-4d48-93ee-ff38349a75c8')/federatedIdentityCredentials/$entity",
"@odata.id": "https://graph.microsoft.com/v2/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/directoryObjects/$/Microsoft.DirectoryServices.Application('bcd7c908-1c4d-4d48-93ee-ff38349a75c8')/federatedIdentityCredentials/d9b7bf1e-429e-4678-8132-9b00c9846cc4",
"id": "d9b7bf1e-429e-4678-8132-9b00c9846cc4",
"name": "testing02",
"issuer": "https://login.microsoftonline.com/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/v2.0",
"subject": "a7d388c3-5e3f-4959-ac7d-786b3383006a",
"description": null,
"audiences": [
"api://AzureADTokenExchange"
]
}
例 2: agentIdentityBlueprint のフェデレーション ID 資格情報を作成する
要求
POST https://graph.microsoft.com/beta/applications/bcd7c908-1c4d-4d48-93ee-ff38349a75c8/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials/
Content-Type: application/json
{
"name": "testing02",
"issuer": "https://login.microsoftonline.com/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/v2.0",
"subject": "a7d388c3-5e3f-4959-ac7d-786b3383006a",
"audiences": [
"api://AzureADTokenExchange"
]
}
応答
注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。
HTTP/1.1 201 Created
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#applications('bcd7c908-1c4d-4d48-93ee-ff38349a75c8')/federatedIdentityCredentials/$entity",
"@odata.id": "https://graph.microsoft.com/v2/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/directoryObjects/$/Microsoft.DirectoryServices.Application('bcd7c908-1c4d-4d48-93ee-ff38349a75c8')/federatedIdentityCredentials/d9b7bf1e-429e-4678-8132-9b00c9846cc4",
"id": "d9b7bf1e-429e-4678-8132-9b00c9846cc4",
"name": "testing02",
"issuer": "https://login.microsoftonline.com/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/v2.0",
"subject": "a7d388c3-5e3f-4959-ac7d-786b3383006a",
"description": null,
"audiences": [
"api://AzureADTokenExchange"
]
}