# Rollen

API-Berechtigungen in Rollen bündeln und Benutzern sowie Gruppen zuweisen, damit Anwendungen rollenbasiert autorisieren.

Requires: rbac

> **Plan-Hinweis:** Die rollenbasierte Zugriffskontrolle (RBAC) ist ab dem Advanced-Tarif verfügbar (sowie in Trial).

Eine **Rolle** ist ein benanntes Bündel von API-Berechtigungen, das Sie Benutzern und Gruppen zuweisen. Wenn sich ein Benutzer an einer Anwendung anmeldet und diese Anwendung einen Token für eine [RBAC-fähige API](https://dts-identity.com/de/docs/integrations/apis.md#role-based-access-control) anfordert, kann die Plattform die Rollen und Berechtigungen des Benutzers in den Token einbetten, sodass die Anwendung feingranulare Autorisierungsentscheidungen treffen kann, ohne ihr eigenes Berechtigungsmodell zu pflegen.

Sie verwalten Rollen in der Admin Console unter **Integrations → Roles**.

> **Hinweis:** Delegierte Administratoren (auf Entwicklerebene) verwalten Rollen über die [Workspaces](https://dts-identity.com/de/docs/governance/workspaces.md), denen sie angehören. Eine Rolle, die einem Workspace hinzugefügt wurde, kann von Mitgliedern mit der Berechtigung **Ressourcen verwalten** verwaltet und zugewiesen werden; vollständige Administratoren verwalten wie bisher alle Rollen.

## Rollen betreffen Anwendungen, nicht die Admin Console

Es lohnt sich klarzustellen, was diese Rollen **nicht** regeln. Sie steuern, was ein Benutzer **innerhalb Ihrer Anwendungen** tun kann, über die in API-Token getragenen Scopes. Sie steuern **nicht**, wer die Plattform administrieren darf; das wird separat durch die Zugriffsstufen geregelt, die Sie Ihrem Admin-Team im Bereich **Security** zuweisen.

## System- und benutzerdefinierte Rollen

- **Systemrollen** sind eingebaut. Ihr Name, ihre Beschreibung und ihre Berechtigungen sind fest; Sie können sie ansehen, aber nicht bearbeiten oder löschen.
- **Benutzerdefinierte Rollen** sind diejenigen, die Sie erstellen und steuern. Sie legen ihren Namen und ihre Beschreibung fest, wählen ihre Berechtigungen und weisen sie Benutzern und Gruppen zu.

## Eine Rolle erstellen und Berechtigungen hinzufügen

1. Wählen Sie auf der Roles-Seite **Create role** und geben Sie ihr einen Namen und eine Beschreibung.
2. Öffnen Sie die Rolle und gehen Sie zu ihrer Registerkarte **permissions**.
3. Wählen Sie **Add permissions**, wählen Sie eine **Custom API** und wählen Sie die einzuschließenden Scopes aus dieser API.
4. Speichern Sie.

Die Berechtigungen einer Rolle sind immer an eine bestimmte Custom API gebunden. Nur **Custom APIs mit aktiviertem RBAC** können Berechtigungen zu einer Rolle beitragen, schalten Sie also zuerst **Rollen und Berechtigungen aufnehmen (RBAC)** auf der API ein (siehe [APIs](https://dts-identity.com/de/docs/integrations/apis.md#role-based-access-control)). Hält eine Rolle Berechtigungen für eine API, bei der später RBAC deaktiviert wurde oder deren API gelöscht wurde, werden diese Einträge in der Rolle gekennzeichnet, damit Sie sie bereinigen können.

> **Hinweis (CIAM):** Auf Deployments mit der Business-Customer-(B2B-)Fähigkeit bietet das Formular zum Erstellen einer Rolle eine **allowed relationship**: Wählen Sie, ob die Rolle für *alle* Benutzer, nur für *customer*-Benutzer oder nur für *employee*-Benutzer verfügbar ist. Dies wählt, auf welche Benutzerpopulation die Rolle zutrifft, und ist bei der Erstellung fixiert. Ohne diese Fähigkeit gilt eine Rolle für alle Benutzer.

[Image: Die Rollenliste in der Admin-Konsole]

## Rollen zuweisen

Öffnen Sie eine Rolle und verwenden Sie ihre Registerkarte **users**, um sie zuzuweisen. Sie können eine Rolle zuweisen an:

- einzelne **Benutzer**: siehe [Personen](https://dts-identity.com/de/docs/directories/people.md), und
- **Gruppen**: siehe [Gruppen](https://dts-identity.com/de/docs/directories/groups.md), sodass jedes Mitglied die Rolle erbt.

Um eine Rolle von einem Benutzer zu entfernen, entfernen Sie ihn aus der Benutzerliste der Rolle. Das Löschen einer benutzerdefinierten Rolle entfernt sie von allen, denen sie zugewiesen war.

Wenn ein Benutzer eine Rolle hält, stehen die von ihr gebündelten Berechtigungen zur Verfügung, um in Token für die passenden RBAC-fähigen APIs eingebettet zu werden.

## Wie eine Berechtigung in einen Token gelangt

Die Kette vom Definieren einer Berechtigung bis zu ihrer Durchsetzung in Ihrer Anwendung:

1. Sie **definieren eine Berechtigung** (einen Scope) auf einer RBAC-fähigen Custom API.
2. Sie **bündeln sie in einer Rolle** auf der Registerkarte permissions der Rolle.
3. Sie **weisen die Rolle** einem Benutzer zu, direkt oder über eine [Gruppe](https://dts-identity.com/de/docs/directories/groups.md), sodass jedes Mitglied sie erbt.
4. Wenn sich dieser Benutzer anmeldet und eine Anwendung einen Token für die API anfordert, werden die berechtigten Berechtigungen des Benutzers aufgelöst und können **in den Access Token eingebettet** werden.

Ob die Rollennamen und Berechtigungen tatsächlich im Token erscheinen, wird pro API über die Optionen **roles in access token** und **permissions in access token** gesteuert (siehe [APIs](https://dts-identity.com/de/docs/integrations/apis.md#role-based-access-control)). Der Kompromiss:

- **Ein**: die Anwendung liest Rollen/Berechtigungen direkt aus dem Token, ohne zusätzliche Abfrage. Der Preis ist ein größerer Token, und ein vor einer Rollenänderung ausgestellter Token behält die alten Claims bis zu seinem Ablauf (mögliche Veralterung).
- **Aus**: der Token bleibt schlank; die Anwendung löst die Berechtigungen des Benutzers selbst auf, wenn sie sie benötigt, was aktuell bleibt, aber einen Callback erfordert.

### Im Access Token durchsetzen, nicht im ID Token [#enforce-on-the-access-token-not-the-id-token]

Eine Anwendung, die den Scope `roles` anfordert, erhält auch im **ID Token** einen Claim `roles`. Nutzen Sie ihn nur zur Darstellung: einen Admin-Menüpunkt einblenden, eine Schaltfläche ausblenden. Treffen Sie damit nie eine Zugriffsentscheidung.

Die beiden Claims sind nicht austauschbar. Das ID Token belegt, wer sich angemeldet hat, und ist an die Anwendung selbst adressiert; es ist nicht dafür gedacht, an eine API weitergereicht zu werden, und ein Dienst, der es als Berechtigungsnachweis akzeptiert, vertraut einem Token, das nie für ihn ausgestellt wurde. Sein Claim `roles` ist zudem der ungenauere von beiden: er listet Rollennamen ohne Bezug zu einer API und sagt damit nicht, ob eine Rolle für die aufgerufene Ressource überhaupt etwas bedeutet.

Das Access Token ist das an die API adressierte Token, und seine Claims sind auf diese API bezogen. Setzen Sie dort durch.

## Referenz

| Begriff | Bedeutung |
|---|---|
| Rolle | Ein benanntes Bündel von API-Berechtigungen, das Benutzern und Gruppen zugewiesen wird. |
| Systemrolle | Eine eingebaute, nicht bearbeitbare Rolle. |
| Benutzerdefinierte Rolle | Eine Rolle, die Sie erstellen und steuern. |
| Berechtigung | Ein einzelner API-Scope, den eine Rolle zu den Token eines Benutzers beiträgt. |

Siehe auch das [Glossar](https://dts-identity.com/de/docs/reference/glossary.md).
