nette-sso
nette-sso is a Nette extension for single sign-on over OAuth2 and OpenID Connect, built against Authentik; it keeps state, nonce and PKCE in the session and maps groups to Nette roles from configuration.
nette-sso is a Nette extension that signs users in through an identity provider over OAuth2 and OpenID Connect and turns the provider's response into a Nette identity with a role. A company has a website admin, a warehouse system, a CRM and an internal wiki, each application with its own user table and its own passwords. When a colleague leaves, someone has to remove them in four places, and one usually gets forgotten. With single sign-on the account lives in one system only, for example Authentik, and the applications ask it at sign-in. A blocked account then cannot sign in anywhere.
What the extension adds to the application
The container gains an SsoProvider service with two steps. getAuthorizationUrl() returns the address of the provider's sign-in page, and authenticate($code, $state), after the return, exchanges the authorisation code for an access token and fetches the user's details from the userinfo endpoint. createIdentity() builds a SimpleIdentity from them: the ID is the provider's sub, and the data holds the email, name, username, picture and list of groups. The result can be passed straight to $this->getUser()->login().
What is kept between the redirect and the return
An OAuth2 sign-in consists of two separate requests: leaving for the provider's page and coming back with a code. In the first one the library generates three values and stores them in the sso session section: a random state against a forged return, a nonce and a PKCE verifier, of which only its SHA-256 digest goes into the URL. On the return it compares state with hash_equals(), puts the verifier back into the token exchange, compares the nonce with the nonce field of the ID token in the token endpoint response and deletes all three values from the session, so a single return cannot be used twice. The screenshot above shows the URL with code_challenge_method=S256 and space-separated scopes, the lengths of the stored values, a rejected return with a foreign state and roles derived from the roleGroups setting.
Groups from the provider become roles
The provider sends a groups field in its response. createIdentity() derives the role from it according to the roleGroups setting: a map from role name to the list of groups that grant it. The first role in order that has a match wins; letter case does not matter, and a user with none of the groups gets viewer. The default map is superadmin (groups superadmin, superadmin-webs), admin (admin, administrators, authentik admins) and moderator. A custom map replaces the default entirely, so roles other than those three can be named. Anyone who keeps roles in their own database passes the role as the second parameter of createIdentity() and the groups are not used.
Separately, hasAdminAccess() decides on entry to the administration according to the adminGroups list from the configuration (six groups by default). The two lists are independent: adminGroups does not affect which role createIdentity() returns.
A broken configuration does not get through
The configuration schema requires all six values (client ID and secret, the return URL and three endpoints) and checks that the addresses are valid URLs. adminGroups and roleGroups are optional. The values can be dynamic parameters such as %env.SSO_CLIENT_SECRET%, so the secret does not have to sit in the repository. The extension was written against Authentik, but the endpoints are free to set and the scope openid email profile groups is standard OpenID Connect, so it should be possible to connect another provider that sends groups in a groups field. It has not been tested with any other.
Project status
The current version is 1.2.0 from 6 November 2026; the first version came out on 18 October 2025. Version 1.1.0 from 22 March 2026 added PKCE, constant-time comparison of state and the nonce check. The repository has Nette Tester tests (nine, using a self-made unsigned ID token and a mocked token endpoint response): the scope separator, storing and restoring the PKCE verifier through the session, the nonce check against the ID token, rejection of a foreign state and role mapping. They pass on PHP 8.1 and 8.4.
Limits: the library does not verify the ID token signature. The token arrives directly from the token endpoint over TLS and only the nonce field is read from it. The sso_provider field in the identity data is always set to authentik. A full sign-in against a live Authentik was not tried while writing this text. PHP 8.1 to 8.4 is supported; composer.json excludes PHP 8.5 for now.
Getting started
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]
In Authentik you create an OAuth2/OpenID provider for the application with the return URL and add a group mapping to the response. It needs Nette 3 (nette/di, nette/security, nette/http) and league/oauth2-client 2.7+.
Source code
The code is on GitHub in the nks-hub/nette-sso repository under the MIT licence, and the package is on Packagist as nks-hub/nette-sso. For identity verification through a bank rather than a company account, there is nette-bankid.