Upsert federatedIdentityCredential

[アーティクル]
03/13/2024

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

アプリケーションに新しい federatedIdentityCredential オブジェクトが存在する場合は作成するか、既存の federatedIdentityCredential オブジェクトのプロパティを更新します。 Microsoft Entra アプリケーション登録とコンピューティングプラットフォームの ID プロバイダーの間に信頼関係を構成することで、そのプラットフォームによって発行されたトークンを使用して、Microsoft ID プラットフォームで認証し、Microsoft エコシステムの API を呼び出すことができます。アプリケーションには最大 20 個のオブジェクトを追加できます。

この API は、次の国内クラウド展開で使用できます。

グローバルサービス	米国政府機関 L4	米国政府機関 L5 (DOD)	21Vianet が運営する中国
✅	✅	✅	✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。これらのアクセス許可の詳細については、アクセス許可のリファレンスを参照してください。

アクセス許可の種類	最小特権アクセス許可	特権の高いアクセス許可
委任 (職場または学校のアカウント)	Application.ReadWrite.All	注意事項なし。
委任 (個人用 Microsoft アカウント)	Application.ReadWrite.All	注意事項なし。
アプリケーション	Application.ReadWrite.OwnedBy	Application.ReadWrite.All

HTTP 要求

アプリケーションのアドレスは、 その ID または appId を使用して行うことができます。 id と appId は、Microsoft Entra 管理センターのアプリ登録でそれぞれオブジェクト ID とアプリケーション (クライアント) ID と呼ばれます。

PATCH /applications/{id}/federatedIdentityCredentials(name='{name}')
PATCH /applications(appId='{appId}')/federatedIdentityCredentials(name='{name}')

要求ヘッダー

名前	説明
Authorization	ベアラー {token}。必須です。認証と承認の詳細については、こちらをご覧ください。
Content-Type	application/json. Required.
Prefer	`create-if-missing`. アップサート動作に必要です。それ以外の場合、要求は更新操作として扱われます。

要求本文

要求本文で、 federatedIdentityCredential オブジェクトの JSON 表現を指定します。次の表に、 federatedIdentityCredential を作成するときに必要なプロパティを示します。 name プロパティは、要求 URL の一部として必要であることに注意してください。

プロパティ	型	説明
観客	String collection	外部トークンに表示できる対象ユーザー。このフィールドは必須であり、Microsoft Entra IDにはに`api://AzureADTokenExchange`設定する必要があります。受信トークンの要求で`aud`受け入れる必要があるMicrosoft ID プラットフォームが表示されます。この値は、外部 ID プロバイダーのMicrosoft Entra IDを表し、ID プロバイダー間で固定値がありません。このトークンの対象ユーザーとして機能するには、ID プロバイダーに新しいアプリケーション登録を作成する必要がある場合があります。このフィールドは 1 つの値のみを受け入れることができ、600 文字の制限があります。必須です。
発行者	String	T 外部 ID プロバイダーの URL と、交換される外部トークンの発行者要求と一致する必要があります。発行者とサブジェクトの値の組み合わせは、アプリで一意である必要があります。制限は 600 文字です。必須です。
subject	String	必須です。外部 ID プロバイダー内の外部ソフトウェアワークロードの識別子。対象ユーザーの値と同様に、各 ID プロバイダーが独自の GUID、時にはコロンで区切られた識別子、時には任意の文字列を使用する場合があるため、固定形式はありません。ここでの値は、Microsoft Entra IDに提示されるトークン内のサブ要求と一致する必要があります。制限は 600 文字です。発行者とサブジェクトの組み合わせは、アプリで一意である必要があります。

応答

成功した場合、名前を持つアプリケーションオブジェクトが存在しない場合、このメソッドは応答コードと、応答本文に新しい federatedIdentityCredential オブジェクトを返201 Createdします。

名前のアプリケーションオブジェクトが既に存在する場合、このメソッドは federatedIdentityCredential オブジェクトを更新し、応答コードを204 No Content返します。

例

例 1: 新しい federatedIdentityCredential が存在しない場合は作成する

次の例では、指定した名前の値を持つ federatedIdentityCredential が存在しないため、federatedIdentityCredential を作成します。

要求

次の例は要求を示しています。

PATCH https://graph.microsoft.com/beta/applications(uniqueName='app-65278')/federatedIdentityCredentials(name='fic01-app-65278')
Content-Type: application/json

{
    "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",
    "id": "d9b7bf1e-429e-4678-8132-9b00c9846cc4",
    "name": "testing02fic01-app-65278",
    "issuer": "https://login.microsoftonline.com/3d1e2be9-a10a-4a0c-8380-7ce190f98ed9/v2.0",
    "subject": "a7d388c3-5e3f-4959-ac7d-786b3383006a",
    "description": null,
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

例 2: 既存の federatedIdentityCredential を更新する

次の例では、指定した名前の値を持つ federatedIdentityCredential が存在するため、federatedIdentityCredential を更新します。

要求