Abrufen und Zurückgeben von Daten aus einem OnAttributeCollectionStart-Ereignis

Gilt für: Externe Mandanten (weitere Informationen)

Um den Anmeldevorgang für Ihre Self-Service-Anmeldevorgänge für Kunden zu ändern, können Sie ein benutzerdefiniertes Authentifizierungsmodul erstellen und es an bestimmten Punkten im Benutzerablauf aufrufen. Das OnAttributeCollectionStart-Ereignis tritt am Anfang des Attributauflistungsschritts auf, bevor die Attributauflistungsseite gerendert wird. Mit diesem Ereignis können Sie Aktionen definieren, bevor Attribute vom Benutzer erfasst werden. Sie können z. B. verhindern, dass ein Benutzer den Registrierungsablauf basierend auf seiner Verbundidentität oder E-Mail fortsetzt oder Attribute mit angegebenen Werten vorfüllt. Die folgenden Aktionen können konfiguriert werden:

• continueWithDefaultBehavior – Rendern Sie die Attributsammlungsseite wie gewohnt.
• setPreFillValues – Vorfüllattribute im Registrierungsformular.
• showBlockPage – Zeigen Sie eine Fehlermeldung an, und blockieren Sie die Registrierung des Benutzers.

In diesem Artikel wird das REST-API-Schema für das OnAttributeCollectionStart-Ereignis beschrieben. (Siehe auch den zugehörigen Artikel Custom Extension for OnAttributeCollectionSubmit event.)

REST-API-Schema

Verwenden Sie den folgenden REST-API-Datenvertrag, um eine eigene REST-API für das Startereignis der Attributsammlung zu entwickeln. Das Schema beschreibt den Vertrag zum Entwerfen des Anforderungs- und Antworthandlers.

Ihre benutzerdefinierte Authentifizierungserweiterung in Microsoft Entra ID führt einen HTTP-Aufruf ihrer REST-API mit einer JSON-Nutzlast durch. Die JSON-Nutzlast enthält Benutzerprofildaten, Authentifizierungskontextattribute und Informationen zur Anwendung, bei der sich der Benutzer anmelden möchte. Die JSON-Attribute können verwendet werden, um zusätzliche Logik von Ihrer API auszuführen.

Anforderung an die externe REST-API

Die Anforderung an Ihre REST-API befindet sich im unten gezeigten Format. In diesem Beispiel enthält die Anforderung Benutzeridentitätsinformationen sowie integrierte Attribute (givenName und companyName) und benutzerdefinierte Attribute (universityGroups, graduationYear und onMailingList).

Die Anforderung enthält die Benutzerattribute, die im Benutzerablauf für die Sammlung während der Self-Service-Registrierung ausgewählt sind, einschließlich integrierter Attribute (z. B. givenName und companyName) und benutzerdefinierter Attribute, die bereits definiert wurden (z. B. universityGroups, graduationYear und onMailingList). Ihre REST-API kann keine neuen Attribute hinzufügen.

Die Anforderung enthält auch Benutzeridentitäten, einschließlich der E-Mail-Adresse des Benutzers, wenn sie als überprüfte Anmeldeinformationen für die Registrierung verwendet wurde. Das Kennwort wird nicht gesendet.

Attribute in der Startanforderung enthalten ihre Standardwerte. Bei Attributen mit mehreren Werten werden die Werte als durch Trennzeichen getrennte Zeichenfolge gesendet. Da Attribute noch nicht vom Benutzer erfasst wurden, werden den meisten Attributen keine Werte zugewiesen. Die folgende HTTP-Anforderung veranschaulicht, wie Microsoft Entra Ihre REST-API aufruft.

POST https://example.azureWebsites.net/api/functionName

Content-Type: application/json

[Request payload]

Das folgende JSON-Dokument stellt ein Beispiel für eine Anforderungsnutzlast bereit:

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

Antwort von der externen REST-API

Die Antwortwerttypen entsprechen den Anforderungswerttypen, z. B.:

• Wenn die Anforderung ein Attribut graduationYear mit einer @odata.type von int64DirectoryAttributeValue enthält, sollte die Antwort ein graduationYear Attribut mit einem ganzzahligen Wert enthalten, z. B. 2010.
• Wenn die Anforderung ein Attribut mit mehreren Werten enthält, die als durch Trennzeichen getrennte Zeichenfolge angegeben sind, sollte die Antwort die Werte in einer durch Trennzeichen getrennten Zeichenfolge enthalten.

Die Microsoft Entra-ID erwartet eine REST-API-Antwort im folgenden Format.

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

Geben Sie in der HTTP-Antwort eines der folgenden JSON-Dokumente an. Die continueWithDefaultBehavior-Aktion gibt an, dass Ihre externe REST-API eine Fortsetzungsantwort zurückgibt.

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

Die SetPrefillValues-Aktion gibt an, dass die externe REST-API eine Antwort auf Vorausfüllattribute mit Standardwerten zurückgibt. Ihre REST-API kann keine neuen Attribute hinzufügen. Alle zusätzlichen Attribute, die zurückgegeben werden, aber nicht Teil der Attributauflistung sind, werden ignoriert.

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.setPrefillValues",
        "inputs": {
          "key1": "value1,value2,value3",
          "key2": true
        }
      }
    ]
  }
}

Die ShowBlockPage-Aktion gibt an, dass Ihre externe REST-API eine blockierende Antwort zurückgibt.

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.showBlockPage",
        "title": "Hold tight...",
        "message": "Your access request is already processing. You'll be notified when your request has been approved."
      }
    ]
  }
}