[{"data":1,"prerenderedAt":673},["ShallowReactive",2],{"docs:doc:\u002Fpl\u002Fdocs\u002Fprzewodniki\u002Fpojecia":3,"docs:pages:docs_pl":606},{"id":4,"title":5,"alt":6,"body":7,"description":595,"extension":596,"key":597,"meta":598,"navigation":599,"order":600,"path":601,"placeholder":602,"seo":603,"stem":604,"__hash__":605},"docs_pl\u002Fpl\u002Fdocs\u002Fprzewodniki\u002Fpojecia.md","Przestrzenie robocze, role i środowiska","\u002Fen\u002Fdocs\u002Fguides\u002Fconcepts",{"type":8,"value":9,"toc":582},"minimark",[10,14,25,28,61,66,85,88,99,103,118,219,228,231,236,243,253,257,268,271,291,297,301,307,325,328,332,335,339,357,363,383,396,413,417,420,527,540,547,557,561,578],[11,12,13],"p",{},"Cały model mieści się w pięciu słowach, a one się zagnieżdżają:",[15,16,21],"pre",{"className":17,"code":19,"language":20},[18],"language-text","Konto            — Ty, czyli klient i podmiot rozliczany\n└── Aplikacja    — jedna domena uwierzytelniania: Twój produkt\n    └── Środowisko        — produkcja i sandbox, zawsze dokładnie dwa\n        ├── Użytkownik    — osoba z danymi logowania, należąca do tego środowiska\n        └── Przestrzeń robocza — grupa zarządzana przez Twoich klientów, z członkami i ich rolami\n","text",[22,23,19],"code",{"__ignoreMap":24},"",[11,26,27],{},"Nic nie przekracza granicy środowiska. Użytkownik z sandboksa nie istnieje na\nprodukcji, a rola zdefiniowana w jednym środowisku nie jest tą samą rolą w\ndrugim, nawet pod tą samą nazwą.",[29,30,33],"callout",{"title":31,"type":32},"Przestrzeń robocza czy tenant?","note",[11,34,35,36,40,41,44,45,48,49,51,52,55,56,60],{},"To samo, w dwóch słownikach. Strony, które widzą Twoi użytkownicy, mówią\n",[37,38,39],"strong",{},"przestrzeń robocza","; API, SDK i claimy tokenu mówią ",[37,42,43],{},"tenant"," —\n",[22,46,47],{},"\u002Ftenants\u002F{id}",", claim ",[22,50,43],{},", ",[22,53,54],{},"tenant_slug",". Słowem „tenant” nigdy nie\nnazywamy ",[57,58,59],"em",{},"naszego"," klienta; to jest konto.",[62,63,65],"h2",{"id":64},"aplikacja","Aplikacja",[11,67,68,69,72,73,76,77,80,81,84],{},"Aplikacja to jeden produkt z jednym zbiorem użytkowników. Dostaje ",[37,70,71],{},"slug",", a ze\nsluga powstają dwa stałe adresy — ",[22,74,75],{},"https:\u002F\u002Facme.kleora.eu"," i\n",[22,78,79],{},"https:\u002F\u002Facme.sandbox.kleora.eu",". To są issuery aplikacji: claim ",[22,82,83],{},"iss","\nkażdego wydanego tokenu, host, z którego serwowane są strony logowania, i baza\ndokumentu discovery.",[11,86,87],{},"Sluga nie da się później zmienić. Każda usługa, która kiedykolwiek sprawdziła\nTwój token, ma ten ciąg zapamiętany; wybierz go z taką uwagą, z jaką wybiera się\ndomenę.",[11,89,90,91,94,95,98],{},"Założenie aplikacji tworzy w jednej transakcji oba środowiska, a w każdym z nich:\ndomyślną przestrzeń roboczą, klienta ",[22,92,93],{},"spa"," o nazwie ",[37,96,97],{},"Default",", klucze\npodpisujące, domyślny branding i ustawienia, zarezerwowane uprawnienia zarządcze\noraz domyślne szablony wiadomości. Niczego z tego nie trzeba potem dokonfigurowywać.",[62,100,102],{"id":101},"środowisko","Środowisko",[11,104,105,106,109,110,113,114,117],{},"Dwa na aplikację, ",[22,107,108],{},"production"," i ",[22,111,112],{},"sandbox",", i ",[37,115,116],{},"strukturalnie identyczne",". Te\nsame funkcje, te same endpointy, te same kształty. Różnią się tym, co ma je\nchronić przed pomyleniem:",[119,120,121,136],"table",{},[122,123,124],"thead",{},[125,126,127,130,133],"tr",{},[128,129],"th",{},[128,131,132],{},"Produkcja",[128,134,135],{},"Sandbox",[137,138,139,155,170,187,208],"tbody",{},[125,140,141,145,150],{},[142,143,144],"td",{},"Issuer",[142,146,147],{},[22,148,149],{},"acme.kleora.eu",[142,151,152],{},[22,153,154],{},"acme.sandbox.kleora.eu",[125,156,157,160,165],{},[142,158,159],{},"Prefiks klucza API",[142,161,162],{},[22,163,164],{},"kl_live_",[142,166,167],{},[22,168,169],{},"kl_test_",[125,171,172,179,183],{},[142,173,174,175,178],{},"Claim ",[22,176,177],{},"env"," w tokenach",[142,180,181],{},[22,182,108],{},[142,184,185],{},[22,186,112],{},[125,188,189,192,198],{},[142,190,191],{},"Adresy powrotne",[142,193,194,195],{},"wyłącznie ",[22,196,197],{},"https:\u002F\u002F",[142,199,200,201,109,204,207],{},"dodatkowo ",[22,202,203],{},"http:\u002F\u002Flocalhost",[22,205,206],{},"http:\u002F\u002F127.0.0.1",", dowolny port i ścieżka",[125,209,210,213,216],{},[142,211,212],{},"Liczone do rozliczeń",[142,214,215],{},"tak",[142,217,218],{},"nigdy",[11,220,221,222,224,225,227],{},"SDK odmawiają ich mieszania: klucz ",[22,223,169],{}," z produkcyjnym issuerem albo token,\nktórego ",[22,226,177],{}," nie zgadza się ze skonfigurowanym issuerem, kończy się błędem na\netapie konfiguracji, a nie na produkcji o drugiej w nocy. Środowisko widać w\nkażdym adresie, jaki wklejasz — i to jest najtańsze zabezpieczenie przed\nwycelowaniem produkcyjnego kodu w sandbox.",[11,229,230],{},"Każde środowisko ma też własne ustawienia: czasy życia tokenów i sesji, reguły\nhaseł, to, czy ludzie mogą rejestrować się sami. Domyślnie token dostępu żyje 15\nminut, token odświeżania 30 dni, a sesja 7 dni z limitem 24 godzin bezczynności;\nkażdą z tych wartości da się zmienić w dopuszczalnym zakresie.",[232,233,235],"h3",{"id":234},"promocja-zamiast-dwukrotnego-klikania-po-produkcji","Promocja zamiast dwukrotnego klikania po produkcji",[11,237,238,239,242],{},"Konfiguracja przenosi się z sandboksa na produkcję jedną operacją: ",[37,240,241],{},"promocją",".\nKopiuje ustawienia, branding, uprawnienia, role przypisane do aplikacji i\nszablony wiadomości, a wcześniej można ją uruchomić na sucho — zwraca ten sam\nwynik i nie zmienia niczego.",[11,244,245,246,249,250,252],{},"Nie kopiuje nigdy tego, co należy do prawdziwych ludzi: użytkowników,\ntożsamości, sesji, przestrzeni roboczych, członkostw, zaproszeń, klientów, kluczy\nAPI i kluczy podpisujących. Członkowie na produkcji zachowują swoje role — a\nponieważ role dopasowywane są po slugu, członek z rolą ",[22,247,248],{},"editor"," po prostu dostaje\nw kolejnym tokenie nowy zestaw uprawnień roli ",[22,251,248],{},".",[62,254,256],{"id":255},"przestrzeń-robocza","Przestrzeń robocza",[11,258,259,260,263,264,267],{},"Przestrzeń robocza to grupa, którą wewnątrz jednego środowiska zarządzają ",[37,261,262],{},"Twoi\nklienci"," — firma, zespół, projekt. Użytkownik dołącza do niej jako ",[37,265,266],{},"członek"," i\nto członkostwo niesie role. Ta sama osoba może być członkiem kilku przestrzeni,\nw każdej z inną rolą.",[11,269,270],{},"Środowisko działa w jednym z dwóch trybów:",[272,273,274,283],"ul",{},[275,276,277,282],"li",{},[37,278,279],{},[22,280,281],{},"single"," — domyślny i właściwy dla produktu konsumenckiego. Jest jedna\nprzestrzeń, jest ukryta, a każdy nowy użytkownik trafia do niej automatycznie.\nNikt niczego nie wybiera przy logowaniu.",[275,284,285,290],{},[37,286,287],{},[22,288,289],{},"multi"," — przestrzenie są prawdziwe. Pojawiają się na listach, można je\nzakładać, a logowanie kończy się w dokładnie jednej z nich.",[11,292,293,294,296],{},"Przejście na ",[22,295,289],{}," nie wymaga migracji. Powrót jest możliwy tylko wtedy, gdy\nzostała już wyłącznie domyślna przestrzeń — bo alternatywą byłoby skasowanie w\nTwoim imieniu przestrzeni, które wciąż mają członków.",[232,298,300],{"id":299},"w-której-przestrzeni-kończy-się-logowanie","W której przestrzeni kończy się logowanie",[11,302,303,304,306],{},"W trybie ",[22,305,289],{},", po uwierzytelnieniu osoby:",[308,309,310,316,319,322],"ol",{},[275,311,312,313,315],{},"Jeśli żądanie autoryzacji wskazało przestrzeń (parametr ",[22,314,43],{},") — ta. Albo\nlogowanie się nie udaje, zamiast po cichu wpaść w inną.",[275,317,318],{},"W przeciwnym razie, jeśli sesja ma już przestrzeń, w której ta osoba nadal\njest członkiem — ta sama.",[275,320,321],{},"W przeciwnym razie: dokładnie jeden kandydat wybiera się sam, a kilku pokazuje\nlistę wyboru.",[275,323,324],{},"Zero kandydatów oznacza to, co mówią ustawienia środowiska: odmowę albo\nformularz „załóż przestrzeń roboczą”.",[11,326,327],{},"Wynik zapisuje się na sesji, więc każdy kolejny token w tej sesji niesie tę samą\nprzestrzeń, dopóki nie zostanie świadomie zmieniona.",[232,329,331],{"id":330},"zaproszenia","Zaproszenia",[11,333,334],{},"Zaproszenie wskazuje adres e-mail i role, które ze sobą przyniesie, i jest ważne\nsiedem dni. Przyjęcie dowodzi kontroli nad adresem, więc zaproszona osoba, która\nnie ma jeszcze konta, rejestruje się z adresem wpisanym i zablokowanym do edycji\n— i ląduje z adresem potwierdzonym, bo dowodem było kliknięcie w link. Na jeden\nadres i jedną przestrzeń przypada jedno otwarte zaproszenie; wysłanie ponowne\nwydaje nowy token i unieważnia poprzedni.",[62,336,338],{"id":337},"role-i-uprawnienia","Role i uprawnienia",[11,340,341,344,345,348,349,352,353,356],{},[37,342,343],{},"Uprawnienie"," to napis w postaci ",[22,346,347],{},"zasób:czasownik"," — ",[22,350,351],{},"invoices:read",",\n",[22,354,355],{},"reports:write",". Definiujesz je sam; znaczą to, co uzna Twoja aplikacja.",[11,358,359,362],{},[37,360,361],{},"Rola"," to ich wiązka i ma jeden z dwóch zasięgów:",[272,364,365,377],{},[275,366,367,370,371,109,374,252],{},[37,368,369],{},"Na poziomie aplikacji"," — zdefiniowana na środowisku, przypisywalna w każdej\njego przestrzeni roboczej. Tu zwykle mieszkają ",[22,372,373],{},"admin",[22,375,376],{},"member",[275,378,379,382],{},[37,380,381],{},"Na poziomie przestrzeni"," — zdefiniowana wewnątrz jednej przestrzeni,\nprzypisywalna tylko tam. Tak jeden klient daje sobie rolę, której inni nie\nmają.",[11,384,385,386,388,389,391,392,395],{},"Slug roli to właśnie to, co niosą tokeny, więc po utworzeniu jest niezmienny;\nnazwa i opis nie są. Slugi nie mogą się zderzać między zasięgami — ",[22,387,373],{}," na\npoziomie aplikacji blokuje ",[22,390,373],{}," w każdej przestrzeni — i to właśnie sprawia,\nże tablica ",[22,393,394],{},"roles"," w tokenie jest jednoznaczna.",[11,397,398,399,402,403,51,406,51,409,412],{},"Kleora zakłada też w każdym środowisku zestaw ",[37,400,401],{},"zarezerwowanych uprawnień\nzarządczych"," (",[22,404,405],{},"users:read",[22,407,408],{},"members:write",[22,410,411],{},"roles:write"," i podobne). Nie da\nsię ich skasować ani przemianować, ale można je włożyć do roli — i tak właśnie\npozwalasz administratorowi po stronie klienta zarządzać członkami swojej\nprzestrzeni przez API, własnym tokenem dostępu, bez stawania się\nadministratorem u Ciebie.",[62,414,416],{"id":415},"co-niesie-token-i-kiedy-się-to-zmienia","Co niesie token i kiedy się to zmienia",[11,418,419],{},"Każdy token dostępu niesie rozstrzygniętą przestrzeń roboczą i związaną z nią\nautoryzację:",[15,421,425],{"className":422,"code":423,"language":424,"meta":24,"style":24},"language-json shiki shiki-themes github-light","{\n  \"sub\": \"…\",\n  \"tenant\": \"…\",\n  \"tenant_slug\": \"acme\",\n  \"roles\": [\"admin\"],\n  \"permissions\": [\"invoices:read\", \"invoices:write\"],\n  \"env\": \"production\"\n}\n","json",[22,426,427,436,452,464,477,492,510,521],{"__ignoreMap":24},[428,429,432],"span",{"class":430,"line":431},"line",1,[428,433,435],{"class":434},"sgsFI","{\n",[428,437,439,443,446,450],{"class":430,"line":438},2,[428,440,442],{"class":441},"sYu0t","  \"sub\"",[428,444,445],{"class":434},": ",[428,447,449],{"class":448},"sYBdl","\"…\"",[428,451,352],{"class":434},[428,453,455,458,460,462],{"class":430,"line":454},3,[428,456,457],{"class":441},"  \"tenant\"",[428,459,445],{"class":434},[428,461,449],{"class":448},[428,463,352],{"class":434},[428,465,467,470,472,475],{"class":430,"line":466},4,[428,468,469],{"class":441},"  \"tenant_slug\"",[428,471,445],{"class":434},[428,473,474],{"class":448},"\"acme\"",[428,476,352],{"class":434},[428,478,480,483,486,489],{"class":430,"line":479},5,[428,481,482],{"class":441},"  \"roles\"",[428,484,485],{"class":434},": [",[428,487,488],{"class":448},"\"admin\"",[428,490,491],{"class":434},"],\n",[428,493,495,498,500,503,505,508],{"class":430,"line":494},6,[428,496,497],{"class":441},"  \"permissions\"",[428,499,485],{"class":434},[428,501,502],{"class":448},"\"invoices:read\"",[428,504,51],{"class":434},[428,506,507],{"class":448},"\"invoices:write\"",[428,509,491],{"class":434},[428,511,513,516,518],{"class":430,"line":512},7,[428,514,515],{"class":441},"  \"env\"",[428,517,445],{"class":434},[428,519,520],{"class":448},"\"production\"\n",[428,522,524],{"class":430,"line":523},8,[428,525,526],{"class":434},"}\n",[11,528,529,531,532,535,536,539],{},[22,530,394],{}," to slugi ról członka, ",[22,533,534],{},"permissions"," to suma uprawnień tych ról, bez\npowtórzeń i posortowana. Oba są zawsze obecne — ",[22,537,538],{},"[]"," zamiast braku — więc\nsprawdzenie autoryzacji nigdy nie musi najpierw badać, czy pole w ogóle jest.\nTwoje API czyta je z tokenu, który i tak już zweryfikowało.",[11,541,542,543,546],{},"Kosztem jest jedna rzecz, którą trzeba wziąć pod uwagę w projekcie: ",[37,544,545],{},"zmiana\nroli albo ról członka jest widoczna przy kolejnym wydaniu tokenu"," — u kogoś,\nkto trzyma ważny token dostępu, w granicach jego czasu życia, a przy najbliższym\nodświeżeniu natychmiast. Dla tokenów dostępu nie ma listy unieważnień. Kiedy\nzmiana musi zadziałać teraz, a nie za piętnaście minut, unieważnij sesje tego\nużytkownika — kolejne żądanie nie ma już żadnego ważnego tokenu.",[29,548,550],{"title":549,"type":32},"Pułap, o którym warto wiedzieć",[11,551,552,553,556],{},"Jeśli uprawnienia członka przekroczą 200 pozycji, zarezerwowane uprawnienia\nzarządcze zostają w całości, a Twoje własne są obcinane od końca posortowanej\nlisty, i token dostaje ",[22,554,555],{},"permissions_truncated: true",". Trafi na to każdy, kto\nzaprojektuje uprawnienia per obiekt jako napisy uprawnień; role są tańszym\nkształtem.",[62,558,560],{"id":559},"dalej","Dalej",[272,562,563,571],{},[275,564,565,570],{},[566,567,569],"a",{"href":568},"\u002Fpl\u002Fdocs\u002Fprzewodniki\u002Fframeworki","Szybki start dla frameworków"," — kod, który\nzamienia to wszystko w zalogowanego użytkownika.",[275,572,573,577],{},[566,574,576],{"href":575},"\u002Fpl\u002Fdocs\u002Fprzewodniki\u002Farchitektura","Jak zbudowana jest Kleora"," — gdzie\ngranica środowiska leży w działającym systemie.",[579,580,581],"style",{},"html pre.shiki code .sgsFI, html code.shiki .sgsFI{--shiki-default:#24292E}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html pre.shiki code .sYBdl, html code.shiki .sYBdl{--shiki-default:#032F62}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":24,"searchDepth":454,"depth":454,"links":583},[584,585,588,592,593,594],{"id":64,"depth":438,"text":65},{"id":101,"depth":438,"text":102,"children":586},[587],{"id":234,"depth":454,"text":235},{"id":255,"depth":438,"text":256,"children":589},[590,591],{"id":299,"depth":454,"text":300},{"id":330,"depth":454,"text":331},{"id":337,"depth":438,"text":338},{"id":415,"depth":438,"text":416},{"id":559,"depth":438,"text":560},"Pięć słów, z których zbudowany jest produkt, to, które z nich niosą Twoje tokeny, i jak zmiana roli dociera do działającej aplikacji.","md","guides\u002Fconcepts",{},true,20,"\u002Fpl\u002Fdocs\u002Fprzewodniki\u002Fpojecia",false,{"title":5,"description":595},"pl\u002Fdocs\u002Fprzewodniki\u002Fpojecia","bO949xGigoPtclmxAhrdsv-rh9Cu8Hz9-I5I_9VWesU",[607,613,619,624,629,633,639,642,647,652,657,662,663,668],{"path":608,"title":609,"description":610,"order":611,"key":612},"\u002Fpl\u002Fdocs","Dokumentacja Kleora","Dodaj hostowane logowanie do swojej aplikacji, sprawdź token w swoim API i zarządzaj użytkownikami, przestrzeniami roboczymi i rolami z jednej konsoli.",0,"index",{"path":614,"title":615,"description":616,"order":617,"key":618},"\u002Fpl\u002Fdocs\u002Fpierwsze-kroki","Pierwsze kroki","Od pustego projektu do działającego logowania — i paczki, które do tego prowadzą.",10,"getting-started\u002Findex",{"path":620,"title":621,"description":622,"order":600,"key":623},"\u002Fpl\u002Fdocs\u002Fpierwsze-kroki\u002Finstalacja","Instalacja SDK","Pięć paczek, które publikujemy, do czego służy każda z nich i jakiej konfiguracji wymaga.","getting-started\u002Finstallation",{"path":625,"title":626,"description":627,"order":617,"key":628},"\u002Fpl\u002Fdocs\u002Fpierwsze-kroki\u002Fszybki-start","Szybki start","Załóż aplikację, podłącz SDK przeglądarkowe i zaloguj się po raz pierwszy — w całości w sandboksie.","getting-started\u002Fquickstart",{"path":575,"title":576,"description":630,"order":631,"key":632},"Kształt usługi hostowanej — jeden adres na środowisko, dwie powierzchnie API i miejsce, w którym leży stan. Oraz dlaczego hostowania u siebie dzisiaj nie wspieramy.",30,"guides\u002Farchitecture",{"path":634,"title":635,"description":636,"order":637,"key":638},"\u002Fpl\u002Fdocs\u002Fprzewodniki\u002Fframeworki\u002Fexpress","Express","Sprawdzanie tokenu dostępu we własnym API — middleware, uprawnienia i trzy odpowiedzi, jakie może mieć odmowa.",40,"guides\u002Fquickstarts\u002Fexpress",{"path":568,"title":569,"description":640,"order":617,"key":641},"Po jednej stronie na stos — Next.js, Nuxt, Express i zwykła przeglądarka — i dwa adresy powrotne, które łączą je wszystkie.","guides\u002Fquickstarts\u002Findex",{"path":643,"title":644,"description":645,"order":600,"key":646},"\u002Fpl\u002Fdocs\u002Fprzewodniki\u002Fframeworki\u002Fnextjs","Next.js","SDK przeglądarkowe w aplikacji na App Router — leniwy klient, trasa powrotna i sprawdzanie tokenu w route handlerze.","guides\u002Fquickstarts\u002Fnextjs",{"path":648,"title":649,"description":650,"order":631,"key":651},"\u002Fpl\u002Fdocs\u002Fprzewodniki\u002Fframeworki\u002Fnuxt","Nuxt","Moduł dla Nuxt — dwie linijki konfiguracji, strona powrotu, której nie piszesz, i middleware chroniący stronę z jej własnych metadanych.","guides\u002Fquickstarts\u002Fnuxt",{"path":653,"title":654,"description":655,"order":617,"key":656},"\u002Fpl\u002Fdocs\u002Fprzewodniki\u002Fframeworki\u002Fprzegladarka","Zwykła przeglądarka","Jedna instancja klienta, jedna trasa powrotna i token dostępu do każdego żądania, które wysyła Twoja aplikacja.","guides\u002Fquickstarts\u002Fbrowser",{"path":658,"title":659,"description":660,"order":600,"key":661},"\u002Fpl\u002Fdocs\u002Fprzewodniki","Przewodniki","Jak podłączyć usługę Kleora do swojego stosu, jakich słów używa produkt i jak zbudowana jest usługa hostowana.","guides\u002Findex",{"path":601,"title":5,"description":595,"order":600,"key":597},{"path":664,"title":665,"description":666,"order":631,"key":667},"\u002Fpl\u002Fdocs\u002Freferencje","Referencje","Materiały referencyjne dla API HTTP i paczek SDK.","reference\u002Findex",{"path":669,"title":670,"description":671,"order":617,"key":672},"\u002Fpl\u002Fdocs\u002Freferencje\u002Fpodswietlanie","Podświetlanie kodu","Po jednym bloku na każdą wstępnie wczytaną gramatykę Shiki — próbka, nie strona referencyjna.","reference\u002Fcode-highlighting",1790698197990]