Zitadel: építs magadnak saját IAM megoldást

Mi a Zitadel?

A készítői szerint a Zitadel egy nyílt forráskódú identitás- és hozzáférés-kezelési platform, amelyet olyan csapatok számára fejlesztettek ki, amelyeknek az alapvető hitelesítésnél többre van szükségük. Akár egy SaaS-terméket biztosít, akár egy B2B platformot épít, akár egy éles IAM-vermet üzemeltet saját tárhelyen – a Zitadel mindent alapfelszereltségként biztosít: SSO, MFA, jelszók, OIDC, SAML, SCIM és egy csatában tesztelt több-bérlős modell.

Én mire használom?

Van több olyan webes szolgáltatásom, ami kint van a neten, de mégse szeretném, hogy bárki hozzáférjen, ezeket Oauth2 mögé rejtem, ami csak sikeres azonosítás után enged hozzá a valódi tartalomhoz. Az azonosítást régebben a gitea szerverem végezte, aminek nem ez a fő profilja. Munkámból adódóan szükségem volt egy profi megoldásra, így ismertem meg a Zitadelt. Majd villámgyorsan meg is kedveltem, és azóta itthon is ő intézi az azonosításomat. Az SSO képességét is szeretem, azaz egy weboldalon bejelentkezem, majd amíg le nem jár a tokenem, addig bármelyik weboldalamra beléphetek újra azonosítás nélkül. Én a Google Authentikátorral is összekötöttem, így meg van oldva a 2 faktoros belépés. Természetesen használható a Microsoft Authentikátorával is (a cégnél azt használom), és még sok minden mással is, pl, ujjlenyomat érzékelő, kamerás azonosítás, yubikey, stb.

Én perpill dockerben futtatom, de igénybe lehet venni némi dollárért cserébe a felhős üzemeltetést is.

Mire lesz szükségünk az üzemeltetéséhez?

Ha az Internetről is el szeretnénk érni, akkor egy saját „A” rekordra (DNS), lehetőség szerint valid certtel, pl Let’s Encrypt.

Hozz létre egy mappát (pl ~/docker/zitadel) a szervereden, benne pedig több fájlt is:

Reflexből AI segítséggel szoktam mindent beállítani, ám ennél mindegyik csúnyán elvérzett, ugyanis az új változat dokumentálásával elmaradt a Zitadel csapat, azaz hibás adatokkal dolgoznak az AI-ok 🙂

Miután elővettem a jó öreg keresőt, elsőre meg is lett a hivatalos leírás, a lényeget megmutatom, hogy neked ne kelljen mindent elolvasnod.

Lépj be az imént létrehozott mappába, majd töltsd le a fájlokat:

curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/.env.example
cp .env.example .env

Nyissuk meg szerkesztésre a .env fájlt, én az alábbi paramétereket módosítottam:

Ez lesz a Zitadel URL-je:

ZITADEL_DOMAIN=zitadel.domained.hu

Ez pedig a zitadel-proxy (traefik) portja, nálam már foglalt volt a 8080, ha nálad üres, akkor hagyd, ellenkező esetben állítsd egy tetszőleges szabad portra:

PROXY_HTTP_PUBLISHED_PORT=8888

A külvilág felől mely porton lesz elérhető:

ZITADEL_EXTERNALPORT=443

Erősen ajánlott https mögé tenni:

ZITADEL_EXTERNALSECURE=true

ZITADEL_PUBLIC_SCHEME=https

Ahogy írja, generálj egy 32 karakteres mester kulcsot és cseréld le:

ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters

Igény esetén adhatsz egyedi jelszót a pgadmin-nak:

POSTGRES_ADMIN_PASSWORD=**********

Most már el lehet indítani a Zitadelt:

docker compose up -d --wait

Összesen négy konténer fog elindulni:

• az adatbázist PostgreSQL-ben tartja
• a korábban emlegetett traefik
• a zitadel-login
• és a zitadel-api

Arról nem írok, hogy hogyan teszed kintről elérhetővé a zitadelt, számos megoldás létezik ehhez, felteszem, nem ez lesz az első publikus honlapod 🙂

Nálam a Kubernetesen futó istio ingress gateway végzi ezt a feladatot, és a cert-manager segítségével lesz Let’s Encrypt certem.

Hogyan lépünk be az admin felületre?

Ha nem változtattál semmit a .env fájlon, és csak ki akarod próbálni az asztali Linux disztródon, akkor nyisd meg ezt az oldalt: http://localhost:8080/ui/console?login_hint=zitadel-admin@zitadel.localhost

A kezdeti jelszó:

Password1!

Ha átállítottad a ZITADEL_DOMAIN változót, akkor a fenti példánál maradva erre módosul a belépési link: https://zitadel.domained.hu/ui/console?login_hint=zitadel-admin@zitadel.zitadel.domained.hu

A jelszó itt is ugyanaz lesz.

Azaz a Zitadel admin felhasználó nevében minden esetben benne van a zitadel domain-je!

Sikeres beléps után ez a felület fogad minket:

Ha szeretnéd magyarra átállítani, így teheted:

Azt javaslom, hogy minden fiókhoz állíts 2 faktoros hitelesítést vagy passkeyt, de ennél mindenképpen:

Végig nézheted a főmenüt, de ne állíts el semmit, mert elromolhat a zitadel!

Inkább hozzunk létre egy új szervezetet magunknak:

Már csak rá kell kattintai a létrejött szervezetre:

Hozzunk létre egy projektet:

Adjunk neki nevet, majd Folytatás:

A projekt általános menüjében ezt be szoktam kapcsolni:

Ha be van kapcsolva, csak az a felhasználó jelentkezhet be az alá tartozó weboldalakba, akinek van valamilyen szerepköre. Ha nincs bekapcsolva, ennek a szervezetnek minden felhasználója (aki nincs letiltva) be fog tudni jelentkezni!

Hozzunk létre egy szerepkört, bármi lehet a neve, nincs jelentősége, kivéve ha a weboldalunk elvár valamilyen spéci értéket:

Nem kell túlbonyolítani:

Lépjünk vissza az Általános menüre, és hozzuk létre az első alkalmazásunkat:

Adj neki nevet, majd válaszd ki a számodra megfelelő típust, nálam az összes a WEB kategóriába tartozik (ha tévedtél, utólag sok minden módosítható, legfeljebb törlöd, és újra létrehozod):

Nálam az összes weboldal a CODE típusú hitelesítési módszerrel dolgozik:

Most meg kell adni az átirányításokat, pl https://weboldalad.domained.hu/oauth2/callback formátumban. A kijelentkezés utáni opcionális, ha van az oldaladnak login linkje, írd be azt, pl: https://weboldalad.domained.hu/login. A fejlesztői módot akkor kell bekapcsolni, ha az oldalad nem tud https módot. A + gombbal mentheted el az URL-eket:

Utolsó ellenőrzés, itt még vissza lehet lépni bármelyik menübe:

Amint rákattintasz a Létrehozás gombra, megjelenik a ClientId és a ClientSecret értéke, ezeket tedd biztonságos helyre, mert többé nem látod. Ha elhagytad, lehet újat generáltatni:

Ezt a két változót kell a weboldalad megfelelő beállításainál megadni, ez a cikk most nem erről szól, nyugi, fogok írni egy másikat, ami igen 😉

Hozzunk létre legalább két felhasználót, az egyikkel be fogunk tudni lépni, a másikkal nem:

Töltsük ki az adatokat, a bekeretezett részben látható két mezőt pipáljuk be, így nem küld e-mail-t (nem is tud, mivel még nem állítottuk be):

Ha már itt vagyunk, válasszuk ki a Szerepkör hozzárendelések menüpontot, és adjuk hozzá a demó projekthez:

Pipáljuk be az „user” szerepkört:

Az imént bemutatott módon hozzunk létre még egy felhasználót, de neki ne állítsunk be szerepkört!

Ha ellenőrzésképpen visszanavigálunk a demo projektünkhöz, láthatjuk, hogy Béla megjelent a Szerepkör hozzárendelések menü alatt:

Mit érdemes még megemlíteni?

Például azt, hogy a Szerepkör hozzárendelések menü alatt minden felhasználót listázni fog, akinek legalább egy szerepköre van:

Érdemes ellátogatni a Beállítások menüpontra, és kötelezővé tenni a kétfaktoros belépést mindenkinek, aki a demo szervezet tagja:

Érdemes lehet a próbálkozások számát limitálni:

Erősen mókusvakítás jellegű, de a bejelentkező képernyőt is testre lehet szabni:

Külön képet lehet feltölteni a világos és a sötét témához is.

Ne számíts nagy dologra, kb így fog kinézni a login képernyő (sötét módban):

Nem túl nagy a feltöltött kép 🙁

Ha váltani akarunk a szervezetek között, bal felül kattintsunk a ^ ikonra:

Itt tudunk létrehozni újat is.

Erősen ajánlott megtiltani, hogy bárki regisztrálhasson felhasználót:

Ha megcsináljátok a fent említett szerepkör hozzáadást (user), akkor nem fog tudni belépni a webes alkalmazásba, de jobb a békesség, a felhasználók kezelését kis szervezetek esetén kezelje a zitadel admin, nagyobb cégeknél pedig az erre kijelölt felhasználók. Ezt a beállítást el kell végezni minden szervezetnél, a ZITADEL-nél is!

Ha már emlegettem, hogyan nevezhetsz ki egy szervezethez egy vagy több embert, aki tudja a felhasználókat menedzselni?

Menj a kívánt szervezethez, majd jobb felül +:

Válaszd ki a kívánt személyt, és állítsd be neki az alábbi jogosultságot:

Nem kell megijedni, több menüpontot is fog látni Béla, de módosítani csak a felhasználókat fogja tudni! Ahogy a képen látszik, több jogot is adhatunk egy személynek. Én azt javaslom, hogy hozzatok létre magatoknak egy admin usert, adjatok neki Org Owner jogot, és akkor a zitadel admin usert félre lehet tenni.

SMTP hozzáadása

Zitadel adminnal látjuk jobb fölül az Alapértelmezett beállítások menüpontot:

Keressük meg a bal oldali menüben az SMTP szolgáltató almenüt, és válasszuk ki a megfelelő szolgáltatót. Ha nem találod a listában, válaszd a Generic SMTP lehetőséget:

Töltsük ki a mezőket, kinek lesz ismerős a mailcow?

Teszteljük le, majd ha jó, Létrehozás:

A sikeres teszt után aktiválni is kell:

Csak akkor lesz sikeres a teszt, ha az SMTP szerverednek is rendben vannak a certjei…

Teszteljünk

Próbáljunk meg bejelentkezni inkognitó módban az új felhasználónkkal:

A kezdeti jelszót meg kell változtatni a felhasználónak:

A bejelentkezett felhasználó minden adatát módosíthatja (természetesen másik, létező felhasználó azonosítóját, e-mail címét nem veheti fel):

Mi történik, ha bejelentkezéskor nem tudjuk a jelszót? Kérjünk újat!

Írjuk be a levélben kapott kódot, kétszer az új jelszót, végül Continue:

Ennyi

Tudom, hogy nem teljes a kép, mivel a másik oldalról most nem írtam, de ahány alkalmazás, annyi féleképpen kell őket beállítani.

Eddig egy kubernetesben futó gitlabot és argocd-t kötöttem hozzá, valamint outh2 mögé rejtve kb egy tucat weboldalam.

Ja és arról is tervezek írni, hogy a Zitdelt Kubernetesbe költöztettem.

Ha valamit kifelejtettem, csak kérdezz rá a lap alján.