OnAttributeCollectionSubmit 事件參考的自訂擴充 (預覽)

發行項
06/24/2024

適用於：具有灰色 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)。

要求包含在自助式註冊期間收集使用者流程選取的使用者屬性，包括內建屬性 (例如 givenName 和 companyName)，以及已定義的自訂屬性 (例如，universityGroups、graduationYear 和 onMailingList)。 REST API 無法新增屬性。

要求也包含使用者身分識別，如果將電子郵件當成已驗證的註冊認證，還包括使用者的電子郵件。不會傳送密碼。對於具有多個值的屬性，這些值會以逗號分隔字串的方式傳送。

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 回應。回應值類型符合要求值類型，例如：

如果要求包含具有 int64DirectoryAttributeValue 之 @odata.type 的屬性 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",
        "title": "Hold tight...",
        "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"
        }
      }
    ]
  }
}

共用方式為

OnAttributeCollectionSubmit 事件參考的自訂擴充 (預覽)

REST API 結構描述

外部 REST API 要求

JSON

來自外部 REST API 的回應

意見反應

其他資源