Hinzufügen von App-Rollen zu Ihrer Anwendung und Empfangen der Rollen im Token

Die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) ist eine beliebte Methode zum Erzwingen der Autorisierung in Anwendungen. RBAC ermöglicht es Administratoren, Berechtigungen für Rollen und nicht für bestimmte Benutzer oder Gruppen zu erteilen. Der Administrator kann anschließend verschiedenen Benutzern und Gruppen Rollen zuweisen, um zu steuern, wer auf welche Inhalte und Funktionen zugreifen kann.

Entwickler können die RBAC mit Anwendungsrollen und Rollenansprüchen verwenden und dadurch mit weniger Aufwand sicher die Autorisierung in ihren Apps erzwingen.

Ein weiterer Ansatz besteht darin, Microsoft Entra-Gruppen und Gruppenansprüche zu verwenden, wie im Codebeispiel "active-directory-aspnetcore-webapp-openidconnect-v2 " auf GitHub gezeigt. Microsoft Entra-Gruppen und Anwendungsrollen schließen sich nicht gegenseitig aus. Sie können zusammen verwendet werden, um eine noch differenziertere Zugriffssteuerung zu ermöglichen.

Deklarieren von Rollen für eine Anwendung

Sie definieren App-Rollen mithilfe des Microsoft Entra Admin Centers während des App-Registrierungsprozesses. App-Rollen werden in einer Anwendungsregistrierung definiert, die einen Dienst, eine App oder eine API darstellt. Wenn sich ein Benutzer bei der Anwendung anmeldet, gibt die Microsoft Entra-ID einen roles Anspruch für jede Rolle aus, die dem Benutzer oder Dienstprinzipal gewährt wurde, der zum Implementieren der anspruchsbasierten Autorisierung verwendet werden kann. App-Rollen können einem Benutzer oder einer Gruppe von Benutzern zugewiesen werden. App-Rollen können auch dem Dienstprinzipal für eine andere Anwendung oder dem Dienstprinzipal für eine verwaltete Identität zugewiesen werden.

Wenn Sie einer Gruppe einen Dienstprinzipal hinzufügen und dieser Gruppe dann eine App-Rolle zuweisen, fügt Microsoft Entra ID den ausgegebenen Token derzeit nicht den roles-Anspruch hinzu.

App-Rollen werden über die Benutzeroberfläche für App-Rollen im Microsoft Entra Admin Center deklariert:

Die Anzahl der von Ihnen hinzugefügten Rollen zählt zu den Grenzwerten des Anwendungsmanifests, die von Microsoft Entra ID durchgesetzt werden. Informationen zu diesen Grenzwerten finden Sie im Abschnitt Manifestgrenzwerte der Manifestreferenz der Microsoft Entra-App.

App-Rollen-UI

So erstellen Sie eine App-Rolle über die Microsoft Entra Admin Center Benutzeroberfläche:

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

2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie das Symbol "Einstellungen" im oberen Menü, um zum Mandanten zu wechseln, der die App-Registrierung aus dem Menü "Verzeichnisse + Abonnements" enthält.

3. Navigieren Sie zu Entra ID>App-Registrierungen, und wählen Sie dann die Anwendung aus, in der Sie App-Rollen definieren möchten.

4. Wählen Sie unter " App-Rollen verwalten" und dann " App-Rolle erstellen" aus.

   

5. Geben Sie im Bereich " App-Rollen erstellen" die Einstellungen für die Rolle ein. Die Tabelle im Anschluss an das Bild beschreibt die einzelnen Einstellungen und ihre Parameter.

   

   Feld	Beschreibung	Beispiel
   Anzeigename	Anzeigename für die App-Rolle, die auf den Administratorbildschirmen für Zustimmung und App-Zuweisung angezeigt wird. Dieser Wert kann Leerzeichen enthalten.	Survey Writer
   Zulässige Membertypen	Gibt an, ob diese App-Rolle Benutzern, Anwendungen oder beiden zugeordnet werden kann. Wenn Rollen für applications verfügbar sind, erscheinen sie als Anwendungsberechtigungen im Bereich Verwalten der App-Registrierung unter >"API-Berechtigungen > Berechtigung hinzufügen > Meine APIs > Wählen Sie eine API > Anwendungsberechtigungen".	Users/Groups
   Wert	Gibt den Wert des Rollenanspruchs an, den die Anwendung in den Token erwarten sollte. Der Wert sollte genau mit der Zeichenfolge übereinstimmen, auf die im Code der Anwendung verwiesen wird. Der Wert darf keine Leerzeichen enthalten.	Survey.Create
   Beschreibung	Eine ausführlichere Beschreibung der App-Rolle, die dem Administrator auf den App-Zuweisungs- und -Zustimmungsoberflächen angezeigt wird.	Writers can create surveys.
   Möchten Sie diese App-Rolle aktivieren?	Gibt an, ob die App-Rolle aktiviert ist. Um eine App-Rolle zu löschen, deaktivieren Sie dieses Kontrollkästchen, und wenden Sie die Änderung an, bevor Sie den Löschvorgang starten. Diese Einstellung steuert die Nutzung und Verfügbarkeit der App-Rolle und ermöglicht gleichzeitig die vorübergehende oder dauerhafte Deaktivierung, ohne sie vollständig zu entfernen.	Geprüft

6. Wählen Sie "Übernehmen" aus, um Ihre Änderungen zu speichern.

Wenn die App-Rolle auf Aktiviert festgelegt ist, wird die App-Rolle in die Token aller Benutzer, Anwendungen oder Gruppen aufgenommen, denen sie zugewiesen wurde. Dies können Zugriffstoken sein, wenn Ihre App die API ist, die von einer App aufgerufen wird, oder ID-Token, wenn Ihre App einen Benutzer anmeldet.

Wenn die App-Rolle auf "Deaktiviert" festgelegt ist, wird sie inaktiv und kann nicht mehr zugewiesen werden. Die aktuellen App-Rollenzuweisungen für Benutzer, Gruppen und Anwendungen bleiben jedoch erhalten, und die App-Rolle wird weiterhin in den Token(s) enthalten sein. Entfernen Sie die App-Rolle aus dem Benutzer, der Gruppe oder der Anwendung, um sicherzustellen, dass die App-Rolle auch aus dem bzw. den Token entfernt wird.

Zuweisen eines Anwendungsbesitzers

Bevor Sie Anwendungen App-Rollen zuweisen können, müssen Sie sich selbst als Anwendungsbesitzer zuweisen.

1. Wählen Sie in Ihrer App-Registrierung unter "Verwalten" " Besitzer" und "Besitzer hinzufügen" aus.
2. Suchen Sie im neuen Fenster nach den Besitzern, die Sie der Anwendung zuweisen möchten, und wählen Sie sie aus. Ausgewählte Besitzer werden im rechten Bereich angezeigt. Bestätigen Sie nach dem Abschluss mit Auswahl, dann erscheinen die App-Besitzer in der Besitzerliste.

Zuweisen von App-Rollen zu Anwendungen

Nachdem Sie Ihrer Anwendung App-Rollen hinzugefügt haben, können Sie einer Client-App eine App-Rolle mithilfe des Microsoft Entra Admin Centers oder programmgesteuert mithilfe von Microsoft Graph zuweisen. Das Zuweisen einer App-Rolle zu einer Anwendung sollte nicht mit dem Zuweisen von Rollen zu Benutzern verwechselt werden.

Wenn Sie einer Anwendung App-Rollen zuweisen, erstellen Sie Anwendungsberechtigungen. Anwendungsberechtigungen werden in der Regel von Daemon-Apps oder Back-End-Diensten verwendet, die ohne Benutzerinteraktion sich selbst authentifizieren und autorisierte API-Aufrufe ausführen müssen.

So weisen Sie einer Anwendung über das Microsoft Entra Admin Center App-Rollen zu:

1. Melden Sie sich mindestens als Cloudanwendungsadministrator beim Microsoft Entra Admin Center an.
2. Navigieren Sie zu Entra ID>App-Registrierungen und wählen Sie dann Alle Anwendungen aus.
3. Wählen Sie "Alle Anwendungen" aus, um eine Liste aller Anwendungen anzuzeigen. Wenn Ihre Anwendung nicht in der Liste angezeigt wird, verwenden Sie die Filter oben in der Liste "Alle Anwendungen ", um die Liste einzuschränken, oder scrollen Sie nach unten, um Ihre Anwendung zu finden.
4. Wählen Sie die Anwendung aus, der Sie eine App-Rolle hinzufügen möchten.
5. Wählen Sie API-Berechtigungen>"Berechtigung hinzufügen" aus.
6. Wählen Sie die Registerkarte "Meine APIs " und dann die App aus, für die Sie App-Rollen definiert haben.
7. Wählen Sie unter "Berechtigung" die Rollen aus, die Sie zuweisen möchten.
8. Wählen Sie die Schaltfläche " Berechtigungen hinzufügen " aus, um die Rollen vollständig hinzuzufügen.

Die neu hinzugefügten Rollen sollten im API-Berechtigungsbereich Ihrer App-Registrierung angezeigt werden.

Gewähren der Administratoreinwilligung

Da es sich hierbei um Anwendungsberechtigungen und nicht um delegierte Berechtigungen handelt, muss ein Administrator die Zustimmung erteilen, um die der Anwendung zugewiesenen App-Rollen zu verwenden.

1. Wählen Sie im API-Berechtigungsbereich der App-Registrierung die Berechtigung "Administratorzustimmung für <Mandantennamen> erteilen" aus.
2. Wählen Sie "Ja " aus, wenn Sie aufgefordert werden, die Zustimmung für die angeforderten Berechtigungen zu erteilen.

In der Spalte "Status" sollte angegeben werden, dass die Zustimmung für <den Mandantennamen> erteilt wurde.

Verwendungsszenario von App-Rollen

Wenn Sie App-Rollen-Geschäftslogik implementieren, die die Benutzer in Ihrem Anwendungsszenario anmeldet, definieren Sie zuerst die App-Rollen in App-Registrierungen. Anschließend weist ein Administrator sie Benutzern und Gruppen im Bereich "Unternehmensanwendungen " zu. Je nach Szenario sind diese zugewiesenen App-Rollen in verschiedenen Token enthalten, die für Ihre Anwendung ausgestellt werden. Bei einer App zur Anmeldung von Benutzern sind die Rollenansprüche beispielsweise im ID-Token enthalten. Wenn Ihre Anwendung eine API aufruft, sind die Rollenansprüche im Zugriffstoken enthalten.

Wenn Sie Geschäftslogik für App-Rollen in einem Szenario implementieren, in dem eine App eine API aufruft, verfügen Sie über zwei App-Registrierungen. Eine App-Registrierung ist für die App und eine zweite für die API. Definieren Sie in diesem Fall die App-Rollen, und weisen Sie sie den Benutzer*innen oder der Gruppe in der App-Registrierung der API zu. Wenn sich der Benutzer bei der App authentifiziert und ein Zugriffstoken zum Aufrufen der API anfordert, wird ein Rollenanspruch in das Token eingeschlossen. Der nächste Schritt besteht im Hinzufügen von Code zu Ihrer Web-API, um diese Rollen zu überprüfen, wenn die API aufgerufen wird.

Informationen zum Hinzufügen der Autorisierung zu Ihrer Web-API finden Sie unter Geschützte Web-API: Überprüfen von Bereichen und App-Rollen.

App-Rollen im Vergleich zu Gruppen

Obwohl Sie App-Rollen oder Gruppen für die Autorisierung verwenden können, können wichtige Unterschiede zwischen ihnen Ihre Entscheidung beeinflussen, welche für das Szenario verwendet werden sollen.

Entwickler können mit App-Rollen steuern, ob ein Benutzer sich bei einer App anmelden kann oder eine App ein Zugriffstoken für eine Web-API abrufen kann. Um diese Sicherheitssteuerung auf Gruppen auszuweiten, können Entwickler und Administratoren auch Sicherheitsgruppen zu App-Rollen zuweisen.

App-Rollen werden von Entwicklern bevorzugt, wenn sie die Parameter der Autorisierung in ihrer App selbst beschreiben und steuern möchten. Beispielsweise wird eine App, die Gruppen für die Autorisierung verwendet, im nächsten Mandanten nicht mehr funktionieren, da sowohl Gruppen-ID als auch Name unterschiedlich sein könnte. Eine App, die App-Rollen verwendet, bleibt sicher. Aus denselben Gründen wird das Zuweisen von Gruppen zu App-Rollen oft bei SaaS-Apps praktiziert, weil dadurch die SaaS-App in mehreren Mandanten bereitgestellt werden kann.

Zuweisen von Benutzern und Gruppen zu Microsoft Entra Rollen

Nachdem Sie Ihrer Anwendung App-Rollen hinzugefügt haben, können Sie Benutzern und Gruppen Microsoft Entra-Rollen zuweisen. Die Zuweisung von Benutzern und Gruppen zu Rollen kann über die Benutzeroberfläche des Portals oder programmgesteuert mithilfe von Microsoft Graph erfolgen. Wenn sich die Benutzer, die den verschiedenen Rollen zugewiesen sind, bei der Anwendung anmelden, enthalten deren Token die zugewiesenen Rollen im roles-Anspruch.

So weisen Sie über das Microsoft Entra Admin Center Benutzer und Gruppen Rollen zu:

1. Melden Sie sich mindestens als Cloudanwendungsadministrator beim Microsoft Entra Admin Center an.
2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie das Symbol "Einstellungen" im oberen Menü, um zum Mandanten zu wechseln, der die App-Registrierung aus dem Menü "Verzeichnisse + Abonnements" enthält.
3. Navigieren Sie zu Entra ID>Enterprise-Apps.
4. Wählen Sie "Alle Anwendungen" aus, um eine Liste aller Anwendungen anzuzeigen. Wenn Ihre Anwendung nicht in der Liste angezeigt wird, verwenden Sie die Filter oben in der Liste "Alle Anwendungen ", um die Liste einzuschränken, oder scrollen Sie nach unten, um Ihre Anwendung zu finden.
5. Wählen Sie die Anwendung aus, in der Sie Benutzer oder eine Sicherheitsgruppe zu Rollen zuweisen möchten.
6. Wählen Sie unter "Verwalten"die Option "Benutzer und Gruppen" aus.
7. Wählen Sie "Benutzer hinzufügen" aus, um den Aufgabenbereich hinzufügen zu öffnen.
8. Wählen Sie das Auswahlelement "Benutzer und Gruppen" im Bereich "Aufgaben hinzufügen" aus. Eine Liste von Benutzern und Sicherheitsgruppen wird angezeigt. Sie können sowohl nach einem bestimmten Benutzer oder einer bestimmten Gruppe suchen als auch mehrere in der Liste angezeigte Benutzer und Gruppen auswählen. Wählen Sie die Schaltfläche "Auswählen " aus, um fortzufahren.
9. Wählen Sie im Bereich "Zuweisung hinzufügen" die Option "Rolle auswählen" aus. Alle Rollen, die Sie für die Anwendung definiert haben, werden angezeigt.
10. Wählen Sie eine Rolle aus, und wählen Sie die Schaltfläche " Auswählen" aus .
11. Wählen Sie die Schaltfläche " Zuweisen " aus, um die Zuweisung von Benutzern und Gruppen zur App abzuschließen.

Vergewissern Sie sich, dass die hinzugefügten Benutzer und Gruppen in der Liste "Benutzer und Gruppen " angezeigt werden.

Nächste Schritte

In den folgenden Ressourcen erfahren Sie mehr über App-Rollen.

• Codebeispiele auf GitHub
  • Hinzufügen von Autorisierung mithilfe von App-Rollen und Rollenansprüchen zu einer ASP.NET Core Web App
• Referenzdokumentation
  • Microsoft Entra-App-Manifest
• Video: Implementieren der Autorisierung in Ihren Anwendungen mit Microsoft Identity Platform (1:01:15)