Aangepaste extensie voor OnAttributeCollectionSubmit-gebeurtenisverwijzing (preview)

Van toepassing op:Externe tenantsvan werknemers (meer informatie)

Als u de registratie-ervaring voor uw selfservicegebruikersstromen voor registratie van klanten wilt wijzigen, kunt u een aangepaste verificatie-extensie maken en deze aanroepen op specifieke punten in de gebruikersstroom. De gebeurtenis OnAttributeCollectionSubmit vindt plaats nadat de gebruiker kenmerken invoert en verzendt en kan worden gebruikt om de informatie van de gebruiker te valideren. U kunt bijvoorbeeld een uitnodigingscode of partnernummer valideren, een adresindeling wijzigen, de gebruiker toestaan door te gaan of een validatie- of blokpagina weer te geven. De volgende acties kunnen worden geconfigureerd:

• continueWithDefaultBehavior - Ga verder met de registratiestroom.
• modifyAttributeValues : overschrijf de waarden die de gebruiker heeft ingediend in het aanmeldingsformulier.
• showValidationError : retourneer een fout op basis van de ingediende waarden.
• showBlockPage : een foutbericht weergeven en blokkeren dat de gebruiker zich kan registreren.

In dit artikel wordt het REST API-schema voor de gebeurtenis OnAttributeCollectionSubmit beschreven. (Zie ook het gerelateerde artikel Aangepaste extensie voor onAttributeCollectionStart-gebeurtenis.)

Tip

Als u deze functie wilt uitproberen, gaat u naar de demo Woodgrove Boodschappen en start u de use-case 'Registratiekenmerken valideren' of 'Voorkomen dat een gebruiker doorgaat met het registratieproces'.

REST API-schema

Gebruik het volgende REST API-gegevenscontract om uw eigen REST API te ontwikkelen voor de gebeurtenis voor het indienen van kenmerkenverzamelingen. In het schema wordt het contract beschreven om de aanvraag- en antwoordhandler te ontwerpen.

Uw aangepaste verificatie-extensie in Microsoft Entra-id maakt een HTTP-aanroep naar uw REST API met een JSON-nettolading. De JSON-nettolading bevat gebruikersprofielgegevens, verificatiecontextkenmerken en informatie over de toepassing waarmee de gebruiker zich wil aanmelden. De JSON-kenmerken kunnen worden gebruikt om extra logica uit te voeren door uw API.

Aanvraag voor de externe REST API

De aanvraag voor uw REST API heeft de onderstaande indeling. In dit voorbeeld bevat de aanvraag informatie over gebruikersidentiteiten, samen met ingebouwde kenmerken (givenName en companyName) en aangepaste kenmerken (universityGroups, graduationYear en onMailingList).

De aanvraag bevat de gebruikerskenmerken die zijn geselecteerd in de gebruikersstroom voor verzameling tijdens selfserviceregistratie, inclusief ingebouwde kenmerken (bijvoorbeeld givenName en companyName) en aangepaste kenmerken die al zijn gedefinieerd (bijvoorbeeld universityGroups, afstudeerjaar en onMailingList). Uw REST API kan geen nieuwe kenmerken toevoegen.

De aanvraag bevat ook gebruikersidentiteiten, waaronder het e-mailadres van de gebruiker als deze is gebruikt als geverifieerde referentie voor registratie. Het wachtwoord wordt niet verzonden. Voor kenmerken met meerdere waarden worden de waarden verzonden als een door komma's gescheiden tekenreeks.

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

Antwoord van de externe REST API

Microsoft Entra ID verwacht een REST API-antwoord in de volgende indeling. De antwoordwaardetypen komen overeen met de aanvraagwaardetypen, bijvoorbeeld:

• Als de aanvraag een kenmerk graduationYear met een @odata.type van int64DirectoryAttributeValuebevat, moet het antwoord een graduationYear kenmerk met een geheel getal bevatten, zoals 2010.
• Als de aanvraag een kenmerk bevat met meerdere waarden die zijn opgegeven als een door komma's gescheiden tekenreeks, moet het antwoord de waarden in een door komma's gescheiden tekenreeks bevatten.

De actie continueWithDefaultBehavior geeft aan dat uw externe REST API een vervolgantwoord retourneert.

HTTP/1.1 200 OK

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

De actie modifyAttributeValues geeft aan dat uw externe REST API een antwoord retourneert om kenmerken met standaardwaarden te wijzigen en te overschrijven nadat de kenmerken zijn verzameld. Uw REST API kan geen nieuwe kenmerken toevoegen. Eventuele extra kenmerken die worden geretourneerd, maar die geen deel uitmaken van de kenmerkverzameling, worden genegeerd.

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

De actie showBlockPage geeft aan dat uw externe REST API een blokkerend antwoord retourneert.

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

De actie showValidationError geeft aan dat uw REST API een validatiefout retourneert en een geschikt bericht en statuscode.

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