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

適用於： 員工租用戶 外部租用戶 (深入了解)

若要修改客戶自助式註冊使用者流程的註冊體驗，您可以建立自訂驗證擴充，並在使用者流程中的特定點叫用它。 OnAttributeCollectionStart 事件會在屬性收集步驟的開頭，於屬性收集頁面呈現之前發生。 此事件可讓您先定義動作，再從使用者收集屬性。 例如，您可以封鎖使用者繼續根據其同盟身分識別或電子郵件進行註冊流程，或是以指定的值預先填入屬性。 您可設定下列動作：

• 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)。

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

要求也包含使用者身分識別，如果將電子郵件當成已驗證的註冊認證，還包括使用者的電子郵件。 不會傳送密碼。

開始要求中的屬性包含其預設值。 對於具有多個值的屬性，這些值會以逗號分隔字串的方式傳送。 由於尚未從使用者收集屬性，因此大部分屬性都不會指派值。

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

• 如果要求包含具有 int64DirectoryAttributeValue 之 @odata.type 的屬性 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",
        "title": "Hold tight...",
        "message": "Your access request is already processing. You'll be notified when your request has been approved."
      }
    ]
  }
}