Anpassat tillägg för Händelsereferens för OnAttributeCollectionStart (förhandsversion)

Gäller för:Personalklientorganisationer Externa klienter (läs mer)

Om du vill ändra registreringsupplevelsen för kundens användarflöden för självbetjäningsregistrering kan du skapa ett anpassat autentiseringstillägg och anropa det vid specifika platser i användarflödet. Händelsen OnAttributeCollectionStart inträffar i början av attributsamlingssteget innan sidan för attributsamling återges. Med den här händelsen kan du definiera åtgärder innan attribut samlas in från användaren. Du kan till exempel blockera en användare från att fortsätta registreringsflödet baserat på deras federerade identitet eller e-post, eller förfyllnadsattribut med angivna värden. Följande åtgärder kan konfigureras:

• continueWithDefaultBehavior – Rendera attributsamlingssidan som vanligt.
• setPreFillValues – Förfyllningsattribut i registreringsformuläret.
• showBlockPage – Visa ett felmeddelande och blockera användaren från att registrera sig.

I den här artikeln beskrivs REST API-schemat för händelsen OnAttributeCollectionStart. (Se även den relaterade artikeln Anpassat tillägg för onAttributeCollectionSubmit-händelse.)

Dricks

Om du vill prova den här funktionen går du till Woodgrove Groceries-demonstrationen och startar användningsfallet "Prepopulate sign-up attributes".

REST API-schema

Om du vill utveckla ditt eget REST-API för attributsamlingens starthändelse använder du följande REST API-datakontrakt. Schemat beskriver kontraktet för att utforma hanteraren för begäran och svar.

Ditt anpassade autentiseringstillägg i Microsoft Entra ID gör ett HTTP-anrop till rest-API:et med en JSON-nyttolast. JSON-nyttolasten innehåller användarprofildata, autentiseringskontextattribut och information om programmet som användaren vill logga in på. JSON-attributen kan användas för att utföra extra logik av ditt API.

Begäran till det externa REST-API:et

Begäran till rest-API:et är i det format som visas nedan. I det här exemplet innehåller begäran information om användaridentiteter tillsammans med inbyggda attribut (givenName och companyName) och anpassade attribut (universityGroups, graduationYear och onMailingList).

Begäran innehåller de användarattribut som väljs i användarflödet för insamling under självbetjäningsregistrering, inklusive inbyggda attribut (till exempel givenName och companyName) och anpassade attribut som redan har definierats (till exempel universityGroups, graduationYear och onMailingList). Rest-API:et kan inte lägga till nya attribut.

Begäran innehåller också användaridentiteter, inklusive användarens e-post om den användes som en verifierad autentiseringsuppgift för att registrera sig. Lösenordet skickas inte.

Attributen i startbegäran innehåller deras standardvärden. För attribut med flera värden skickas värdena som en kommaavgränsad sträng. Eftersom attribut inte har samlats in från användaren ännu har de flesta attribut inte värden tilldelade.

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

Svar från det externa REST-API:et

Microsoft Entra ID förväntar sig ett REST API-svar i följande format. Svarsvärdetyperna matchar typen av begärandevärde, till exempel:

• Om begäran innehåller ett attribut graduationYear med ett @odata.type av int64DirectoryAttributeValueska svaret innehålla ett graduationYear attribut med ett heltalsvärde, till exempel 2010.
• Om begäran innehåller ett attribut med flera värden som anges som en kommaavgränsad sträng ska svaret innehålla värdena i en kommaavgränsad sträng.

Åtgärden continueWithDefaultBehavior anger att ditt externa REST API returnerar ett fortsättningssvar.

HTTP/1.1 200 OK

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

Åtgärden setPrefillValues anger att det externa REST-API:et returnerar ett svar på förfyllningsattribut med standardvärden. Rest-API:et kan inte lägga till nya attribut. Eventuella extra attribut som returneras men som inte ingår i attributsamlingen ignoreras.

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

Åtgärden showBlockPage anger att ditt externa REST API returnerar ett blockerande svar.

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