Estensione personalizzata per OnAttributeCollectionSubmit (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 OnAttributeCollectionSubmit si verifica dopo che l'utente immette e invia attributi e può essere usato per convalidare le informazioni fornite dall'utente. Ad esempio, è possibile convalidare un codice di invito o un numero di partner, modificare un formato di indirizzo, consentire all'utente di continuare o visualizzare una pagina di convalida o blocco. È possibile configurare le azioni seguenti:

• continueWithDefaultBehavior : continuare con il flusso di iscrizione.
• modifyAttributeValues : sovrascrivere i valori inviati dall'utente nel modulo di iscrizione.
• showValidationError : restituisce un errore in base ai valori inviati.
• showBlockPage : mostra un messaggio di errore e impedisce all'utente di iscriversi.

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

Suggerimento

Per provare questa funzionalità, passare alla demo di Woodgrove Groceries e avviare il caso d'uso "Convalidare gli attributi di iscrizione" oppure il caso d'uso "Impedisci a un utente di continuare il processo di iscrizione".

Schema dell'API REST

Per sviluppare un'API REST personalizzata per l'evento di invio 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. Per gli attributi con più valori, i valori vengono inviati come stringa delimitata da virgole.

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

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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.continueWithDefaultBehavior"
      }
    ]
  }
}

L'azione modifyAttributeValues specifica che l'API REST esterna restituisce una risposta per modificare ed eseguire l'override degli attributi con valori predefiniti dopo la raccolta degli attributi. 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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.modifyAttributeValues",
        "attributes": {
          "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.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."
      }
    ]
  }
}

L'azione showValidationError specifica che l'API REST restituisce un errore di convalida e un messaggio e un codice di stato appropriato.

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