Vlastní rozšíření pro referenční informace o událostech OnAttributeCollectionSubmit (Preview)

Článek
04/10/2024

Platí pro: Bílý kruh se šedým symbolem X. Tenanti pracovních sil – externí tenanti Zelený kruh s bílým symbolem zaškrtnutí (další informace)

Pokud chcete upravit prostředí registrace pro toky uživatelů samoobslužné registrace zákazníka, můžete vytvořit vlastní rozšíření ověřování a vyvolat ho v konkrétních bodech v toku uživatele. Událost OnAttributeCollectionSubmit nastane poté, co uživatel zadá a odešle atributy a lze jej použít k ověření informací poskytovaných uživatelem. Můžete například ověřit kód pozvánky nebo číslo partnera, upravit formát adresy, povolit uživateli pokračovat nebo zobrazit ověřovací nebo blokovou stránku. Můžete nakonfigurovat následující akce:

continueWithDefaultBehavior – pokračujte v postupu registrace.
modifyAttributeValues – přepíše hodnoty, které uživatel odeslal ve formuláři pro registraci.
showValidationError – Vrátí chybu na základě odeslaných hodnot.
showBlockPage – Zobrazí chybovou zprávu a zablokuje uživatele v registraci.

Tento článek popisuje schéma rozhraní REST API pro událost OnAttributeCollectionSubmit. (Viz také související článek Vlastní rozšíření pro událost OnAttributeCollectionStart.)

Tip

Pokud si chcete tuto funkci vyzkoušet, přejděte na ukázku potravin Woodgrove a spusťte případ použití ověření atributů registrace nebo případ použití Blokovat uživateli pokračovat v procesu registrace.

Schéma rozhraní REST API

K vývoji vlastního rozhraní REST API pro událost odeslání kolekce atributů použijte následující kontrakt dat rozhraní REST API. Schéma popisuje kontrakt pro návrh obslužné rutiny požadavku a odpovědi.

Vaše vlastní rozšíření ověřování v Microsoft Entra ID provede volání HTTP do rozhraní REST API s datovou částí JSON. Datová část JSON obsahuje data profilu uživatele, atributy kontextu ověřování a informace o aplikaci, ke které se chce uživatel přihlásit. Atributy JSON je možné použít k provedení další logiky rozhraní API.

Požadavek na externí rozhraní REST API

Požadavek na vaše rozhraní REST API je ve formátu uvedeném níže. V tomto příkladu požadavek obsahuje informace o identitách uživatelů spolu s integrovanými atributy (givenName a companyName) a vlastními atributy (universityGroups, graduationYear a onMailingList).

Požadavek obsahuje atributy uživatele, které jsou vybrány v toku uživatele pro shromažďování během samoobslužné registrace, včetně předdefinovaných atributů (například givenName a companyName) a vlastních atributů, které už byly definovány (například universityGroups, graduationYear a onMailingList). Vaše rozhraní REST API nemůže přidat nové atributy.

Žádost obsahuje také identity uživatelů, včetně e-mailu uživatele, pokud se použilo jako ověřené přihlašovací údaje k registraci. Heslo se neodesílají. U atributů s více hodnotami se hodnoty odesílají jako řetězec oddělený čárkami.

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

Odpověď z externího rozhraní REST API

Microsoft Entra ID očekává odpověď rozhraní REST API v následujícím formátu. Typy hodnot odpovědí odpovídají typům hodnot požadavku, například:

Pokud požadavek obsahuje atribut graduationYear s hodnotou int64DirectoryAttributeValue@odata.type of , odpověď by měla obsahovat graduationYear atribut s celočíselnou hodnotou, například 2010.
Pokud požadavek obsahuje atribut s více hodnotami zadanými jako řetězec oddělený čárkami, odpověď by měla obsahovat hodnoty v řetězci s oddělovači.

Akce continueWithDefaultBehavior určuje, že vaše externí rozhraní REST API vrací odpověď na pokračování.

HTTP/1.1 200 OK

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

Akce modifyAttributeValues určuje, že vaše externí rozhraní REST API vrátí odpověď na úpravy a přepsání atributů s výchozími hodnotami po shromáždění atributů. Vaše rozhraní REST API nemůže přidat nové atributy. Všechny další atributy, které se vrátí, ale které nejsou součástí kolekce atributů, budou ignorovány.

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

Akce showBlockPage určuje, že vaše externí rozhraní REST API vrací blokující odpověď.

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

Akce showValidationError určuje, že vaše rozhraní REST API vrací chybu ověření a odpovídající zprávu a stavový kód.

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

Sdílet prostřednictvím