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

[アーティクル]
04/10/2024

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

顧客のセルフサービスサインアップユーザーフローのサインアップエクスペリエンスを変更するには、カスタム認証拡張機能を作成し、ユーザーフロー内の特定のポイントで呼び出します。 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 への要求は、以下に示す形式になります。この例では、要求にはユーザー 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.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 からの応答

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

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

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

HTTP/1.1 200 OK

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

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

HTTP/1.1 200 OK

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

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

HTTP/1.1 200 OK

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

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

HTTP/1.1 200 OK

{
  "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"
        }
      }
    ]
  }
}

次の方法で共有