nette-sso

nette-sso je rozšíření pro Nette, které přihlašuje přes OAuth2 a OpenID Connect (psané proti Authentiku), drží state, nonce a PKCE v session a role Nette odvodí ze skupin podle konfigurace.

nette-sso: přihlašovací adresa s PKCE, hodnoty uložené v session, odmítnutý cizí state a role odvozené ze skupin podle roleGroups

nette-sso je rozšíření pro Nette, které přihlašuje uživatele přes poskytovatele identity s protokolem OAuth2 a OpenID Connect a z jeho odpovědi vytvoří identitu Nette s rolí. Firma má administraci webu, sklad, CRM a interní wiki, každou aplikaci s vlastní tabulkou uživatelů a vlastními hesly. Když kolega odejde, musí ho někdo zrušit na čtyřech místech, a na jedno se obvykle zapomene. S jednotným přihlášením je účet jen v jednom systému, například v Authentiku, a aplikace se ho při přihlášení ptají. Zablokovaný účet se pak nepřihlásí nikam.

Co rozšíření přidá do aplikace

Do kontejneru přibude služba SsoProvider se dvěma kroky. getAuthorizationUrl() vrátí adresu přihlašovací stránky poskytovatele a authenticate($code, $state) po návratu vymění autorizační kód za přístupový token a stáhne údaje o uživateli z koncového bodu userinfo. createIdentity() z nich složí SimpleIdentity: ID je sub od poskytovatele, v datech jsou e-mail, jméno, uživatelské jméno, obrázek a seznam skupin. Výsledek jde rovnou předat do $this->getUser()->login().

Co se drží mezi přesměrováním a návratem

Přihlášení přes OAuth2 jsou dva oddělené požadavky: odchod na stránku poskytovatele a návrat s kódem. Knihovna si v prvním vygeneruje tři hodnoty a uloží je do sekce session sso: náhodný state proti podvrženému návratu, nonce a ověřovací kód PKCE, z něhož do adresy putuje jen jeho otisk SHA-256. Při návratu porovná state funkcí hash_equals(), ověřovací kód vrátí do výměny tokenu, nonce porovná s polem nonce v ID tokenu z odpovědi token endpointu a všechny tři hodnoty ze session smaže, takže jeden návrat nejde použít dvakrát. Na snímku nahoře je vidět adresa s code_challenge_method=S256 a rozsahy oddělenými mezerou, délky uložených hodnot, odmítnutý návrat s cizím state a role odvozené podle nastavení roleGroups.

Skupiny z poskytovatele se mění na role

Poskytovatel posílá v odpovědi pole groups. createIdentity() z něj odvodí roli podle nastavení roleGroups: mapy názvu role na seznam skupin, které ji dávají. Platí první role v pořadí, ve kterém je shoda; velikost písmen nehraje roli, a kdo nemá žádnou ze skupin, dostane viewer. Výchozí mapa je superadmin (skupiny superadmin, superadmin-webs), admin (admin, administrators, authentik admins) a moderator. Vlastní mapa výchozí nahradí celou, takže jde pojmenovat i jiné role než ty tři. Kdo vede role ve vlastní databázi, předá roli jako druhý parametr createIdentity() a skupiny se nepoužijí.

Zvlášť je hasAdminAccess(), která rozhoduje o vstupu do administrace podle seznamu adminGroups z konfigurace (výchozích je šest skupin). Oba seznamy jsou nezávislé: adminGroups neovlivní, jaká role z createIdentity() vyjde.

Chybná konfigurace neprojde

Schéma konfigurace vyžaduje všech šest údajů (ID a tajemství klienta, adresu návratu a tři koncové body) a u adres kontroluje, že jde o platnou URL. Volitelné je adminGroups a roleGroups. Hodnoty můžou být dynamické parametry %env.SSO_CLIENT_SECRET%, takže tajemství nemusí být v repozitáři. Rozšíření je napsané proti Authentiku, koncové body jsou ale volné a rozsah oprávnění openid email profile groups je standardní OpenID Connect, takže by mělo jít připojit i jiného poskytovatele, který posílá skupiny v poli groups. Vyzkoušené to s jiným není.

Stav projektu

Aktuální je verze 1.2.0 z 6. listopadu 2026, první verze vyšla 18. října 2025. Verze 1.1.0 z 22. března 2026 přidala PKCE, porovnání state v konstantním čase a kontrolu nonce. Repozitář má testy v Nette Tester (devět, s vlastním nepodepsaným ID tokenem a zaslepenou odpovědí token endpointu): oddělovač rozsahů, uložení a vrácení ověřovacího kódu PKCE přes session, kontrola nonce z ID tokenu, odmítnutí cizího state a mapování rolí. Projdou na PHP 8.1 i 8.4.

Omezení: podpis ID tokenu knihovna neověřuje. Token přichází přímo z token endpointu přes TLS a čte se z něj jen pole nonce. V datech identity je pole sso_provider vždy nastavené na authentik. Plné přihlášení proti živému Authentiku nebylo v rámci psaní tohoto textu zkoušené. Podporované je PHP 8.1 až 8.4, PHP 8.5 composer.json zatím vylučuje.

Jak začít

composer require nks-hub/nette-sso
extensions:
    sso: NksHub\NetteSso\DI\SsoExtension

sso:
    clientId: %env.SSO_CLIENT_ID%
    clientSecret: %env.SSO_CLIENT_SECRET%
    redirectUri: 'https://app.example.com/auth/callback'
    authorizeUrl: 'https://sso.example.com/application/o/authorize/'
    tokenUrl: 'https://sso.example.com/application/o/token/'
    userinfoUrl: 'https://sso.example.com/application/o/userinfo/'
    adminGroups: [admin, superadmin, moderator]
    roleGroups:
        admin: [authentik admins, sso-admins]
        editor: [sso-editors]

V Authentiku se pro aplikaci založí poskytovatel OAuth2/OpenID s adresou návratu a do odpovědi se přidá mapování skupin. Potřeba je Nette 3 (nette/di, nette/security, nette/http) a league/oauth2-client 2.7+.

Zdrojový kód

Kód je na GitHubu v repozitáři nks-hub/nette-sso pod licencí MIT, balíček na Packagistu jako nks-hub/nette-sso. Pro ověření totožnosti přes banku místo firemního účtu je tu nette-bankid.

← Všechny reference