Anpassat tillägg för Händelsereferens för OnAttributeCollectionSubmit (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 OnAttributeCollectionSubmit inträffar efter att användaren har angett och skickat attribut och kan användas för att verifiera informationen som tillhandahålls av användaren. Du kan till exempel verifiera en inbjudningskod eller ett partnernummer, ändra ett adressformat, låta användaren fortsätta eller visa en verifierings- eller blockeringssida. Följande åtgärder kan konfigureras:

• continueWithDefaultBehavior – Fortsätt med registreringsflödet.
• modifyAttributeValues – Skriv över de värden som användaren skickade i registreringsformuläret.
• showValidationError – Returnera ett fel baserat på de inskickade värdena.
• 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 OnAttributeCollectionSubmit. (Se även den relaterade artikeln Anpassat tillägg för OnAttributeCollectionStart-händelse.)

Dricks

Om du vill testa den här funktionen går du till Woodgrove Groceries-demonstrationen och startar användningsfallet "Verifiera registreringsattribut" eller användningsfallet "Blockera en användare från att fortsätta registreringsprocessen".

REST API-schema

Om du vill utveckla ditt eget REST-API för attributsamlingens sändningshä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. För attribut med flera värden skickas värdena som en kommaavgränsad sträng.

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

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

Åtgärden modifyAttributeValues anger att ditt externa REST API returnerar ett svar för att ändra och åsidosätta attribut med standardvärden efter att attributen har samlats in. 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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.modifyAttributeValues",
        "attributes": {
          "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.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."
      }
    ]
  }
}

Åtgärden showValidationError anger att rest-API:et returnerar ett valideringsfel och en lämplig meddelande- och statuskod.

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