Mwongozo wa mthibitishaji wa OpenID4VP: kukubali pochi ya EUDI

Ilikaguliwa mara ya mwisho: 5 Oktoba 2026 · Si ushauri wa kisheria

OpenID4VP ni njia ambayo tovuti au programu huomba pochi ithibitishe jambo fulani kuhusu mtu, kama jina au tarehe ya kuzaliwa. Mthibitishaji anaeleza hati tambulishi na madai anayoyataka, mtumiaji anaidhinisha ndani ya pochi, na pochi inarudisha wasilisho ambalo mthibitishaji analikagua kwa njia ya kriptografia. Kwa maneno ya vipimo vyenyewe, "inafafanua itifaki ya kuomba na kuwasilisha hati tambulishi".^[1]

Mwongozo huu ni kwa wasanidi programu wanaojenga mthibitishaji wa OpenID4VP kwa pochi ya EUDI: kitu cha ombi (request object), DCQL, njia za majibu, mitiririko ya vifaa, ukaguzi wa SD-JWT VC na mdoc, kanuni za HAIP katika sheria ya Umoja wa Ulaya, makosa ya kawaida na mahali pa kufanya majaribio.

OpenID4VP kwa maneno rahisi

OpenID4VP inatumia upya muundo wa ombi la uidhinishaji la OAuth 2.0. Mthibitishaji anaomba aina ya jibu vp_token, na jibu lililofanikiwa lazima liwe na kigezo cha vp_token kinachobeba mawasilisho.^[1] Hakuna msimbo wala tokeni ya ufikiaji ya kubadilishana: data inafika ndani ya jibu.

Pochi inamthibitisha mhusika anayetegemea (relying party), inakagua kwamba haombi zaidi ya kile alichosajili, inakusanya idhini ya mtumiaji na inatia saini wasilisho. Kisha mhusika anayetegemea anathibitisha saini ya mtoaji, hali ya ubatilishaji na ufungaji kwa kifaa (device binding).^[3] Data ya utambulisho wa mtu (PID) inatolewa katika miundo miwili, SD-JWT VC na ISO/IEC mdoc, na yote miwili inatumia hashi zenye chumvi (salted hashes) ili mtumiaji ashiriki baadhi ya sifa na kuficha zilizobaki.^[5][3]

1. 10 Julai 2025Vipimo vya mwishoOpenID4VP 1.0 iliidhinishwa.
2. 22 Julai 2026ImechapishwaCIR 2026/1731 (iliyopitishwa 15 Julai 2026) katika Gazeti Rasmi (Official Journal).
3. 23 Julai 2026ARF v3.0.0Toleo la sasa la usanifu.
4. 24 Desemba 2026PochiAngalau moja kwa kila Nchi Mwanachama.
5. 24 Desemba 2027UkubalikajiWahusika binafsi wanaotegemea walio chini ya udhibiti.

Kuanzia vipimo vya mwisho hadi tarehe ya ukubalikaji kwa sekta binafsi.^[2][3][4][5]

Jinsi ubadilishanaji wa mthibitishaji wa OpenID4VP unavyofanya kazi

OpenID4VP inachapisha muundo wa marejeleo kwa njia ya majibu direct_post, ambapo pochi inatuma jibu moja kwa moja kwenye endpoint ya seva badala ya kulipitisha kupitia kivinjari.^[1]

Muundo wa marejeleo wa direct_post katika OpenID4VP 1.0, sehemu ya 13.3, uliorahisishwa.^[1]

• Tengeneza nonce ya "angalau baiti 16 mpya, za nasibu kikriptografia" kwa kila ombi.
• Tuma kitambulisho cha ombi (request-id) kutoka kwenye sehemu ya kupokelea majibu (response endpoint) kwenda kwenye pochi kama state.
• Rudisha URI ya kuelekeza upya yenye response_code mpya mara pochi inapotuma jibu.
• Pata VP Token kwa kutumia transaction-id na msimbo huo, kisha kagua nonce.

response_code huzuia shambulio la kufunga kipindi (session fixation), ambapo mshambulizi hupeleka ombi lako kwenye pochi ya mwathiriwa. Vipimo vinaeleza kuwa haisaidii kati ya vifaa tofauti na vinapendekeza mbinu za ziada katika hali hiyo.^[1]

Request object ya OpenID4VP na vitambulisho vya mteja

client_id huanza na Kiambishi Awali cha Kitambulisho cha Mteja kinachoiambia pochi jinsi ya kuthibitisha uhalali wa mthibitishaji.^[1] Maombi makubwa hutumwa kwa marejeleo: pochi huchukua request object iliyosainiwa kutoka kwenye request_uri. Kwa misimbo ya QR, vipimo vinapendekeza direct_post pamoja na request_uri, kwa kuwa ombi "huenda lisitoshe kwenye msimbo wa QR".^[1]

Viambishi Awali vya Kitambulisho cha Mteja (Client Identifier Prefixes), OpenID4VP 1.0 sehemu ya 5.9.^[1]

Kwa wathibitishaji wa EUDI, sheria ya Umoja wa Ulaya ndiyo inayochagua kiambishi awali: cheti cha mwisho (leaf certificate) "kwa matumizi na Kiambishi Awali cha Kitambulisho cha Mteja x509_hash kitakuwa cheti cha ufikiaji cha RP kama kilivyobainishwa katika ETSI TS 119 475", na kipengele kimoja cha verifier_info "kitajumuisha cheti cha usajili".^[5]

Hoja za DCQL: omba kile ulichosajili

Digital Credentials Query Language (DCQL) ni hoja ya JSON inayotaja vitambulisho (credentials) na madai (claims) unayoyataka. Ina safu ya lazima ya credentials na safu ya hiari ya credential_sets. Kila hoja ya kitambulisho inahitaji id, format na kitu cha meta.^[1] Mfano wa SD-JWT VC kutoka kwenye vipimo:^[1]

{ "credentials": [ { "id": "my_credential", "format": "dc+sd-jwt", "meta": { "vct_values": [ "https://credentials.example.com/identity_credential" ] }, "claims": [ {"path": ["last_name"]}, {"path": ["first_name"]}, {"path": ["address", "street_address"]} ] } ] }

Kwa mdoc, muundo ni mso_mdoc na meta hubeba doctype_value.^[1] Kwa PID, weka aina yake na majina ya madai yake. Sifa za lazima za PID ni jina la ukoo, jina la kwanza, tarehe ya kuzaliwa, mahali pa kuzaliwa na uraia.^[7]

• require_cryptographic_holder_binding ina thamani chaguo-msingi ya true. Ibakize: inaifanya pochi irudishe uthibitisho wa ufungaji wa ufunguo (key binding proof).^[1]
• trusted_authorities huchuja tu kile ambacho pochi inatoa. Wathibitishaji "lazima wathibitishe wenyewe kwamba mtoaji wa wasilisho lililopokelewa anaaminika".^[1]
• Wahusika wanaotegemea (relying parties) "hawataruhusiwa kuwaomba watumiaji kutoa data yoyote isipokuwa" kile walichosajili, na pochi hukagua.^[4][3]

Njia za majibu za OpenID4VP

Njia ya majibu huamua jinsi VP Token inavyorudi. Chaguo-msingi kwa vp_token ni fragment, katika kipande (fragment) cha URI ya kuelekeza upya.^[1]

Njia za majibu katika OpenID4VP 1.0.^[1]

Kwa direct_post, response_uri inahitajika na redirect_uri lazima isiwepo, la sivyo pochi hurejesha invalid_request.^[1] Kwa mfano, EVO Wallet ya Moldova inaeleza katika nyaraka zake OpenID4VP 1.0 pamoja na direct_post.jwt katika mtiririko wa kifaa kimoja, mdoc ya ISO/IEC 18013-5 iliyowekewa wasifu kwa mujibu wa OpenID4VC HAIP 1.0, na IETF Token Status List kwa ajili ya ubatilishaji.^[11]

Kifaa kimoja, vifaa tofauti na Digital Credentials API

ARF inaorodhesha michanganyiko ya mbali inayoungwa mkono: OpenID4VP pamoja na utaratibu wa usafirishaji unaotegemea uelekezaji upya na mifumo maalum ya URI (custom URI schemes); OpenID4VP au ISO/IEC 18013-7 pamoja na W3C Digital Credentials API; na, kwa hiari, ISO/IEC 18013-7 pamoja na uelekezaji upya na mifumo maalum ya URI.^[3]

Njia tatu ambazo pochi hupokea ombi la OpenID4VP.^[3][1][10]

ARF inasema mifumo maalum ya URI "haipendekezwi kwa mitiririko ya vifaa tofauti" na inataja Digital Credentials API kama mbadala.^[3] Kupitia API hiyo, pochi inapata asili (origin) ya mthibitishaji kama ilivyothibitishwa na kivinjari, "jambo ambalo ni muhimu kwa ustahimilivu dhidi ya hadaa".^[1] Vipimo vya W3C bado ni rasimu.^[9] Kile mtumiaji anachoona kwenye simu:

Kuthibitisha uwasilishaji wa SD-JWT VC hatua kwa hatua

Uwasilishaji wa SD-JWT VC unabeba JWT iliyosainiwa na mtoaji, ufichuzi ambao mtumiaji aliufichua na Key Binding JWT. Mthibitishaji "LAZIMA athibitishe kila Verifiable Presentation moja moja" na akatae yoyote yenye nonce isiyo sahihi.^[1]

Ukaguzi wa mthibitishaji kwenye uwasilishaji mmoja wa SD-JWT VC.^[1][3]

Saini ya mtoaji. ARF inaiweka ya kwanza katika ukaguzi wa upande unaotegemea (relying party). Vianzo vya uaminifu (trust anchors) vinatoka kwenye Orodha za Kuaminika (Trusted Lists, ETSI TS 119 612) na Orodha za Taasisi Zinazoaminika (Lists of Trusted Entities, ETSI TS 119 602).^[3]

Ufichuzi. Maudhui yaliyosainiwa yana safu ya _sd ya muhtasari (digests); kila ufichuzi ni chumvi (salt), jina la dai na thamani, kwa mfano ["eluV5Og3gSNII8EYnsxA_A", "family_name", "Doe"].^[1] Tengeneza hashi ya kila mmoja na utafute muhtasari wake. Kukosekana kwa ulinganifu kunamaanisha kwamba mtoaji hakuusaini.

Key Binding JWT. Pale ambapo ufungaji kwa mmiliki (holder binding) unahitajika, pochi "LAZIMA irudishe SD-JWT pamoja na Key Binding JWT". nonce yake lazima ilingane na nonce ya ombi lako, na aud yake ilingane na Client Identifier yako, au, kupitia Digital Credentials API, origin yako ikitanguliwa na origin:.^[1] Mfano kutoka kwenye vipimo (specification):

{ "nonce": "n-0S6_WzA2Mj", "aud": "x509_san_dns:client.example.org", "iat": 1709838604, "sd_hash": "Dy-RYwZfaaoC3inJbLslgPvMp09bH-clYP_3qbRqtW4" }

Ubatilishaji. Upande unaotegemea unathibitisha kwamba mtoa huduma "hakubatilisha PID au uthibitisho".^[3] EVO Wallet ya Moldova, kwa mfano, inaeleza IETF Token Status List kwa ajili ya hili.^[11]

Uwasilishaji wa mdoc kupitia ISO/IEC 18013-7, kwa ufupi

Kwa mdoc, VP Token hubeba DeviceResponse iliyosimbwa kwa base64url kutoka ISO/IEC 18013-5 ambayo "ina sahihi au MAC juu ya SessionTranscript", ikijumuisha muundo wa handover wa OpenID4VP.^[1] Handover hiyo inafunga mdoc kwenye ombi lako, kama nonce na audience zinavyofunga SD-JWT VC.

Ulinganisho wetu wa SD-JWT VC dhidi ya mdoc unaeleza ni lini kila muundo unafaa.

Kile ambacho wasifu wa HAIP unaongeza kwa wathibitishaji wa EUDI

High Assurance Interoperability Profile (HAIP) inapunguza chaguo za OpenID4VP. ARF tayari inaitaka kwa utoaji, ikisema matumizi yake "ni muhimu ili kuhakikisha utangamano".^[3] Kwa uwasilishaji, CIR 2026/1731 inaweka "wasifu wa OpenID4VC-HAIP" na "wasifu wa ISO/IEC-mdoc".^[5]

Cheti cha usajili "kinaeleza matumizi yaliyokusudiwa ya mhusika anayetegemea na kinaonyesha sifa" alizosajili, na kanuni ya usajili inatumika kuanzia tarehe 24 Desemba 2026.^[6] Tarehe ya 11 Agosti 2028 inahusu tu ukaguzi wa cheti hicho upande wa pochi, si usajili.^[5] Ujerumani inafupisha hivi: shirika "hupokea cheti cha ufikiaji na cha usajili kwa shirika na kwa matumizi husika".^[12] Mwongozo wetu wa mhusika anayetegemea pochi ya EUDI unaeleza usajili kikamilifu.

Makosa ya kawaida wakati wa kujenga mthibitishaji wa OpenID4VP

Pochi pia ni ya hiari: ufikiaji "hautazuiliwa kwa njia yoyote wala kufanywa kuwa na hasara" kwa watu wasioitumia, kwa hivyo mthibitishaji wako anakaa pamoja na njia nyingine.^[4]

Rasilimali za majaribio

Anza na programu ya marejeleo na majaribio ya ulinganifu kabla ya kujaribu dhidi ya pochi za kitaifa.

• Endesha majaribio ya ulinganifu kwenye conformance.eudi.dev.^[3]
• Soma nyaraka za utekelezaji wa marejeleo kwenye docs.eudi.dev, ambazo ni nyaraka, si majaribio.^[3]
• Chunguza mthibitishaji wa maonyesho wa Benki ya Taifa ya Moldova na msimbo wake chanzo.^[13]
• Kagua rasimu ya Digital Credentials API kabla ya kutegemea njia ya kivinjari.^[9]

Kwa tarehe zinazoongoza mpango wako wa majaribio, angalia tarehe za mwisho za EUDI Wallet kwa 2026 na 2027.

Jinsi Didit inavyosaidia katika uthibitishaji wa EUDI Wallet

Ukubali wa EUDI Wallet unakuja hivi karibuni kwenye Didit: uko kwenye mpango wetu wa maendeleo, unaoendana na ratiba ya EUDI Wallet, katika mtiririko uleule unaotumia leo. Wakati huo huo, unaweza kuthibitisha watu kwa mbali sasa.

• eID tano za kitaifa zinafanya kazi kwenye Didit leo kupitia pochi za utambulisho wa kidijitali: MitID, BankID Sweden, Finnish Trust Network, Smart-ID na Mobile-ID. Angalia uthibitishaji wa eID.
• Ikiwa mtu hana eID, mtiririko unarudi kwenye uthibitishaji wa nyaraka pamoja na usomaji wa chipu ya NFC, ukaguzi wa uhai na ulinganishaji wa uso, vilivyowekwa kwa kila nchi. Ukaguzi kamili wa KYC unagharimu $0.33.
• Uchunguzi wa AML unaendeshwa katika mtiririko uleule kwa $0.20.

Unabaki na majukumu yako ya mhusika anayetegemea (relying party). Nyaraka za pochi zinaonyesha jinsi eID zinavyowashwa kwa kila nchi.

Maswali yanayoulizwa mara kwa mara

Vyanzo

1. OpenID for Verifiable Presentations 1.0, OpenID Foundation, Vipimo vya Mwisho.
2. Vipimo vya Mwisho vya OpenID for Verifiable Presentations 1.0 Vimeidhinishwa, OpenID Foundation, 10 Julai 2025.
3. Architecture and Reference Framework v3.0.0, eu-digital-identity-wallet kwenye GitHub, toleo la tarehe 23 Julai 2026.
4. Kanuni (EU) 2024/1183 (eIDAS 2), EUR-Lex, Gazeti Rasmi la tarehe 30 Aprili 2024.
5. Kanuni ya Utekelezaji ya Tume (EU) 2026/1731, EUR-Lex, Gazeti Rasmi la tarehe 22 Julai 2026.
6. Kanuni ya Utekelezaji ya Tume (EU) 2025/848 kuhusu usajili wa wahusika wanaotegemea pochi, EUR-Lex, Gazeti Rasmi la tarehe 7 Mei 2025.
7. Kanuni ya Utekelezaji ya Tume (EU) 2024/2977 kuhusu data ya utambulisho wa mtu, EUR-Lex, Gazeti Rasmi la tarehe 4 Desemba 2024.
8. ISO/IEC 18013-7, ukurasa wa kiwango cha ISO.
9. Digital Credentials, rasimu ya W3C.
10. Digital Credentials API imezinduliwa, Chrome for Developers.
11. Mwongozo wa wasanidi wa EVO Wallet, Serikali ya Moldova, egov4dev.
12. Maswali yanayoulizwa mara kwa mara kuhusu pochi ya EUDI, eudi-wallet.gov.de.
13. Mthibitishaji wa majaribio wa BNM, Serikali ya Moldova, egov4dev.

OpenID4VP ni sehemu ya pochi ya EUDI ambayo wasanidi huitumia zaidi, na ni thabiti vya kutosha kujenga juu yake. Angalia jinsi Didit inavyoshughulikia ukubali wa pochi kwenye ukurasa wa suluhisho la pochi ya EUDI, na picha pana katika muhtasari wetu wa eIDAS 2.