Skip to Content

Role

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

Requiresrbac

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ń

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

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, 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:

  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ę, 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). 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

TerminZnaczenie
RolaNazwany zestaw uprawnień API przypisywany użytkownikom i grupom.
Rola systemowaWbudowana rola, której nie można edytować.
Rola niestandardowaRola tworzona i zarządzana samodzielnie.
UprawnieniePojedynczy scope API, który rola wnosi do tokenów użytkownika.

Zobacz też słownik.

Na tej stronie