OnAttributeCollectionStart イベントのカスタム拡張機能のリファレンス (プレビュー)

[アーティクル]
01/23/2024

適用対象: Microsoft Entra 外部 ID の顧客構成

顧客のセルフサービスサインアップユーザーフローのサインアップエクスペリエンスを変更するには、カスタム認証拡張機能を作成し、ユーザーフロー内の特定のポイントで呼び出します。 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 への要求は、以下に示す形式になります。この例では、要求にはユーザー ID 情報と共に、組み込みの属性 (givenName、companyName) とカスタム属性 (universityGroups、graduationYear、onMailingList) が含まれています。

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

要求にはユーザー ID も含まれます。これには、検証済みの資格情報としてサインアップに使用された場合のユーザーのメールアドレスも含まれます。パスワードは送信されません。

開始要求の属性には、既定値が含まれています。複数の値を持つ属性の場合、値はコンマ区切りの文字列として送信されます。属性はまだユーザーから収集されていないため、ほとんどの属性には値が割り当てられていません。

JSON

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

{
  "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 からの応答

Microsoft Entra ID は、次の形式で REST API の応答を受け取ります。応答値の型は、要求値の型と一致します。次に例を示します。

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

continueWithDefaultBehavior アクションは、外部 REST API から継続応答が返されていることを指定します。

HTTP/1.1 200 OK

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

setPrefillValues アクションは、外部 REST API が属性を既定値で事前入力するための応答を返すように指定します。 REST API で新しい属性を追加することはできません。返されるが、属性コレクションの一部ではない追加の属性は無視されます。

HTTP/1.1 200 OK

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

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

HTTP/1.1 200 OK

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

Share via

OnAttributeCollectionStart イベントのカスタム拡張機能のリファレンス (プレビュー)

REST API スキーマ

外部 REST API への要求

JSON

外部 REST API からの応答

その他のリソース