次の方法で共有

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

  • [アーティクル]

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

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

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

コンポーネントの概要

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

カスタム クレーム プロバイダーを設定して統合するために Microsoft Entra ID で構成するコンポーネントを示すスクリーンショット。

  • 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

要求サイズの制限

要求プロバイダーが返すことができる最大要求サイズは、3 KB に制限されています。 これは、REST API によって返されるすべてのキーと値のペアの合計です。

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

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/ などのツールを使用して、要求マッピング ポリシーを文字列化できます。

関連項目