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

2025-06-26

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

顧客のセルフサービスサインアップユーザーフローのサインアップエクスペリエンスを変更するには、カスタム認証拡張機能を作成し、ユーザーフロー内の特定のポイントで呼び出します。 OnAttributeCollectionStart イベントは、属性コレクションページがレンダリングされる前に、属性コレクションステップの開始時に発生します。このイベントを使用すると、ユーザーから属性を収集する前にアクションを定義できます。たとえば、ユーザーがフェデレーション ID または電子メールに基づいてサインアップフローを続行するのをブロックしたり、指定した値を持つ属性を事前入力したりできます。次のアクションを構成できます。

continueWithDefaultBehavior - 属性コレクションページを通常どおりにレンダリングします。
setPreFillValues - サインアップフォームの事前入力属性。
showBlockPage - エラーメッセージを表示し、ユーザーのサインアップをブロックします。

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

ヒント

この機能を試すには、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.attributeCollectionStart",
  "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/<resourceAppguid>",
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartCalloutData",
    "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.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.continueWithDefaultBehavior"
      }
    ]
  }
}

setPrefillValues アクションは、外部 REST API が既定値を持つプリフィル属性への応答を返すように指定します。 REST API で新しい属性を追加することはできません。返されるが、属性コレクションの一部ではない追加の属性は無視されます。

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.setPrefillValues",
        "inputs": {
          "key1": "value1,value2,value3",
          "key2": true
        }
      }
    ]
  }
}

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

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

次の方法で共有

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

REST API スキーマ

外部 REST API への要求

外部 REST API からの応答

フィードバック

その他のリソース