Benutzerdefinierte Erweiterung für die OnAttributeCollectionStart-Ereignisreferenz (Preview)

Gilt für: Mitarbeitermandanten Externe Mandanten (weitere Informationen)

Um die Anmeldeoberfläche für Ihre Self-Service-Benutzerabläufe für die Kunden-Self-Service-Registrierung zu ändern, können Sie eine benutzerdefinierte Authentifizierungserweiterung erstellen und an bestimmten Stellen 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 für OnAttributeCollectionSubmit event.)

Tipp

Um dieses Feature auszuprobieren, wechseln Sie zur Woodgrove Groceries Demo, und starten Sie den Anwendungsfall Vorfüllen von Anmeldeattributen.

REST-API-Schema

Um Ihre eigene REST-API für das Ereignis „Start der Attributsammlung“ zu entwickeln, verwenden Sie den folgenden REST-API-Datenvertrag. Das Schema beschreibt den Vertrag zum Entwerfen des Anforderungs- und Antworthandlers.

Ihre benutzerdefinierte Authentifizierungserweiterung in Microsoft Entra ID macht einen HTTP-Aufruf an Ihre REST-API mit einer JSON-Nutzlast. Die JSON-Nutzdaten enthalten Benutzerprofildaten, Authentifizierungskontextattribute und Informationen zu der 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.

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

Antwort von der externen REST-API

Die Microsoft Entra-ID erwartet eine REST-API-Antwort im folgenden Format. Die Antwortwerttypen entsprechen den Anforderungswerttypen, z. B.:

• Wenn die Anforderung ein Attribut graduationYear mit einer @odata.type von int64DirectoryAttributeValueenthä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 continueWithDefaultBehavior-Aktion gibt an, dass Ihre externe REST-API eine Fortsetzungsantwort zurückgibt.

HTTP/1.1 200 OK

{
  "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.

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

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

HTTP/1.1 200 OK

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