Przestrzenie robocze, role i środowiska

Cały model mieści się w pięciu słowach, a one się zagnieżdżają:

Konto            — Ty, czyli klient i podmiot rozliczany
└── Aplikacja    — jedna domena uwierzytelniania: Twój produkt
    └── Środowisko        — produkcja i sandbox, zawsze dokładnie dwa
        ├── Użytkownik    — osoba z danymi logowania, należąca do tego środowiska
        └── Przestrzeń robocza — grupa zarządzana przez Twoich klientów, z członkami i ich rolami

Nic nie przekracza granicy środowiska. Użytkownik z sandboksa nie istnieje na produkcji, a rola zdefiniowana w jednym środowisku nie jest tą samą rolą w drugim, nawet pod tą samą nazwą.

Aplikacja

Aplikacja to jeden produkt z jednym zbiorem użytkowników. Dostaje slug, a ze sluga powstają dwa stałe adresy — https://acme.kleora.eu i https://acme.sandbox.kleora.eu. To są issuery aplikacji: claim iss każdego wydanego tokenu, host, z którego serwowane są strony logowania, i baza dokumentu discovery.

Sluga nie da się później zmienić. Każda usługa, która kiedykolwiek sprawdziła Twój token, ma ten ciąg zapamiętany; wybierz go z taką uwagą, z jaką wybiera się domenę.

Założenie aplikacji tworzy w jednej transakcji oba środowiska, a w każdym z nich: domyślną przestrzeń roboczą, klienta spa o nazwie Default, klucze podpisujące, domyślny branding i ustawienia, zarezerwowane uprawnienia zarządcze oraz domyślne szablony wiadomości. Niczego z tego nie trzeba potem dokonfigurowywać.

Środowisko

Dwa na aplikację, production i sandbox, i strukturalnie identyczne. Te same funkcje, te same endpointy, te same kształty. Różnią się tym, co ma je chronić przed pomyleniem:

SDK odmawiają ich mieszania: klucz kl_test_ z produkcyjnym issuerem albo token, którego env nie zgadza się ze skonfigurowanym issuerem, kończy się błędem na etapie konfiguracji, a nie na produkcji o drugiej w nocy. Środowisko widać w każdym adresie, jaki wklejasz — i to jest najtańsze zabezpieczenie przed wycelowaniem produkcyjnego kodu w sandbox.

Każde środowisko ma też własne ustawienia: czasy życia tokenów i sesji, reguły haseł, to, czy ludzie mogą rejestrować się sami. Domyślnie token dostępu żyje 15 minut, token odświeżania 30 dni, a sesja 7 dni z limitem 24 godzin bezczynności; każdą z tych wartości da się zmienić w dopuszczalnym zakresie.

Promocja zamiast dwukrotnego klikania po produkcji

Konfiguracja przenosi się z sandboksa na produkcję jedną operacją: promocją. Kopiuje ustawienia, branding, uprawnienia, role przypisane do aplikacji i szablony wiadomości, a wcześniej można ją uruchomić na sucho — zwraca ten sam wynik i nie zmienia niczego.

Nie kopiuje nigdy tego, co należy do prawdziwych ludzi: użytkowników, tożsamości, sesji, przestrzeni roboczych, członkostw, zaproszeń, klientów, kluczy API i kluczy podpisujących. Członkowie na produkcji zachowują swoje role — a ponieważ role dopasowywane są po slugu, członek z rolą editor po prostu dostaje w kolejnym tokenie nowy zestaw uprawnień roli editor.

Przestrzeń robocza

Przestrzeń robocza to grupa, którą wewnątrz jednego środowiska zarządzają Twoi klienci — firma, zespół, projekt. Użytkownik dołącza do niej jako członek i to członkostwo niesie role. Ta sama osoba może być członkiem kilku przestrzeni, w każdej z inną rolą.

Środowisko działa w jednym z dwóch trybów:

• single — domyślny i właściwy dla produktu konsumenckiego. Jest jedna przestrzeń, jest ukryta, a każdy nowy użytkownik trafia do niej automatycznie. Nikt niczego nie wybiera przy logowaniu.
• multi — przestrzenie są prawdziwe. Pojawiają się na listach, można je zakładać, a logowanie kończy się w dokładnie jednej z nich.

Przejście na multi nie wymaga migracji. Powrót jest możliwy tylko wtedy, gdy została już wyłącznie domyślna przestrzeń — bo alternatywą byłoby skasowanie w Twoim imieniu przestrzeni, które wciąż mają członków.

W której przestrzeni kończy się logowanie

W trybie multi, po uwierzytelnieniu osoby:

1. Jeśli żądanie autoryzacji wskazało przestrzeń (parametr tenant) — ta. Albo logowanie się nie udaje, zamiast po cichu wpaść w inną.
2. W przeciwnym razie, jeśli sesja ma już przestrzeń, w której ta osoba nadal jest członkiem — ta sama.
3. W przeciwnym razie: dokładnie jeden kandydat wybiera się sam, a kilku pokazuje listę wyboru.
4. Zero kandydatów oznacza to, co mówią ustawienia środowiska: odmowę albo formularz „załóż przestrzeń roboczą”.

Wynik zapisuje się na sesji, więc każdy kolejny token w tej sesji niesie tę samą przestrzeń, dopóki nie zostanie świadomie zmieniona.

Zaproszenia

Zaproszenie wskazuje adres e-mail i role, które ze sobą przyniesie, i jest ważne siedem dni. Przyjęcie dowodzi kontroli nad adresem, więc zaproszona osoba, która nie ma jeszcze konta, rejestruje się z adresem wpisanym i zablokowanym do edycji — i ląduje z adresem potwierdzonym, bo dowodem było kliknięcie w link. Na jeden adres i jedną przestrzeń przypada jedno otwarte zaproszenie; wysłanie ponowne wydaje nowy token i unieważnia poprzedni.

Role i uprawnienia

Uprawnienie to napis w postaci zasób:czasownik — invoices:read, reports:write. Definiujesz je sam; znaczą to, co uzna Twoja aplikacja.

Rola to ich wiązka i ma jeden z dwóch zasięgów:

• Na poziomie aplikacji — zdefiniowana na środowisku, przypisywalna w każdej jego przestrzeni roboczej. Tu zwykle mieszkają admin i member.
• Na poziomie przestrzeni — zdefiniowana wewnątrz jednej przestrzeni, przypisywalna tylko tam. Tak jeden klient daje sobie rolę, której inni nie mają.

Slug roli to właśnie to, co niosą tokeny, więc po utworzeniu jest niezmienny; nazwa i opis nie są. Slugi nie mogą się zderzać między zasięgami — admin na poziomie aplikacji blokuje admin w każdej przestrzeni — i to właśnie sprawia, że tablica roles w tokenie jest jednoznaczna.

Kleora zakłada też w każdym środowisku zestaw zarezerwowanych uprawnień zarządczych (users:read, members:write, roles:write i podobne). Nie da się ich skasować ani przemianować, ale można je włożyć do roli — i tak właśnie pozwalasz administratorowi po stronie klienta zarządzać członkami swojej przestrzeni przez API, własnym tokenem dostępu, bez stawania się administratorem u Ciebie.

Co niesie token i kiedy się to zmienia

Każdy token dostępu niesie rozstrzygniętą przestrzeń roboczą i związaną z nią autoryzację:

{
  "sub": "…",
  "tenant": "…",
  "tenant_slug": "acme",
  "roles": ["admin"],
  "permissions": ["invoices:read", "invoices:write"],
  "env": "production"
}

roles to slugi ról członka, permissions to suma uprawnień tych ról, bez powtórzeń i posortowana. Oba są zawsze obecne — [] zamiast braku — więc sprawdzenie autoryzacji nigdy nie musi najpierw badać, czy pole w ogóle jest. Twoje API czyta je z tokenu, który i tak już zweryfikowało.

Kosztem jest jedna rzecz, którą trzeba wziąć pod uwagę w projekcie: zmiana roli albo ról członka jest widoczna przy kolejnym wydaniu tokenu — u kogoś, kto trzyma ważny token dostępu, w granicach jego czasu życia, a przy najbliższym odświeżeniu natychmiast. Dla tokenów dostępu nie ma listy unieważnień. Kiedy zmiana musi zadziałać teraz, a nie za piętnaście minut, unieważnij sesje tego użytkownika — kolejne żądanie nie ma już żadnego ważnego tokenu.

Dalej

• Szybki start dla frameworków — kod, który zamienia to wszystko w zalogowanego użytkownika.
• Jak zbudowana jest Kleora — gdzie granica środowiska leży w działającym systemie.