nette-bankid

nette-bankid je rozšíření pro Nette, které ověří totožnost přes české BankID: přihlášení do vlastní banky na úrovni LOA3, jméno, e-mail, datum narození a telefon, sandbox i produkce, panel v Tracy.

nette-bankid: přihlašovací adresa BankID v režimu sandbox s rozsahy oddělenými mezerou, LOA3 a PKCE, odmítnutý cizí state

nette-bankid je rozšíření pro Nette, přes které aplikace ověří totožnost člověka pomocí BankID, tedy přihlášením do jeho internetového bankovnictví. Web, kde lidé podávají žádost o pronájem bytu, potřebuje vědět, že ji poslal skutečný člověk s tímhle jménem a datem narození, a ne někdo, kdo si založil účet na cizí e-mail. Fotka občanky jde podvrhnout a ruční kontrola stojí čas. Banka svého klienta při založení účtu identifikovala; přes BankID tenhle údaj na žádost předá aplikaci, když s tím klient výslovně souhlasí.

Jak přihlášení probíhá

BankID používá protokol OpenID Connect. Aplikace přesměruje uživatele na stránku BankID, ten si vybere svou banku, přihlásí se a potvrdí, jaké údaje se předají. Banka ho pak vrátí na adresu návratu s jednorázovým kódem a aplikace si za něj vyzvedne přístupový token a údaje o uživateli. Rozšíření tyto kroky obaluje třídou BankIdProvider: getAuthorizationUrl() sestaví adresu přesměrování, authenticate() ověří state, vymění kód (s ověřovacím kódem PKCE ze session, který po použití smaže), ověří nonce v ID tokenu a stáhne údaje. Hodnoty state a nonce si mezi přesměrováním a návratem drží aplikace, rozšíření je jen vrací z getState() a getNonce().

Snímek nahoře ukazuje skutečnou adresu, kterou rozšíření sestavilo v režimu sandbox, tedy rozsahy oprávnění oddělené mezerou a ověřovací kód PKCE uložený v session, ze kterého do adresy putuje jen otisk SHA-256. Požaduje úroveň ověření acr_values=loa3, tedy bankovní identitu, a prompt=login, takže se uživatel musí přihlásit znovu i s živou relací v bance. Adresy koncových bodů pro sandbox i produkci jsou v kódu jako konstanty; 6. listopadu 2026 se shodovaly s tím, co BankID zveřejňuje ve svém dokumentu .well-known/openid-configuration, a ten jako jedinou podporovanou úroveň uvádí právě loa3.

Co aplikace dostane

Ve výchozím stavu žádá rozšíření o jméno, e-mail, datum narození a telefon (profile.name, profile.email, profile.birthdate, profile.phonenumber). Z odpovědi userinfo přijdou pole sub (trvalý identifikátor osoby u BankID), given_name, family_name, email, birthdate, phone_number a acr. Adresu (v odpovědi pole addresses) nebo rodné číslo BankID nabízí v dalších rozsazích, například profile.addresses, které jde přidat přes parametr scope v getAuthorizationUrl(). createReporterData() složí z odpovědi strukturu pro uložení: celé jméno, kontakty, datum narození, bankid_sub, čas ověření a úroveň ověření.

Ukládání je na aplikaci. Rozšíření nemá vlastní tabulky ani entity, README ukazuje příklad s Doctrine.

Sandbox, produkce a ladění

Přepínač sandbox volí mezi testovacím a produkčním prostředím BankID. Sandbox je dostupný po registraci na vývojářském portálu, produkční přístup vyžaduje certifikaci a smlouvu. S debug: true přibude v Tracy panel BankID s režimem, adresou návratu, údaji ověřeného uživatele a časem každého kroku v milisekundách; tytéž události se zapisují do log/bankid.log. Panel i log obsahují osobní údaje, proto patří jen do vývoje. Tracy je volitelná (tracy/tracy je v suggest), bez ní se logování přeskočí. Tokeny se do logu nezapisují. Vlastní koncové body jde nastavit v konfiguraci, slovenské výchozí adresy rozšíření nemá a s country: sk bez nich skončí výjimkou.

Stav projektu a omezení

Aktuální je verze 1.1.1 z 6. listopadu 2026; 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 (osm, 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 a odmítnutí cizího state. Projdou na PHP 8.1 i 8.4.

Co rozšíření nedělá: podpis ID tokenu neověřuje. Token přichází přímo z token endpointu přes TLS a čte se z něj jen pole nonce; ověření přes JWKS není implementované. Proti produkčnímu BankID ani proti sandboxu s přihlášením skutečné osoby nebylo rozšíření zkoušené, protože to vyžaduje vývojářský účet, respektive smluvní přístup. Slovenské koncové body chybí.

Jak začít

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

Potřeba je PHP 8.1 až 8.4, Nette 3 nebo 4, league/oauth2-client 2.7+ a vývojářský účet na developer.bankid.cz. Adresa návratu musí v konfiguraci přesně odpovídat té, která je zaregistrovaná na portálu.

Zdrojový kód

Kód je na GitHubu v repozitáři nks-hub/nette-bankid pod licencí MIT, balíček na Packagistu jako nks-hub/nette-bankid. Pro přihlášení zaměstnanců přes firemní účet je tu nette-sso.

← Všechny reference