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

Artikel
04/10/2024

Gilt für: Weißer Kreis mit grauem X. Mitarbeitermandanten Grüner Kreis mit weißem Häkchen. 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 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 für OnAttributeCollectionStart event.)

Tipp

Um dieses Feature auszuprobieren, wechseln Sie zur Woodgrove Groceries-Demo, und starten Sie den Anwendungsfall Anmeldungsattribute überprüfen oder den Anwendungsfall Benutzer daran hindern, den Anmeldevorgang fortzusetzen.

REST-API-Schema

Verwenden Sie den folgenden REST-API-Datenvertrag, um eine eigene REST-API für das Sendeereignis der Attributsammlung zu entwickeln. 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. Bei Attributen mit mehreren Werten werden die Werte als durch Trennzeichen getrennte Zeichenfolge gesendet.

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

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

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

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

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

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

Teilen über