OnAttributeCollectionSubmit イベントからデータを取得して返す

2025-06-26

適用対象: 灰色の X 記号がある白い円。従業員テナント白いチェックマーク記号がある緑の円。外部テナント (詳細情報)

顧客のセルフサービスサインアップユーザーフローのサインアップエクスペリエンスを変更するには、カスタム認証拡張機能を作成し、ユーザーフロー内の特定のポイントで呼び出します。 OnAttributeCollectionSubmit イベントは、ユーザーが属性を入力して送信した後に発生し、ユーザーが提供する情報を検証するために使用できます。たとえば、招待コードまたはパートナー番号を検証したり、アドレス形式を変更したり、ユーザーが続行したり、検証またはブロックページを表示したりできます。次のアクションを構成できます。

continueWithDefaultBehavior - サインアップフローを続行します。
modifyAttributeValues - サインアップフォームでユーザーが送信した値を上書きします。
showValidationError - 送信された値に基づいてエラーを返します。
showBlockPage - エラーメッセージを表示し、ユーザーのサインアップをブロックします。

この記事では、OnAttributeCollectionSubmit イベントの REST API スキーマについて説明します。 (関連記事「 OnAttributeCollectionStart イベントのカスタム拡張機能」も参照してください)。

ヒント

この機能を試すには、Woodgrove Groceries のデモにアクセスし、"サインアップ属性の検証" ユースケースまたは "ユーザーがサインアッププロセスを続行できないようにする" ユースケースを開始します。

REST API スキーマ

属性コレクション送信イベント用の独自の REST API を開発するには、次の REST API データコントラクトを使用します。スキーマは、要求ハンドラーと応答ハンドラーを設計するコントラクトを記述します。

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

外部 REST API への要求

REST API への要求は、次の例に示す形式です。この例では、要求には、組み込みの属性 (givenName と companyName) とカスタム属性 (universityGroups、graduationYear、onMailingList) と共にユーザー ID 情報が含まれています。

要求には、セルフサービスサインアップ時にコレクション用にユーザーフローで選択されたユーザー属性が含まれます。組み込みの属性 (givenName や companyName など) と、既に定義されているカスタム属性 (universityGroups、graduationYear、onMailingList など) が含まれます。 REST API で新しい属性を追加することはできません。

要求にはユーザー ID も含まれます。これには、サインアップに検証済みの資格情報として使用された場合のユーザーの電子メールも含まれます。パスワードは送信されません。複数の値を持つ属性の場合、値はコンマ区切りの文字列として送信されます。次の HTTP 要求は、Microsoft Entra が REST API を呼び出す方法を示しています。

POST https://example.azureWebsites.net/api/functionName

Content-Type: application/json

[Request payload]

次の JSON ドキュメントでは、要求ペイロードの例を示します。

{
  "type": "microsoft.graph.authenticationEvent.attributeCollectionSubmit",
  "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/<resourceAppguid>",
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitCalloutData",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "authenticationEventListenerId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "customAuthenticationExtensionId": "11112222-bbbb-3333-cccc-4444dddd5555",
    "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"
        }
    },
    "userSignUpInfo": {
      "attributes": {
        "givenName": {
          "@odata.type": "microsoft.graph.stringDirectoryAttributeValue",
          "value": "Larissa Price",
          "attributeType": "builtIn"
        },
        "companyName": {
          "@odata.type": "microsoft.graph.stringDirectoryAttributeValue",
          "value": "Contoso University",
          "attributeType": "builtIn"
        },
        "extension_<appid>_universityGroups": {
          "@odata.Type": "microsoft.graph.stringDirectoryAttributeValue",
          "value": "Alumni,Faculty",
          "attributeType": "directorySchemaExtension"
        },
        "extension_<appid>_graduationYear": {
          "@odata.type": "microsoft.graph.int64DirectoryAttributeValue",
          "value": 2010,
          "attributeType": "directorySchemaExtension"
        },
        "extension_<appid>_onMailingList": {
          "@odata.type": "microsoft.graph.booleanDirectoryAttributeValue",
          "value": false,
          "attributeType": "directorySchemaExtension"
        }
      },
      "identities": [
        {
          "signInType": "email",
          "issuer": "contoso.onmicrosoft.com",
          "issuerAssignedId": "larissa.price@contoso.onmicrosoft.com"
        }
      ]
    }
  }
}

外部 REST API からの応答

応答値の型は、要求値の型と一致します。次に例を示します。

要求にgraduationYearの@odata.typeを持つ属性int64DirectoryAttributeValueが含まれている場合、応答には、graduationYearなどの整数値を持つ2010属性を含める必要があります。
要求にコンマ区切り文字列として指定された複数の値を持つ属性が含まれている場合、応答にはコンマ区切り文字列の値が含まれている必要があります。

Microsoft Entra ID は、次の形式の REST API 応答を受け取ります。

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

HTTP 応答で、次のいずれかの JSON ドキュメントを指定します。 continueWithDefaultBehavior アクションは、外部 REST API が継続応答を返していることを指定します。

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.continueWithDefaultBehavior"
      }
    ]
  }
}

modifyAttributeValues アクションは、属性の収集後に、外部 REST API が属性を変更し、既定値でオーバーライドする応答を返すように指定します。 REST API で新しい属性を追加することはできません。返されるが、属性コレクションの一部ではない追加の属性は無視されます。

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.modifyAttributeValues",
        "attributes": {
          "key1": "value1,value2,value3",
          "key2": true
        }
      }
    ]
  }
}

showBlockPage アクションは、外部 REST API がブロック応答を返していることを指定します。

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.showBlockPage",
        "title": "Hold tight...",
        "message": "Your access request is already processing. You'll be notified when your request has been approved."
      }
    ]
  }
}

showValidationError アクションは、REST API が検証エラーと適切なメッセージと状態コードを返していることを指定します。

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.showValidationError",
        "message": "Please fix the below errors to proceed.",
        "attributeErrors": {
          "city": "City cannot contain any numbers",
          "extension_<appid>_graduationYear": "Graduation year must be at least 4 digits"
        }
      }
    ]
  }
}

次の方法で共有

OnAttributeCollectionSubmit イベントからデータを取得して返す

REST API スキーマ

外部 REST API への要求

外部 REST API からの応答

フィードバック

その他のリソース