eID integrációs útmutató
Teljes fejlesztői dokumentáció
Lépésről lépésre technikai útmutató a rendszerének DÁP eAzonosítás szolgáltatással való integrálásához Relying Party-ként.
Tartalomjegyzék
Áttekintés
Az eAzonosítási folyamatban az Igénybe vevő fél – a DÁP dokumentáció terminológiájában Relying Party – felelős azért, hogy a saját rendszerében képes legyen digitális személyazonosítást fogadni, a bemutatott PID-et és egyéb attribútum-tanúsítványokat ellenőrizni, valamint teljesítse a szükséges kriptográfiai és biztonsági követelményeket.
Az alábbi összefoglaló a magyar Műszaki csatlakozási dokumentáció 1.6-1 alapján készült.
1. Regisztráció és előfeltételek
Az elfogadó fél akkor csatlakozhat az eAzonosítási ökoszisztémához, ha teljesíti az alábbi követelményeket:
- Regisztrálja magát a SZEÜSZ Portálon Relying Party (RP) szerepkörben, ahol nyilvántartásba kerül és megkapja a szükséges tanúsítványait
- Elvégzi a fejlesztést, lefuttatja a csatlakozási folyamatot, feltölti a sikeres teszteket igazoló jegyzőkönyvet
- Rendelkezik egy X.509 szabványú aláírótanúsítvánnyal, amelyet az OpenID4VP folyamatokban benyújtott kérelmek aláírásához használ
A tanúsítványt olyan hitelesítésszolgáltatónak kell kibocsátania, amely szerepel az RP Access CA Trusted List-en.
2. OpenID4VP kliens implementációja
A magyar eAzonosítás OpenID for Verifiable Presentations (OID4VP) szabványra épül, ezért az RP-nek implementálnia kell:
- Az OpenID4VP authorizációs kérés összeállítását és aláírását a kötelező paraméterekkel: client_id, request_uri, request_uri_method=post
- A Request Object kiszolgálását HTTPS POST-on keresztül, úgy, hogy a request_uri domainje megegyezzen a client_id-ben szereplő DNS-sel
- A Wallet Metadata fogadását és felhasználását a Request Object előállításához
- Az authorizációs válaszüzenet (VP + SD-JWT attribútumok) biztonságos fogadását és feldolgozását
Ez gyakorlatban azt jelenti, hogy az RP-nek saját rendszerében egy OpenID4VP-kompatibilis "Verifier kliens" implementációt kell futtatnia.
Kész megoldást keres?
Tekintse meg eID csatlakozási csomagjainkat - SDK és kulcsrakész megoldásokat kínálunk az integráció egyszerűsítéséhez.
eID csomagok megtekintése3. A bemutatott adatok kriptográfiai ellenőrzése
A bemutatás után az RP feladata a következő ellenőrzések elvégzése.
3.1 PID és attribútum-tanúsítvány ellenőrzése
A PID dokumentumon végre kell hajtani:
- A PID Provider tanúsítványának ellenőrzése (érvényesség, visszavonás, hitelesség)
- A PID aláírásának ellenőrzése
- A PID érvényességi idejének vizsgálata
- A PID visszavonási státuszának ellenőrzése a PID ARL listán keresztül
3.2 Device Binding
A tárca a PID-hez tartozó privát kulccsal írja alá a RP által adott kihívást (challenge), így bizonyítva, hogy a bemutatás ugyanazon eszközről történik, amelyre a PID eredetileg kiállításra került.
3.3 Wallet Instance Attestation (WIA) ellenőrzése
Az RP-nek ellenőriznie kell:
- A tárcaszolgáltató tanúsítványának hitelességét a Wallet Provider Trust List alapján
- A WIA érvényességét és visszavonási állapotát
- A WIA eszközhöz kötöttségét (device binding)
4. Bizalmi és visszavonási listák használata
Az RP-nek képesnek kell lennie automatikusan és rendszeresen ellenőrizni a bizalmi és visszavonási listákat.
Bizalmi listák (ETSI TS 119 612)
PID Provider, Wallet Provider, RP Access CA Trust List-ek
Visszavonási listák (ARL)
PID ARL és WIA ARL az érvénytelen igazolványok kiszűréséhez
Ezek szükségesek a visszavont, hamisított vagy érvénytelen tárcák és igazolványok kiszűréséhez.
5. Same-device és cross-device folyamatok
Az RP-nek mindkét OpenID4VP bemutatási módot támogatnia kell:
Same-device flow
A mobilalkalmazás deeplinkkel indul
Cross-device flow
A felhasználó QR-kóddal kapcsolódik a webes felületről
Mindkét esetben ugyanaz az OID4VP kérés-válasz mechanizmus fut le.
6. Sandbox és tesztkörnyezet használata
Az RP-nek a csatlakozás előtt mindkét környezetben tesztelnie kell:
Sandbox környezet
Komponens- és hibaág-tesztelés. Klienstanúsítvány szükséges a belépéshez. A request_uri domainje kötött a regisztrált domainre.
Tesztkörnyezet
Mobilalkalmazás-alapú életszerű tesztelés. Aláírótanúsítvány elegendő. Valós PID helyett teszt-PID biztosított.
7. Üzenetformátumok és hibakezelés
Az RP-nek kezelnie kell:
- Request Object és Authorisation Response JWT / JWE struktúráit
- A hivatalos hibakódok és hibaválaszok formátumát
- A presentation_submission elem validálását
8. Integrációs feladatok - fejlesztői checklist
Az alábbi gyakorlati checklist a teljes RP-oldali feladatlistát összegzi:
Regisztráció és tanúsítványok:
- RP regisztráció a SZEÜSZ Portálon
- X.509 aláírótanúsítványhoz CSR beküldése
- Klienstanúsítvány beszerzése sandboxhoz
OID4VP folyamat implementálása:
- Authorizációs kérés összeállítása (client_id, request_uri, request_uri_method=post)
- Request Object aláírása
- Request Object POST endpoint implementálása
- Wallet Metadata fogadásának és értelmezésének implementálása
- Authorizációs válasz (VP + SD-JWT + WIA) fogadás és feldolgozás
Kriptográfiai ellenőrzések:
- PID aláírás ellenőrzése
- PID Provider tanúsítvány érvényessége
- PID érvényességi idő vizsgálata
- PID visszavonottság (PID ARL) ellenőrzése
- WIA tanúsítvány ellenőrzése
- WIA visszavonási állapot vizsgálata
- Device Binding vizsgálata (challenge PoP)
Bizalmi infrastruktúrák és ARL-ek:
- PID Provider Trust List rendszeres letöltése
- Wallet Provider Trust List letöltése
- RP Access CA Trust List kezelése
- PID ARL és WIA ARL rendszeres frissítése
Tesztelés és környezetek:
- Sandbox teszt lefuttatása teljes funkcionalitással
- Tesztkörnyezetben életszerű folyamattal tesztelés
- Hibaágak és érvénytelen prezentációk kezelésének teljeskörű tesztje
- Minden ellenőrzés auditálható naplózása
Készen áll az integrációra?
Vegye fel velünk a kapcsolatot, és segítünk az eAzonosítás szolgáltatáshoz való csatlakozásban.