Role
Grupowanie uprawnień API w role i przypisywanie ich użytkownikom i grupom, aby aplikacje mogły autoryzować na podstawie ról.
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, 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, 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ń
- Na stronie Role wybierz Utwórz rolę i nadaj roli nazwę oraz opis.
- Otwórz rolę i przejdź do jej karty Uprawnienia.
- Wybierz Dodaj uprawnienia, wskaż Custom API i zaznacz scope'y tego API, które mają zostać uwzględnione.
- 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). 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.

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, oraz
- grupom: zobacz Grupy, 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:
- Zdefiniuj uprawnienie (scope) w Custom API z włączonym RBAC.
- Dodaj je do roli na karcie uprawnień roli.
- Przypisz rolę użytkownikowi, bezpośrednio lub przez grupę, dzięki czemu dziedziczy ją każdy członek.
- 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). 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
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.