# Role

Grupowanie uprawnień API w role i przypisywanie ich użytkownikom i grupom, aby aplikacje mogły autoryzować na podstawie ról.

Requires: rbac

> **Informacja o planie:** Kontrola dostępu oparta na rolach (RBAC) jest dostępna w planie Advanced i wyższych (oraz w wersji Trial).

**Rola** to nazwany zestaw uprawnień API przypisywany użytkownikom i grupom. Gdy użytkownik loguje się do aplikacji, a ta aplikacja żąda tokenu dla [API z włączonym RBAC](https://dts-identity.com/pl/docs/integrations/apis.md#role-based-access-control), platforma może osadzić w tokenie role i uprawnienia użytkownika, dzięki czemu aplikacja może podejmować szczegółowe decyzje autoryzacyjne bez utrzymywania własnego modelu uprawnień.

Rolami zarządza się w konsoli administracyjnej w sekcji **Integracje → Role**.

> **Uwaga:** Administratorzy delegowani (na poziomie dewelopera) zarządzają rolami za pośrednictwem [Workspace'ów](https://dts-identity.com/pl/docs/governance/workspaces.md), do których należą. Rolą dodaną do Workspace'u mogą zarządzać i przypisywać ją członkowie z uprawnieniem **Zarządzanie zasobami**; pełni administratorzy zarządzają wszystkimi rolami tak jak dotychczas.

## Role dotyczą aplikacji, a nie Admin Console

Warto jasno określić, czego te role **nie** regulują. Kontrolują one, co użytkownik może robić **wewnątrz aplikacji**, za pośrednictwem scope'ów przenoszonych w tokenach API. **Nie** kontrolują natomiast, kto może administrować platformą. Reguluje to oddzielnie poziom dostępu przypisywany członkom zespołu administratorów w obszarze **Bezpieczeństwo**.

## Role systemowe i niestandardowe

- **Role systemowe** są wbudowane. Ich nazwa, opis i uprawnienia są stałe; można je przeglądać, ale nie można ich edytować ani usuwać.
- **Role niestandardowe** to role tworzone i zarządzane samodzielnie. Określa się ich nazwę i opis, wybiera uprawnienia i przypisuje je użytkownikom i grupom.

## Tworzenie roli i dodawanie uprawnień

1. Na stronie Role wybierz **Utwórz rolę** i nadaj roli nazwę oraz opis.
2. Otwórz rolę i przejdź do jej karty **Uprawnienia**.
3. Wybierz **Dodaj uprawnienia**, wskaż **Custom API** i zaznacz scope'y tego API, które mają zostać uwzględnione.
4. Zapisz.

Uprawnienia roli są zawsze powiązane z określonym Custom API. Uprawnienia do roli mogą wnosić tylko **Custom API z włączonym RBAC**, dlatego najpierw włącz w API opcję **Dołącz role i uprawnienia (RBAC)** (zobacz [API](https://dts-identity.com/pl/docs/integrations/apis.md#role-based-access-control)). Jeśli rola zawiera uprawnienia do API, w którym później wyłączono RBAC lub które zostało usunięte, te wpisy są oznaczane w roli, aby można je było uporządkować.

> **Uwaga (CIAM):** we wdrożeniach z funkcją klientów biznesowych (B2B) formularz tworzenia roli oferuje pole **allowed relationship**: należy wybrać, czy rola jest dostępna dla *wszystkich* użytkowników, tylko dla użytkowników *customer* czy tylko dla użytkowników *employee*. Określa to, do której populacji użytkowników rola ma zastosowanie, i jest ustalane na stałe przy tworzeniu. Bez tej funkcji rola dotyczy wszystkich użytkowników.

[Image: Lista ról w konsoli administracyjnej]

## Przypisywanie ról

Otwórz rolę i użyj jej karty **Użytkownicy**, aby ją przypisać. Rolę można przypisać:

- poszczególnym **użytkownikom**: zobacz [Osoby](https://dts-identity.com/pl/docs/directories/people.md), oraz
- **grupom**: zobacz [Grupy](https://dts-identity.com/pl/docs/directories/groups.md), dzięki czemu każdy członek dziedziczy rolę.

Aby odebrać rolę użytkownikowi, usuń go z listy użytkowników roli. Usunięcie roli niestandardowej odbiera ją wszystkim, którym była przypisana.

Gdy użytkownik posiada rolę, zgrupowane w niej uprawnienia mogą zostać osadzone w tokenach dla odpowiednich API z włączonym RBAC.

## Jak uprawnienie trafia do tokenu

Łańcuch od zdefiniowania uprawnienia do jego egzekwowania w aplikacji:

1. **Zdefiniuj uprawnienie** (scope) w Custom API z włączonym RBAC.
2. **Dodaj je do roli** na karcie uprawnień roli.
3. **Przypisz rolę** użytkownikowi, bezpośrednio lub przez [grupę](https://dts-identity.com/pl/docs/directories/groups.md), dzięki czemu dziedziczy ją każdy członek.
4. Gdy ten użytkownik się loguje, a aplikacja żąda tokenu dla API, przysługujące mu uprawnienia są ustalane i mogą zostać **osadzone w tokenie dostępu (access token)**.

To, czy nazwy ról i uprawnienia rzeczywiście pojawiają się w tokenie, określa się osobno dla każdego API za pomocą opcji **roles in access token** i **permissions in access token** (zobacz [API](https://dts-identity.com/pl/docs/integrations/apis.md#role-based-access-control)). Kompromis wygląda następująco:

- **Włączone**: aplikacja odczytuje role i uprawnienia bezpośrednio z tokenu, bez dodatkowego zapytania. Kosztem jest większy token, a token wystawiony przed zmianą roli zachowuje stare claims aż do wygaśnięcia (możliwa nieaktualność).
- **Wyłączone**: token pozostaje niewielki; aplikacja sama ustala uprawnienia użytkownika, gdy ich potrzebuje, co zapewnia aktualność, ale wymaga dodatkowego wywołania.

### Egzekwowanie w access tokenie, a nie w ID tokenie [#enforce-on-the-access-token-not-the-id-token]

Aplikacja, która żąda scope'u `roles`, otrzymuje również claim `roles` w swoim **ID tokenie**. Należy go używać wyłącznie do celów prezentacji: wyświetlenia pozycji menu administracyjnego czy ukrycia przycisku. Nigdy nie należy podejmować na jego podstawie decyzji o dostępie.

Te dwa claims nie są wymienne. ID token potwierdza, kto się zalogował, i jest adresowany do samej aplikacji; nie jest przeznaczony do przekazywania do API, a usługa, która akceptuje go jako dowód uprawnień, ufa tokenowi, który nigdy nie został dla niej wystawiony. Jego claim `roles` jest też mniej precyzyjny: zawiera nazwy ról bez odniesienia do jakiegokolwiek API, więc nie pozwala ustalić, czy dana rola ma jakiekolwiek znaczenie dla wywoływanego zasobu.

Access token jest adresowany do API, a jego claims dotyczą tego API. To tam należy egzekwować uprawnienia.

## Informacje referencyjne

| Termin | Znaczenie |
|---|---|
| Rola | Nazwany zestaw uprawnień API przypisywany użytkownikom i grupom. |
| Rola systemowa | Wbudowana rola, której nie można edytować. |
| Rola niestandardowa | Rola tworzona i zarządzana samodzielnie. |
| Uprawnienie | Pojedynczy scope API, który rola wnosi do tokenów użytkownika. |

Zobacz też [słownik](https://dts-identity.com/pl/docs/reference/glossary.md).
