Aangepaste extensie voor OnAttributeCollectionStart-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 OnAttributeCollectionStart vindt plaats aan het begin van de stap voor het verzamelen van kenmerken, voordat de pagina voor het verzamelen van kenmerken wordt weergegeven. Met deze gebeurtenis kunt u acties definiëren voordat kenmerken van de gebruiker worden verzameld. U kunt bijvoorbeeld voorkomen dat een gebruiker doorgaat met de registratiestroom op basis van hun federatieve identiteit of e-mail, of kenmerken vooraf invullen met opgegeven waarden. De volgende acties kunnen worden geconfigureerd:

• continueWithDefaultBehavior : geef de pagina van de kenmerkverzameling weer zoals gebruikelijk.
• setPreFillValues - Prefill attributes in the sign-up form.
• showBlockPage : een foutbericht weergeven en blokkeren dat de gebruiker zich kan registreren.

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

Tip

Als u deze functie wilt uitproberen, gaat u naar de demo Woodgrove Boodschappen en start u de use case 'Vooraf ingevulde registratiekenmerken'.

REST API-schema

Gebruik het volgende REST API-gegevenscontract om uw eigen REST API te ontwikkelen voor de begin-gebeurtenis van de kenmerkverzameling. 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.

Kenmerken in de startaanvraag bevatten hun standaardwaarden. Voor kenmerken met meerdere waarden worden de waarden verzonden als een door komma's gescheiden tekenreeks. Omdat er nog geen kenmerken van de gebruiker zijn verzameld, hebben de meeste kenmerken geen waarden toegewezen.

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

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

De actie SetPrefillValues geeft aan dat de externe REST API een antwoord retourneert om kenmerken vooraf in te vullen met standaardwaarden. 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.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.setPrefillValues",
        "inputs": {
          "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.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."
      }
    ]
  }
}