Abrufen und Zurückgeben von Daten aus einem OnAttributeCollectionSubmit-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 OnAttributeCollectionSubmit-Ereignis tritt ein, nachdem der Benutzer Attribute eingibt und übermittelt und kann verwendet werden, um die vom Benutzer bereitgestellten Informationen zu überprüfen. Sie können z. B. einen Einladungscode oder eine Partnernummer überprüfen, ein Adressformat ändern, dem Benutzer erlauben, den Vorgang fortzusetzen oder eine Überprüfungs- oder Blockseite anzuzeigen. Die folgenden Aktionen können konfiguriert werden:

• continueWithDefaultBehavior – Fahren Sie mit dem Registrierungsablauf fort.
• modifyAttributeValues : Überschreiben Sie die Werte, die der Benutzer im Registrierungsformular übermittelt hat.
• showValidationError – Gibt einen Fehler basierend auf den übermittelten Werten zurück.
• showBlockPage – Zeigen Sie eine Fehlermeldung an, und blockieren Sie die Registrierung des Benutzers.

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

REST-API-Schema

Verwenden Sie den folgenden REST-API-Datenvertrag, um eine eigene REST-API für das Übermittlungsevent der Attributsammlung zu erstellen. 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 weist das im folgenden Beispiel gezeigte Format auf. 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 Benutzerfluss zur Erfassung während der Selbstbedienungsregistrierung ausgewählt sind. Enthalten sind integrierte Attribute (z. B. givenName und companyName) und benutzerdefinierte Attribute, die bereits definiert sind (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. Bei Attributen mit mehreren Werten werden die Werte als durch Trennzeichen getrennte Zeichenfolge gesendet. 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.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"
        }
      ]
    }
  }
}

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

Die ModifyAttributeValues-Aktion gibt an, dass Ihre externe REST-API eine Antwort zurückgibt, um Attribute mit Standardwerten zu ändern und außer Kraft zu setzen, nachdem die Attribute gesammelt wurden. 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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.modifyAttributeValues",
        "attributes": {
          "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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.showBlockPage",
        "title": "Hold tight...",
        "message": "Your access request is already processing. You'll be notified when your request has been approved."
      }
    ]
  }
}

Die showValidationError-Aktion gibt an, dass Ihre REST-API einen Überprüfungsfehler und einen entsprechenden Meldungs- und Statuscode zurückgibt.

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