Hinzufügen eines benutzerdefinierten Genehmigungsworkflows zur Self-Service-Registrierung

  • Artikel

Mit API-Connectors können Sie Ihre eigenen benutzerdefinierten Genehmigungsworkflows in die Self-Service-Registrierung integrieren, sodass Sie verwalten können, welche Gastbenutzerkonten in Ihrem Mandanten erstellt werden.

Dieser Artikel enthält ein Beispiel für die Integration in ein Genehmigungssystem. In diesem Beispiel sammelt der Benutzerflow der Self-Service-Registrierung während des Registrierungsvorgangs Benutzerdaten und übergibt sie an Ihr Genehmigungssystem. Anschließend kann das Genehmigungssystem folgende Aktionen ausführen:

  • Genehmigen Sie den Benutzer automatisch und erlauben Sie Microsoft Entra ID, das Benutzerkonto zu erstellen.
  • Eine manuelle Überprüfung auslösen. Wenn die Anforderung genehmigt wird, verwendet das Genehmigungssystem Microsoft Graph zur Bereitstellung des Benutzerkontos. Das Genehmigungssystem kann den Benutzer auch darüber benachrichtigen, dass sein Konto erstellt wurde.

Wichtig

Registrieren einer Anwendung für Ihr Genehmigungssystem

Tipp

Die Schritte in diesem Artikel können je nach dem Portal, mit dem Sie beginnen, geringfügig variieren.

Sie müssen Ihr Genehmigungssystem als Anwendung in Ihrem Microsoft Entra-Mandanten registrieren, damit es sich mit Microsoft Entra ID authentifizieren und über die Berechtigung zum Erstellen von Benutzern verfügen kann. Erfahren Sie mehr über Grundlagen zu Authentifizierung und Autorisierung für Microsoft Graph.

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Benutzeradministrator an.
  2. Navigieren Sie zu Identität>Anwendungen>App-Registrierungen, und wählen Sie dann Neue Registrierung aus.
  3. Geben Sie einen Namen für die Anwendung ein, z. B. Registrierungsgenehmigungen.
  4. Wählen Sie Registrieren. Sie können bei anderen Feldern die Standardwerte beibehalten.

Screenshot: Hervorgehobene Schaltfläche „Registrieren“

  1. Wählen Sie unter Verwalten im linken Menü API-Berechtigungen und dann Berechtigung hinzufügen aus.
  2. Wählen Sie auf der Seite API-Berechtigungen anfordern die Option Microsoft Graph aus, und wählen Sie Anwendungsberechtigungen aus.
  3. Erweitern Sie unter Berechtigungen auswählen den Eintrag Benutzer, und aktivieren Sie dann das Kontrollkästchen User.ReadWrite.All. Diese Berechtigung ermöglicht dem Genehmigungssystem, den Benutzer nach der Genehmigung zu erstellen. Klicken Sie dann auf Berechtigungen hinzufügen.

Screenshot: Anfordern von API-Berechtigungen.

  1. Wählen Sie auf der Seite API-Berechtigungen die Option Administratorzustimmung für (Ihr Mandantenname) erteilen und dann Ja.
  2. Wählen Sie im linken Menü unter Verwalten die Option Zertifikate & Geheimnisse und anschließend Neuer geheimer Clientschlüssel aus.
  3. Geben Sie eine Beschreibung für das Geheimnis ein, z. B. Genehmigungen für geheimen Clientschlüssel, und wählen Sie den Zeitraum bis zum Ablauf des geheimen Clientschlüssels mit einem Eintrag in Läuft ab. Wählen Sie anschließend Hinzufügen.
  4. Kopieren Sie den Wert des geheimen Clientschlüssels. Werte von geheimen Clientschlüsseln können nur unmittelbar nach der Erstellung angezeigt werden. Speichern Sie das Geheimnis nach der Erstellung unbedingt, bevor Sie die Seite verlassen.

Screenshot: Kopieren des geheimen Clientschlüssels.

  1. Konfigurieren Sie das Genehmigungssystem für die Verwendung der Anwendungs-ID als Client-ID und des geheimen Clientschlüssels, den Sie für die Authentifizierung mit Microsoft Entra ID generiert haben.

Erstellen der API-Connectors

Als nächstes erstellen Sie die API-Connectors für ihren Self-Service-Registrierungs-Benutzerflow. Ihre Genehmigungssystem-API benötigt zwei Connectors und entsprechende Endpunkte, wie im folgenden Beispiel gezeigt. Diese API-Connectors führen folgende Aktionen aus:

  • Genehmigungsstatus überprüfen. Senden Sie sofort nach der Anmeldung eines Benutzers mit einem Identitätsanbieter einen Aufruf an das Genehmigungssystem, um zu überprüfen, ob der Benutzer über eine Genehmigungsanforderung verfügt oder bereits abgelehnt wurde. Wenn Ihr Genehmigungssystem nur automatische Genehmigungsentscheidungen durchführt, ist dieser API-Connector möglicherweise nicht erforderlich. Beispiel für API-Connector „Genehmigungsstatus überprüfen“.

Screenshot: Genehmigungsstatus überprüfen – API-Connector-Konfiguration.

  • Genehmigung anfordern: Senden Sie einen Aufruf an das Genehmigungssystem, nachdem ein Benutzer die Attributsammlungseite abgeschlossen hat, aber bevor das Benutzerkonto erstellt wird, um die Genehmigung anzufordern. Die Genehmigungsanforderung kann automatisch erteilt oder manuell überprüft werden. Beispiel für API-Conncector „Genehmigung anfordern“.

Screenshot: Genehmigung anfordern – API-Connector-Konfiguration.

Befolgen Sie zum Erstellen dieser Connectors die Schritte in Erstellen eines API-Connectors.

Aktivieren der API-Connectors in einem Benutzerflow

Nun fügen Sie die API-Connectors mit folgenden Schritten einem Self-Service-Registrierungs-Benutzerflow hinzu:

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Benutzeradministrator an.

  2. Navigieren Sie zu Identität>Externe Identitäten>Benutzerflows, und wählen Sie dann den Benutzerflow aus, für den Sie den API-Connector aktivieren möchten.

  3. Wählen Sie mit folgenden Schritte API-Connectors aus und dann die API-Endpunkte, die Sie im Benutzerflow aufrufen möchten:

    • Nach dem Verbund mit einem Identitätsanbieter während der Registrierung: Wählen Sie den API-Connector für den Genehmigungsstatus aus, z. B. Genehmigungsstatus überprüfen.
    • Vor dem Erstellen des Benutzers: Wählen Sie den API-Connector für Ihre Genehmigungsanforderung aus, z. B. Genehmigung anfordern.

Screenshot: API-Connector in einem Benutzerflow.

  1. Wählen Sie Speichern aus.

Steuern des Registrierungsflows mit API-Antworten

Das Genehmigungssystem kann seine Antworten verwenden, wenn es zum Steuern des Registrierungsflows aufgerufen wird.

Anforderung und Antworten für den API-Connector „Genehmigungsstatus überprüfen“

Beispiel für die Anforderung, die von der API über den API-Connector „Genehmigungsstatus überprüfen“ empfangen wurde:

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ //Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

Die genauen Ansprüche, die an die API gesendet werden, hängen von den Informationen ab, die vom Identitätsanbieter bereitgestellt werden. „Email“ wird immer gesendet.

Fortsetzungsantwort für „Genehmigungsstatus überprüfen“

Der Genehmigungsstatus überprüfen-API-Endpunkt sollte unter folgender Voraussetzung eine Fortsetzungsantwort zurückgeben:

  • Der Benutzer hat zuvor keine Genehmigung angefordert.

Beispiel für eine Fortsetzungsantwort:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue"
}

Blockierungsantwort für „Genehmigungsstatus überprüfen“

Der Genehmigungsstatus überprüfen-API-Endpunkt sollte unter folgender Voraussetzung eine Blockierungsantwort zurückgeben:

  • Die Benutzergenehmigung steht aus.
  • Der Benutzer wurde abgelehnt und er sollte die Genehmigung nicht erneut anfordern dürfen.

Nachfolgend finden Sie Beispiele für Blockierungsantworten:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your access request is already processing. You'll be notified when your request has been approved.",
}

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}

Anforderung und Antworten für den API-Connector „Genehmigung anfordern“

Beispiel für eine HTTP-Anforderung, die von der API über den API-Connector „Genehmigung anfordern“ empfangen wurde:

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Die genauen Ansprüche, die an die API gesendet werden, hängen von den Informationen ab, die vom Benutzer gesammelt oder vom Identitätsanbieter bereitgestellt werden.

Fortsetzungsantwort für „Genehmigung anfordern“

Der Genehmigung anfordern-API-Endpunkt sollte unter folgenden Voraussetzungen eine Fortsetzungsantwort zurückgeben:

  • Der Benutzer kann automatisch genehmigt werden.

Beispiel für eine Fortsetzungsantwort:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue"
}

Wichtig

Wenn eine Fortsetzungsantwort empfangen wird, erstellt Microsoft Entra ID ein Benutzerkonto und leitet den Benutzer an die Anwendung weiter.

Blockierungsantwort für „Genehmigung anfordern“

Der Genehmigung anfordern-API-Endpunkt sollte unter folgenden Voraussetzungen eine Blockierungsantwort zurückgeben:

  • Eine Benutzergenehmigungsanforderung wurde erstellt und steht nun aus.
  • Eine Benutzergenehmigungsanforderung wurde automatisch abgelehnt.

Nachfolgend finden Sie Beispiele für Blockierungsantworten:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your account is now waiting for approval. You'll be notified when your request has been approved.",
}

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}

Die userMessage in der Antwort wird dem Benutzer angezeigt, z. B.:

Beispielseite für ausstehende Genehmigung

Erstellung eines Benutzerkontos nach manueller Genehmigung

Nachdem das benutzerdefinierte Genehmigungssystem die manuelle Genehmigung erhält, erstellt es ein Benutzer-Konto mithilfe von Microsoft Graph. Wie das Genehmigungssystem das Benutzerkonto bereitstellt, hängt von dem Identitätsanbieter ab, der vom Benutzer verwendet wurde.

Für Verbundbenutzer von Google oder Facebook und einmalige Passcode per E-Mail

Wichtig

Das Genehmigungssystem muss explizit überprüfen, ob identities, identities[0] und identities[0].issuer vorhanden sind und dass identities[0].issuer „facebook“, „google“ oder „mail“ entspricht, damit diese Methode verwendet werden kann.

Wenn Ihr Benutzer sich mit einem Google- oder Facebook-Konto oder mit einem einmaligen Passcode per E-Mail angemeldet hat, können Sie die Benutzererstellungs-API verwenden.

  1. Das Genehmigungssystem verwendet die HTTP-Anforderung aus dem Benutzerflow.
POST <Approvals-API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@outlook.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
 "ui_locales":"en-US"
}
  1. Das Genehmigungssystem verwendet Microsoft Graph, um ein Benutzerkonto zu erstellen.
POST https://graph.microsoft.com/v1.0/users
Content-type: application/json

{
 "userPrincipalName": "johnsmith_outlook.com#EXT@contoso.onmicrosoft.com",
 "accountEnabled": true,
 "mail": "johnsmith@outlook.com",
 "userType": "Guest",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value"
}
Parameter Erforderlich BESCHREIBUNG
userPrincipalName Ja Kann generiert werden, indem in dem an die API gesendeten email-Anspruch das @-Zeichen durch _ ersetzt wird und er #EXT@<tenant-name>.onmicrosoft.com vorangestellt wird.
accountEnabled Ja Muss auf true festgelegt sein.
mail Ja Entspricht dem an die API gesendeten email-Anspruch.
userType Ja Muss Guestlauten. Weist diesen Benutzer als Gastbenutzer aus.
Identitäten Ja Die Verbundidentitätsinformationen.
<otherBuiltInAttribute> Nein Andere integrierte Attribute wie displayName, city und andere. Parameternamen sind identisch mit den vom API-Connector gesendeten Parametern.
<extension_{extensions-app-id}_CustomAttribute> Nein Benutzerdefinierte Attribute über den Benutzer. Parameternamen sind identisch mit den vom API-Connector gesendeten Parametern.

Für einen verbundenen Microsoft Entra-Benutzer oder einen Microsoft-Kontobenutzer

Wenn ein Benutzer sich mit einem verbundenen Microsoft Entra-Konto oder einem Microsoft-Konto anmeldet, müssen Sie die Einladungs-API verwenden, um den Benutzer zu erstellen und ihm dann optional mit der API zur Benutzeraktualisierung weitere Attribute zuweisen.

  1. Das Genehmigungssystem empfängt die HTTP-Anforderung aus dem Benutzerflow.
POST <Approvals-API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
 "ui_locales":"en-US"
}
  1. Das Genehmigungssystem erstellt die Einladung mithilfe der vom API-Connector bereitgestellten email.
POST https://graph.microsoft.com/v1.0/invitations
Content-type: application/json

{
    "invitedUserEmailAddress": "johnsmith@fabrikam.onmicrosoft.com",
    "inviteRedirectUrl" : "https://myapp.com"
}

Beispielanwort:

HTTP/1.1 201 OK
Content-type: application/json

{
    ...
    "invitedUser": {
        "id": "<generated-user-guid>"
    }
}
  1. Das Genehmigungssystem aktualisiert mit der ID des eingeladenen Benutzers das Konto des Benutzers mit den gesammelten Benutzerattributen (optional).
PATCH https://graph.microsoft.com/v1.0/users/<generated-user-guid>
Content-type: application/json

{
    "displayName": "John Smith",
    "city": "Redmond",
    "extension_<extensions-app-id>_AttributeName": "custom attribute value"
}

Nächste Schritte