カスタムクレームプロバイダーリファレンス

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

この参照記事では、カスタムクレームプロバイダーイベントの REST API スキーマと要求マッピングポリシー構造について説明します。

トークン発行開始イベント

カスタムクレームプロバイダートークン発行イベントを使用すると、外部システムからの情報を使用してアプリケーショントークンを強化またはカスタマイズできます。この情報は、Microsoft Entra ディレクトリのユーザープロファイルの一部として格納することができません。

コンポーネントの概要

カスタム拡張機能をアプリケーションと設定し統合するには、複数のコンポーネントを接続する必要があります。次の図は、構成ポイントと、カスタム拡張機能を実装するために作成されたリレーションシップの概要を示しています。

REST API エンドポイントを一般公開する必要があります。この図では、Azure 関数で表されています。 REST API はカスタム要求を生成し、カスタム拡張機能に返します。これは、Microsoft Entraアプリケーションの登録に関連付けられています。
API に接続するように構成されている Microsoft Entra ID でカスタム拡張機能を構成する必要があります。
カスタマイズされたトークンを受け取るアプリケーションが必要です。たとえば、トークンのデコードされた内容を表示する https://jwt.ms Microsoft 所有の Web アプリケーション。
https://jwt.ms などのアプリケーションは、アプリ登録を使用して Microsoft Entra ID に登録する必要があります。
アプリケーションとカスタム拡張機能間に関連付けを作成する必要があります。
必要に応じて、認証プロバイダーを使用して Azure 関数をセキュリティで保護できます。この記事では、Microsoft Entra ID を使用します。

REST API

REST API エンドポイントは、ダウンストリームサービスとのインターフェイスを担当します。たとえば、データベース、他の REST API、LDAP ディレクトリ、またはトークン構成に追加する属性を含む他のストアなどです。

REST API からは、属性を含む Microsoft Entra ID に HTTP 応答が返されます。 REST API によって返される属性は、トークンに自動的に追加されません。代わりに、任意の属性をトークンに含めるために、アプリケーションの要求マッピングポリシーを構成する必要があります。 Microsoft Entra ID では、クレームマッピングポリシーにより、特定のアプリケーションに対して発行されたトークンに出力されるクレームが変更されます。

REST API スキーマ

トークン発行開始イベント用の独自の REST API を開発するには、次の REST API データコントラクトを使用します。スキーマは、要求ハンドラーと応答ハンドラーを設計するコントラクトを表します。

Microsoft Entra ID のカスタム拡張機能では、JSON ペイロードを使用して REST API に HTTP 呼び出しを行います。 JSON ペイロードには、ユーザープロファイルデータ、認証コンテキスト属性、およびユーザーがサインインするアプリケーションに関する情報が含まれています。次の JSON の id 値は、Microsoft Entra 認証イベントサービスを表す Microsoft アプリケーションです。 JSON 属性は、API によって追加のロジックを実行するために使用できます。 API への要求の形式は次のとおりです。

POST https://your-api.com/endpoint

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/<Your tenant GUID>/applications/<Your Test Application App Id>",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "<Your tenant GUID>",
        "authenticationEventListenerId": "<GUID>",
        "customAuthenticationExtensionId": "<Your custom extension ID>",
        "authenticationContext": {
            "correlationId": "<GUID>",
            "client": {
                "ip": "30.51.176.110",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen"
                "createdDateTime": "2016-03-01T15:23:40Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", // Client ID representing the Microsoft Entra authentication events service
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Azure が想定する REST API の応答形式は、以下のような形式で、要求 DateOfBirth と CustomRoles が Azure に返されます。

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "DateOfBirth": "01/01/2000",
                    "CustomRoles": [
                        "Writer",
                        "Editor"
                    ]
                }
            }
        ]
    }
}

Fabrikam 組織の B2B ユーザーが Contoso の組織に対して認証を行うと、REST API に送信される要求ペイロードには、以下の形式の user 要素が含まれています。

"user": {
    "companyName": "Fabrikam",
    "createdDateTime": "2022-07-15T00:00:00Z",
    "displayName": "John Wright",
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "mail": "johnwright@fabrikam.com",
    "preferredDataLocation": "EUR",
    "userPrincipalName": "johnwright_fabrikam.com#EXT#@contoso.onmicrosoft.com",
    "userType": "Guest"
}

サポートされるデータ型

次の表は、トークン発行開始イベントでカスタムクレームプロバイダーによってサポートされるデータ型を示しています。

データ型	サポートされています
String	True
文字列配列	True
Boolean	False
JSON	False

要求のマッピングポリシー

Microsoft Entra ID では、クレームマッピングポリシーにより、特定のアプリケーションに対して発行されたトークンに出力されるクレームが変更されます。これには、カスタムクレームプロバイダーからの要求と、トークンへの発行が含まれます。

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "true",
        "ClaimsSchema": [{
            "Source": "CustomClaimsProvider",
            "ID": "dateOfBirth",
            "JwtClaimType": "birthdate"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "customRoles",
            "JwtClaimType": "my_roles"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "correlationId",
            "JwtClaimType": "correlation_Id"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "apiVersion",
            "JwtClaimType": "apiVersion"
        },
        {
            "Value": "tokenaug_V2",
            "JwtClaimType": "policy_version"
        }]
    }
}

ClaimsSchema 要素には、次の属性にマップされる要求の一覧が含まれています。

ソースは属性のソースである CustomClaimsProvider を表します。最後の要素には、テスト目的でポリシーバージョンの固定値が含まれていることに注意してください。したがって、source 属性は省略されます。
ID は、作成した Azure 関数から返される要求の名前です。

重要

ID 属性の値では大文字と小文字が区別されます。要求名は、Azure 関数から返されたとおりに入力してください。
JwtClaimType は、OpenID Connect アプリ用に出力されたトークン内の要求の省略可能な名前です。これにより、JWT トークンで返される別の名前を指定できます。たとえば、API 応答の ID 値が dateOfBirth の場合、トークンで birthdate として出力できます。

クレームマッピングポリシーを作成したら、次の手順で Microsoft Entra テナントにアップロードします。テナントで次の claimsMappingPolicy Graph API を使用します。

重要

定義要素は、単一の文字列値を持つ配列である必要があります。文字列は、要求マッピングポリシーの文字列化およびエスケープされたバージョンである必要があります。 https://jsontostring.com/ などのツールを使用して、要求マッピングポリシーを文字列化できます。

次の方法で共有

カスタムクレームプロバイダーリファレンス

トークン発行開始イベント

コンポーネントの概要

REST API

REST API スキーマ

サポートされるデータ型

要求のマッピングポリシー

関連項目

フィードバック

フィードバック

その他のリソース

次の方法で共有

カスタム クレーム プロバイダー リファレンス

トークン発行開始イベント

コンポーネントの概要

REST API

REST API スキーマ

サポートされるデータ型

要求のマッピング ポリシー

関連項目

フィードバック

フィードバック

その他のリソース

カスタムクレームプロバイダーリファレンス

要求のマッピングポリシー