Riferimento all'evento Custom Extension for OnAttributeCollectionStart (anteprima)

Si applica a: Tenant esterni della forza lavoro (altre informazioni)

Per modificare l'esperienza di iscrizione per i flussi utente di iscrizione self-service dei clienti, è possibile creare un'estensione di autenticazione personalizzata e richiamarla in punti specifici nel flusso utente. L'evento OnAttributeCollectionStart si verifica all'inizio del passaggio della raccolta di attributi prima del rendering della pagina della raccolta di attributi. Questo evento consente di definire azioni prima che gli attributi vengano raccolti dall'utente. Ad esempio, è possibile impedire a un utente di continuare il flusso di iscrizione in base all'identità federata o al messaggio di posta elettronica oppure precompilare gli attributi con i valori specificati. È possibile configurare le azioni seguenti:

• continueWithDefaultBehavior : eseguire il rendering della pagina della raccolta di attributi come di consueto.
• setPreFillValues : precompilare gli attributi nel modulo di iscrizione.
• showBlockPage : mostra un messaggio di errore e impedisce all'utente di iscriversi.

Questo articolo descrive lo schema dell'API REST per l'evento OnAttributeCollectionStart. Vedere anche l'articolo correlatoEstensione personalizzata per l'evento OnAttributeCollectionSubmit.

Suggerimento

Per provare questa funzionalità, passare alla demo di Woodgrove Groceries e avviare il caso d'uso "Prepopulate sign-up attributes".

Schema dell'API REST

Per sviluppare un'API REST personalizzata per l'evento di avvio della raccolta di attributi, usare il contratto dati DELL'API REST seguente. Lo schema descrive il contratto per progettare il gestore di richiesta e risposta.

L'estensione di autenticazione personalizzata in Microsoft Entra ID effettua una chiamata HTTP all'API REST con un payload JSON. Il payload JSON contiene dati del profilo utente, attributi del contesto di autenticazione e informazioni sull'applicazione a cui l'utente vuole accedere. Gli attributi JSON possono essere usati per eseguire logica aggiuntiva dall'API.

Richiesta all'API REST esterna

La richiesta all'API REST è nel formato illustrato di seguito. In questo esempio, la richiesta include informazioni sulle identità utente insieme agli attributi predefiniti (givenName e companyName) e agli attributi personalizzati (universityGroups, graduationYear e onMailingList).

La richiesta contiene gli attributi utente selezionati nel flusso utente per la raccolta durante l'iscrizione self-service, inclusi gli attributi predefiniti (ad esempio, givenName e companyName) e gli attributi personalizzati già definiti , ad esempio universityGroups, graduationYear e onMailingList. L'API REST non può aggiungere nuovi attributi.

La richiesta contiene anche le identità utente, incluso il messaggio di posta elettronica dell'utente, se è stato usato come credenziale verificata per l'iscrizione. La password non viene inviata.

Gli attributi nella richiesta di avvio contengono i valori predefiniti. Per gli attributi con più valori, i valori vengono inviati come stringa delimitata da virgole. Poiché gli attributi non sono ancora stati raccolti dall'utente, la maggior parte degli attributi non avrà valori assegnati.

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

Risposta dall'API REST esterna

Microsoft Entra ID prevede una risposta api REST nel formato seguente. I tipi di valore della risposta corrispondono ai tipi di valore della richiesta, ad esempio:

• Se la richiesta contiene un attributo graduationYear con un @odata.type di int64DirectoryAttributeValue, la risposta deve includere un graduationYear attributo con un valore intero, ad esempio 2010.
• Se la richiesta contiene un attributo con più valori specificati come stringa delimitata da virgole, la risposta deve contenere i valori in una stringa delimitata da virgole.

L'azione continueWithDefaultBehavior specifica che l'API REST esterna restituisce una risposta di continuazione.

HTTP/1.1 200 OK

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

L'azione setPrefillValues specifica che l'API REST esterna restituisce una risposta agli attributi di precompilato con valori predefiniti. L'API REST non può aggiungere nuovi attributi. Tutti gli attributi aggiuntivi restituiti ma che non fanno parte della raccolta di attributi vengono ignorati.

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

L'azione showBlockPage specifica che l'API REST esterna restituisce una risposta di blocco.

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