nette-bankid

nette-bankid is a Nette extension for identity verification through the Czech BankID: sign-in at the user's own bank at LOA3, name, email, birthdate and phone, sandbox and production.

nette-bankid: the BankID sandbox sign-in address with space-separated scopes, LOA3 and PKCE, and a rejected foreign state

nette-bankid is a Nette extension through which an application verifies a person's identity using the Czech BankID, that is, by signing in to their online banking. A website where people apply to rent a flat needs to know that the application was sent by a real person with this name and date of birth, not by someone who opened an account with another person's email. A photo of an ID card can be faked and manual checks take time. The bank identified its client when the account was opened; through BankID it passes this information to the application on request, once the client has explicitly agreed.

How the sign-in works

BankID uses the OpenID Connect protocol. The application redirects the user to the BankID page, where they choose their bank, sign in and confirm which details will be shared. The bank then sends them back to the return URL with a one-time code, and the application exchanges it for an access token and the user's details. The extension wraps these steps in the BankIdProvider class: getAuthorizationUrl() builds the redirect URL, and authenticate() checks state, exchanges the code (with the PKCE verifier from the session, which it deletes after use), checks the nonce in the ID token and fetches the details. The application keeps state and nonce between the redirect and the return; the extension only hands them out through getState() and getNonce().

The screenshot above shows the real URL the extension built in sandbox mode, with the scopes separated by spaces and a PKCE verifier stored in the session, of which only its SHA-256 digest goes into the URL. It requests the assurance level acr_values=loa3, meaning a banking identity, and prompt=login, so the user has to sign in again even with a live session at the bank. The endpoint addresses for the sandbox and production are constants in the code; on 6 November 2026 they matched what BankID publishes in its .well-known/openid-configuration document, which lists loa3 as the only supported level.

What the application receives

By default the extension asks for the name, email, date of birth and phone number (profile.name, profile.email, profile.birthdate, profile.phonenumber). The userinfo response brings the fields sub (the person's permanent identifier at BankID), given_name, family_name, email, birthdate, phone_number and acr. BankID offers the address (returned as the addresses field) or the Czech personal identification number in further scopes, such as profile.addresses, which can be added through the scope parameter of getAuthorizationUrl(). createReporterData() builds a structure for storage from the response: full name, contact details, date of birth, bankid_sub, the time of verification and the assurance level.

Storage is up to the application. The extension has no tables or entities of its own; the README shows an example with Doctrine.

Sandbox, production and debugging

The sandbox switch chooses between the BankID test and production environments. The sandbox is available after registering on the developer portal; production access requires certification and a contract. With debug: true, Tracy gains a BankID panel with the mode, the return URL, the verified user's details and the time of each step in milliseconds; the same events are written to log/bankid.log. Both the panel and the log contain personal data, so they belong in development only. Tracy is optional (tracy/tracy is listed in suggest); without it, logging is skipped. Tokens are not written to the log. Custom endpoints can be set in the configuration; the extension has no default Slovak addresses, and with country: sk and no custom endpoints it throws an exception.

Project status and limits

The current version is 1.1.1 from 6 November 2026; 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 (eight, 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 and rejection of a foreign state. They pass on PHP 8.1 and 8.4.

What the extension does not do: it 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; validation through JWKS is not implemented. The extension has not been tried against production BankID, nor against the sandbox with a real person signing in, because that needs a developer account or contractual access. Slovak endpoints are missing.

Getting started

composer require nks-hub/nette-bankid
extensions:
    bankid: NksHub\NetteBankId\DI\BankIdExtension

bankid:
    clientId: %env.BANKID_CLIENT_ID%
    clientSecret: %env.BANKID_CLIENT_SECRET%
    redirectUri: 'https://example.com/bankid/callback'
    sandbox: true

It needs PHP 8.1 to 8.4, Nette 3 or 4, league/oauth2-client 2.7+ and a developer account at developer.bankid.cz. The return URL in the configuration must match the one registered on the portal exactly.

Source code

The code is on GitHub in the nks-hub/nette-bankid repository under the MIT licence, and the package is on Packagist as nks-hub/nette-bankid. For signing employees in with a company account, there is nette-sso.

← Back to overview