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

Platí pro: Tenanti pracovních sil – externí tenanti (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. OnAttributeCollectionStart událost nastane na začátku kroku kolekce atributů před vykreslení stránky kolekce atributů. Tato událost umožňuje definovat akce před shromažďováním atributů od uživatele. Můžete například zablokovat, aby uživatel pokračoval v toku registrace na základě federované identity nebo e-mailu nebo předvyplnění atributů se zadanými hodnotami. Můžete nakonfigurovat následující akce:

• continueWithDefaultBehavior – vykreslí stránku kolekce atributů obvyklým způsobem.
• setPreFillValues – atributy předběžného vyplňování ve formuláři pro registraci
• showBlockPage – Zobrazí chybovou zprávu a zablokuje uživatele v registraci.

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

Tip

Pokud si chcete tuto funkci vyzkoušet, přejděte do ukázky potravin Woodgrove a spusťte případ použití "Předem vyplní atributy registrace".

Schéma rozhraní REST API

K vývoji vlastního rozhraní REST API pro počáteční událost shromažďování 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í.

Atributy v počátečním požadavku obsahují výchozí hodnoty. U atributů s více hodnotami se hodnoty odesílají jako řetězec oddělený čárkami. Vzhledem k tomu, že atributy se od uživatele ještě neshromažďovaly, většina atributů nebude mít přiřazené hodnoty.

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

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

Akce setPrefillValues určuje, že externí rozhraní REST API vrací odpověď na předvyplnění atributů s výchozími hodnotami. 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.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.setPrefillValues",
        "inputs": {
          "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.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."
      }
    ]
  }
}