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

Gilt für: Mitarbeiter(-)Mandanten (weitere Informationen)

Mit API-Connectors können Sie ihre eigenen benutzerdefinierten Genehmigungsworkflows mit Self-Service-Registrierung integrieren, damit 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.

Registrieren einer Anwendung für Ihr Genehmigungssystem

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 die Authentifizierungs- und Autorisierungsgrundlagen für Microsoft Graph.

1. Melden Sie sich mindestens als Benutzeradministrator beim Microsoft Entra Admin Center an.
2. Navigieren Sie zu Entra ID>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" aus. Sie können bei anderen Feldern die Standardwerte beibehalten.

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 " Microsoft Graph und dann "Anwendungsberechtigungen" aus.
3. Erweitern Sie unter "Berechtigungen auswählen"User, und aktivieren Sie dann das Kontrollkästchen "User.ReadWrite.All". Diese Berechtigung ermöglicht dem Genehmigungssystem, den Benutzer nach der Genehmigung zu erstellen. Wählen Sie dann "Berechtigungen hinzufügen" aus.

9. Wählen Sie auf der Seite "API-Berechtigungen " die Option " Administratorzustimmung für (Ihren Mandantennamen) erteilen" und dann "Ja" aus.
10. Wählen Sie unter "Verwalten " im linken Menü "Zertifikate und Geheime Schlüssel" und dann " Neuer geheimer Clientschlüssel" aus.
11. Geben Sie eine Beschreibung für das Geheimnis ein, z. B. Genehmigungen-Client-Geheimnis, und wählen Sie die Dauer aus, bis das Clientgeheimnis abläuft. Wählen Sie dann "Hinzufügen" aus.
12. 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.

13. Konfigurieren Sie Ihr Genehmigungssystem, um die Anwendungs-ID als Client-ID und den geheimen Clientschlüssel zu verwenden, 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-Registrierungsbenutzerablauf. Ihre Genehmigungssystem-API benötigt zwei Connectors und entsprechende Endpunkte, wie im folgenden Beispiel gezeigt. Diese API-Connectors führen folgende Aktionen aus:

• Überprüfen sie den Genehmigungsstatus. 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“.

• Genehmigung anfordern – Senden Sie einen Aufruf an das Genehmigungssystem, nachdem ein Benutzer die Attributsammlungsseite 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“.

Führen Sie zum Erstellen dieser Connectors die Schritte zum Erstellen eines API-Connectors aus.

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 mindestens als Benutzeradministrator beim Microsoft Entra Admin Center an.

2. Navigieren Sie zu Entra ID>External Identities>User Flows, und wählen Sie dann den Benutzerfluss aus, für den Sie den API-Connector aktivieren möchten.

3. Wählen Sie API-Connectors aus, und wählen Sie dann die API-Endpunkte aus, die Sie in den folgenden Schritten im Benutzerablauf aufrufen möchten:

   • Nach der Föderation mit einem Identitätsanbieter bei der Registrierung: Wählen Sie Ihren Genehmigungsstatus-API-Connector aus, z. B. "Genehmigungsstatus überprüfen".
   • Wählen Sie vor dem Erstellen des Benutzers Ihren API-Connector für die Genehmigungsanforderung aus, z. B. "Genehmigung anfordern".

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. Der Anspruch „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 API-Endpunkt zur Überprüfung des Genehmigungsstatus sollte eine blockierende Antwort zurückgeben, wenn:

• 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 Endpunkt der Anforderungsgenehmigungs-API sollte eine Fortsetzungsantwort zurückgeben, wenn:

• 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 Endpunkt der Anforderungsgenehmigungs-API sollte eine Blockierungsantwort zurückgeben, wenn:

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

Erstellung eines Benutzerkontos nach manueller Genehmigung

Nachdem das benutzerdefinierte Genehmigungssystem die manuelle Genehmigung erhalten hat, erstellt es ein Benutzerkonto 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 Sich Ihr Benutzer mit einem Google- oder Facebook-Konto oder einer einmaligen E-Mail-Kennung 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"
}

2. 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
Benutzerprinzipalname	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.
Benutzertyp	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}_benutzerdefiniertesAttribut>	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 sich ein Benutzer mit einem Microsoft Entra-Verbundkonto oder einem Microsoft-Konto anmeldet, müssen Sie die Einladungs-API verwenden, um den Benutzer zu erstellen, und optional die Benutzeraktualisierungs-API , um dem Benutzer weitere Attribute zuzuweisen.

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

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

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

• Hinzufügen eines Self-Service-Registrierungsbenutzerablaufs
• Hinzufügen eines API-Connectors
• Schützen Sie Ihren API-Connector
• Beispiel für Self-Service-Registrierung von Gastbenutzern mit manueller Genehmigung.