Mwongozo wa kuunganisha eID API: mifumo, msimbo na usalama

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

Mwongozo huu unaoanza na msimbo ni kwa wahandisi wanaoongeza eID za kitaifa kwenye mchakato wa kumsajili mteja.

Jinsi API ya eID inavyofanya kazi: mifumo mitano ya mwingiliano

Mfumo wako ndio mhusika anayetegemea (relying party, RP). Hauoni kamwe kitambulisho chenyewe, bali jibu lililotiwa saini kuhusu mtu huyo tu.

Baadhi ya mifumo iko nyuma ya lango la umma. TARA ya Estonia ni lango la msimbo wa uidhinishaji lililo mbele ya kitambulisho, Smart-ID, Mobile-ID na eID za EU.^[7] Angalia mifumo ya eID kwa nchi ili kujua kila mfumo unatumia mtindo upi.

Unachojenga wewe na kile mtoa huduma anashughulikia

Ufikiaji unatangulia msimbo. Nchini Denmark kila mtoa huduma lazima apitie dalali wa MitID aliyeidhinishwa.^[12] Nchini Sweden unanunua BankID kutoka benki au muuzaji na unaagiza cheti cha mhusika anayetegemea.^[15] Nchini Ujerumani unaendesha seva yako mwenyewe ya eID, unatumia huduma ya eID inayopangishwa ukiwa na cheti chako mwenyewe, au unatumia huduma ya utambulisho bila kushikilia cheti wewe mwenyewe.^[13] Kwa Pochi ya EUDI, mhusika anayetegemea lazima ajisajili katika Nchi Mwanachama ambako ana makao yake.^[1]

Madalali walioidhinishwa wapo kwa mifumo mingi ya nchi za Nordiki na Baltiki. Unganisha moja kwa moja kwa mfumo mmoja wenye idadi kubwa ya watumiaji; tumia API moja watumiaji wanapotoka nchi kadhaa.

Mtiririko wa uelekezaji upya, hatua kwa hatua

Huu ni mtiririko wa msimbo wa uidhinishaji wa OIDC. Backend yako inatuma kivinjari nje pamoja na state na nonce nasibu, kisha inabadilisha msimbo uliorudishwa kwa tokeni ya ID na kuikagua.

Kuingia kwa uelekezaji upya. Madalali na malango huongeza vituo vya kupitia katika hatua ya 2, si hatua mpya kwako.

Ukaguzi baada ya hatua ya 5 ndio muhimu zaidi. Kwa mujibu wa nyaraka za ID-porten za Digdir, mteja "LAZIMA athibitishe kwamba kiwango cha usalama (acr) kiko juu vya kutosha".^[5] Soma acr kama kiwango cha uhakika (LoA) ambacho mpango unadai, na kataa chochote kilicho chini ya sera yako.

Mtiririko wa arifa ya programu pamoja na msimbo wa ulinganisho

Smart-ID na Mobile-ID hazimtoi mtumiaji kwenye ukurasa wako. Mtumiaji anaandika msimbo wa utambulisho binafsi (Mobile-ID pia huomba namba ya simu), ukurasa wako unaonyesha msimbo mfupi, na msimbo huo huo unaonekana kwenye programu. Mtumiaji anaidhinisha kwa PIN kwenye simu pale tu misimbo inapolingana.^[20] Smart-ID pia inaweza kuonyesha misimbo mitatu na kumwomba mtumiaji achague ulio sahihi.^[10]

BankID Sweden ina muundo uleule, lakini kwa QR badala ya msimbo unaoandikwa. Mtumiaji hufungua programu kwenye kifaa kilekile kwa tokeni ya autostart, au huchanganua QR inayobadilika inayoonyeshwa kwenye kifaa kingine. Backend yako huuliza /collect mara kwa mara hadi agizo likamilike. Agizo lililokamilika lina nambari ya kibinafsi, jina, jina la kwanza na jina la ukoo, pamoja na sehemu za kifaa, sahihi na sehemu za hiari za hatari.^[8] Smart-ID+ inahamisha Smart-ID kwenye muundo huu (QR inayobadilika kwenye kompyuta ya mezani, programu kwa programu kwenye simu), hivyo watumiaji hawaandiki tena msimbo wa kibinafsi kwenye tovuti.^[11]

Kuingia kwa Smart-ID au Mobile-ID, kwa mpangilio ambao mtumiaji anauona: msimbo wa kibinafsi, msimbo wa kulinganisha kwenye ukurasa wako, msimbo uleule kwenye programu, kisha PIN.^[20] Katika toleo la QR la BankID, hatua ya 1 inaondoka na hatua ya 2 inaonyesha msimbo wa QR.

Kadi na NFC, na Pochi ya EUDI kupitia OpenID4VP

Kwa kadi ya eID ya Ujerumani, mtumiaji huishikilia kadi kwenye simu yenye NFC ndani ya AusweisApp. Kabla PIN haijaandikwa, sheria inaitaka programu ionyeshe jina la mtoa huduma, anwani yake na aina za data zinazoombwa. Aina hizo pekee ndizo hutumwa.^[14]

Kwa mujibu wa OpenID Foundation, OpenID4VP 1.0 ni vipimo vya mwisho.^[16] Architecture and Reference Framework (ARF) inaorodhesha uwasilishaji wa mbali kama OpenID4VP kupitia uelekezaji upya na mipango maalum ya URI kama openid4vp://, OpenID4VP kupitia W3C Digital Credentials API, au ISO/IEC 18013-7 kupitia API hiyo.^[2][17] Kabla ya kushiriki chochote, pochi huthibitisha cheti chako cha ufikiaji, hukagua kwamba huombi sifa zaidi ya zile ulizosajili, na humruhusu mtumiaji kuidhinisha kila sifa.^[2] Ni kuanzia tarehe 11 Agosti 2028 tu ndipo picha ya uso inakuwa ya lazima katika data ya utambulisho wa mtu (PID), isipokuwa pale mtumiaji anapochagua waziwazi kutoitoa.^[18]

1. 23 Julai 2026ARF v3.0.0Toleo la sasa la mfumo wa pochi.
2. 24 Desemba 2026Pochi zinatakiwaKila Nchi Mwanachama inatoa angalau pochi moja.
3. 24 Desemba 2027KukubaliwaWahusika wategemezi wa sekta binafsi wanaotakiwa na sheria au mkataba kutumia uthibitishaji imara wa mtumiaji wanaikubali pochi kwa ombi la mtumiaji. Biashara ndogo sana na biashara ndogo zimesamehewa.
4. 11 Agosti 2028Picha ya usoPicha ya uso katika PID inakuwa ya lazima isipokuwa mtumiaji akichagua kutoitoa.

Tarehe za Pochi ya EUDI zinazounda ramani ya maendeleo ya API ya eID.^[1][2][18]

Mwongozo wa Pochi ya EUDI unashughulikia usajili wa wahusika wanaotegemea na utayari kwa kila nchi.

Hitilafu, njia mbadala na majaribio ya marudio

Kuingia huishia katika hali ya kukamilika, kughairiwa, kuisha kwa muda au kushindwa. Shughulikia hali tatu za mwisho kwa namna moja, na uamue kwa kila nchi kinachofuata.

Usirudie kamwe kiotomatiki kuingia kulikoghairiwa. Fanya callback iwe idempotent, ili kuonyesha upya ukurasa au tukio lililorudiwa kusiweze kufungua akaunti mbili. Weka njia kwa watu wasio na eID, kwa kawaida hati ya utambulisho yenye usomaji wa chipu kwa NFC, ukaguzi wa uhai na ulinganisho wa uso. Uthibitishaji wa eID kwa NFC na usalama wa chipu unaeleza njia hiyo.

Orodha ya ukaguzi wa usalama kwa muunganisho wa API ya eID

• Tengeneza state na nonce mpya kwa kila kuingia na ukatae callback isiyolingana nazo.
• Thibitisha saini ya kila tokeni au matokeo kabla ya kusoma sifa yoyote.
• Kagua kiwango cha uhakika kwenye matokeo, si kwenye ombi pekee.^[5]
• Taka kiwango cha kutosha (substantial) au cha juu (high) pale njia ya eID ya AMLR inapokuhusu.^[3]
• Usikusanye kamwe PIN ya eID kwenye ukurasa wako; inamilikiwa na programu ya mfumo husika.^[20]
• Pendelea QR au uzinduzi wa programu hadi programu badala ya misimbo inayoandikwa kwa kuingia kati ya vifaa tofauti.^[11]
• Omba sifa ulizosajili na unazohitaji pekee.^[1]
• Thibitisha saini na mihuri ya muda ya webhook kabla ya kuamini matokeo.

Msingi wa kisheria ni Kanuni ya Kupambana na Utakatishaji Fedha (AMLR), inayotumika kuanzia 10 Julai 2027: Kifungu 22(6)(b) kinaruhusu "njia za utambulisho wa kielektroniki zinazokidhi matakwa ya Kanuni (EU) Na. 910/2014 kuhusu viwango vya uhakika 'cha kutosha' (substantial) au 'cha juu' (high)".^[3] Si kila mfumo umearifiwa: MitID iko kwenye orodha ya EU ya mifumo iliyoarifiwa, Smart-ID haiko.^[4]

Jinsi Didit inavyosaidia katika muunganisho wa API ya eID

Didit inaweka eID tano zinazofanya kazi nyuma ya API moja ya kipindi (MitID, BankID Sweden, Finnish Trust Network, Smart-ID na Mobile-ID, katika nchi saba), pamoja na njia ya hati ndani ya mtiririko huo huo. Mifumo zaidi iko kwenye mpango wa maendeleo wa Didit, na kukubali Pochi ya EUDI (EUDI Wallet) kunakuja hivi karibuni. Didit haiombi PIN kamwe. Maelezo zaidi yako kwenye ukurasa wa pochi za kidijitali za utambulisho na kwenye nyaraka za pochi.^[19]

Washa eID zinazofanya kazi kwa kila nchi

Kwenye konsoli: Workflows, hatua ya ID Verification, Countries, "Wallets accepted". Kupitia API, kipengele cha ID Verification (OCR) kinapokea kitu cha methods chenye funguo za msimbo wa nchi wa ISO 3166-1 alpha-3, kinachotumwa pamoja na POST /v3/workflows/. Kipande kilichoandikwa kwenye nyaraka kwa Denmark:^[21]

{ "feature": "OCR", "config": { "methods": { "DNK": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" } } } } }

Na kwa Estonia, ukikubali eID zote mbili zinazotumia simu:^[20]

{ "EST": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["smart_id", "mobile_id"], "on_failure": "fallback_to_document" } } }

providers ni orodha ya zinazokubaliwa, si mpangilio wa vipaumbele. on_failure ni fallback_to_document au decline. Pochi isiyopatikana katika mazingira yako inakataa uhifadhi wote, kwa hiyo soma katalogi kwanza.^[21]

Unda kipindi na usome matokeo

POST /v3/session/ pamoja na workflow_id yako (na, ukipenda, vendor_data na callback) hurejesha session_id, url na session_token. Fungua URL au tumia SDK.^[24] Matokeo hufika kupitia webhook au GET /v3/session/{id}/decision/, yakiwa na verification_method: "wallet", assurance: "cryptographic" na kitu cha wallet_verification.^[19]

Kiwango kilicho chini ya kile kilichoombwa husababisha kuingia kushindwa. Ni kuingia kulikokamilika tu ndiko hutozwa ada.^[19] Bei: MitID, Finnish Trust Network $0.25; BankID Sweden, Smart-ID, Mobile-ID $0.20.

Webhook na sandbox

Thibitisha X-Signature-V2 kwa kutumia siri ya anwani yako ya kupokea, kataa X-Timestamp iliyopita zaidi ya sekunde 300, na weka idempotency kwa kutumia event_id. Uwasilishaji ulioshindwa hujaribiwa tena hadi mara mbili.^[22] Programu ya sandbox inaweza kuwezesha kila pochi, huidhinisha bila uingiaji halisi, na hutoa wallet_cancelled, wallet_timeout na wallet_provider_error ili kujaribu njia yako mbadala.^[23]

Maswali yanayoulizwa mara kwa mara

Vyanzo

1. Kanuni (EU) 2024/1183 (eIDAS 2), EUR-Lex, Gazeti Rasmi la tarehe 30 Aprili 2024, Vifungu 5a, 5b na 5f.
2. Architecture and Reference Framework v3.0.0, mradi wa EUDI Wallet wa Tume ya Ulaya, ulitolewa tarehe 23 Julai 2026, sehemu 4.4.3, 5.7.1 na 6.6.3.
3. Kanuni (EU) 2024/1624 (AMLR), EUR-Lex, Kifungu 22(6).
4. Overview of pre-notified and notified eID schemes under eIDAS, Tume ya Ulaya, ilisomwa tarehe 5 Oktoba 2026.
5. ID-porten ID token, Wakala wa Kidijitali wa Norway (Digdir).
6. Anbindung mit OpenID Connect, nyaraka za wasanidi za ID Austria.
7. TARA technical specification, Mamlaka ya Mifumo ya Habari ya Estonia (RIA).
8. Auth and sign: collect, nyaraka za wasanidi za BankID.
9. QR-koden gjorde susen: BankID-bedrägerierna ned med 90 procent, Computer Sweden, 3 Julai 2019 (chanzo cha pili).
10. Why do I sometimes see one confirmation code and sometimes three, Smart-ID.
11. How does the new Smart-ID protect me from fraud, Smart-ID.
12. MitID brokers, Wakala wa Serikali ya Kidijitali wa Denmark.
13. Become a service provider, AusweisApp, serikali ya shirikisho ya Ujerumani.
14. Kifungu cha 18 cha Sheria ya Pasipoti na Kadi ya Kitambulisho (PAuswG), Gesetze im Internet.
15. Connect your business to BankID, BankID.
16. OpenID for Verifiable Presentations 1.0 final specification approved, OpenID Foundation.
17. Digital Credentials, W3C.
18. Kanuni ya Utekelezaji ya Tume (EU) 2026/1731, EUR-Lex, picha ya uso katika PID kuanzia tarehe 11 Agosti 2028.
19. Pochi za vitambulisho vya kidijitali, nyaraka za Didit.
20. Muunganisho wa Smart-ID na Mobile-ID, nyaraka za Didit.
21. Mipangilio ya vipengele vya mtiririko wa kazi, nyaraka za Didit.
22. Webhooks, nyaraka za Didit.
23. Sandbox na data ya majaribio, nyaraka za Didit.
24. Kuanza haraka, nyaraka za Didit.

Tazama kila eID ya kitaifa, kiwango chake na hali yake kwenye ukurasa wa uthibitishaji wa eID.