AJAX põhine ID kaardi ja Mobiil-ID autentimine/allkirjastamine. Kui sk.ee lehel olevad näited on terviklahendused, siis see projekt üritab kõik tegevused lammutada eraldi AJAX põhisteks käsklusteks. Nii on autentimist ja allkirjastamist mugav lisada suvalistele veebiaplikatsioonidele. Zone III paketis ning Veebimajutus.ee Standard+ paketis peaks teek töötama ilma eriliselt seadistamata.
Kopeeri ID-AJAX oma HTTPS serveri juurkataloogi
cd /path/to/htdocs
git clone https://github.com/andris9/ID-AJAX.git
või lae alla ZIP arhiiv ja paki lahti.
Muuda saidi juurkataloogis .htaccess
faili, lisades reeglid URL'ide ümberkirjutamiseks - edaspidi hakkavad kõik päringud ID-AJAX mooduli pihta olema aadressidel /auth/tegevuseNimi.
RewriteEngine On
RewriteBase /
RewriteRule ^auth/cardAuthRequest$ ID-AJAX/IDCardAuth/cardauth.php?action=cardAuthRequest&%{QUERY_STRING} [NC]
RewriteRule ^auth/(.*)$ ID-AJAX/auth.php?action=$1&%{QUERY_STRING} [NC]
ID kaardi tugi peab olema serveris olemas. See on automaatselt olemas näiteks Zone III paketis ja Veebimajutus.ee Standard+ paketis - nende pakettide puhul midagi täiendavalt ise ID kaardi töölepanekuks tegema ei pea.
Ava aadress https://sinuserver.com/ID-AJAX/test/
ning proovi järgi, kas asi töötab.
- Algselt autenditakse mitte live-, vaid testserveri pihta (vaata faili ID-AJAX/conf.php)
- **NB!**Testserveri kasutamiseks tuleb eelnevalt oma Mobiil või ID kaardi sertifikaadid seal registreerida - seda saab teha aadressil openxades.org
- Teenuse sertide asukoht on ID-AJAX/lib/service_certs.pem
- DigiDoc teek puhverdab WSDL klassi faili ID-AJAX/wsdl.class.php - juhul kui conf.php faili muudetakse, tuleb see WSDL ära kustutada
- Allkirjastatavate failidega majandab klass
FileStore
(ID-AJAX/filestore.php), mis vaikimisi salvestab kõigi failide andmed kausta /ID-AJAX/tmpfiles. Juhul kui tekib soov need failid kuhugi mujale paigutada (MySQL vms), siis võib FileStore klassi üle kirjutada, oluline on vaid jätta selle klassi API samaks, sisu võib aga suvaline olla.
Hetkel live demo puudub
Ma ei suutnud tuvastada kas sk.ee poolt pakutavatel teekidel on mingi litsents või mitte. Igatahes kataloogis ID-AJAX/static/ olevad .JAR failid ning osaliselt IDCardModule.js, samuti ka ID-AJAX/lib/include kataloogis olevad failid on (c) sk.ee, kõik muu on BSD.
Kõige parem on vaadata, kuidas töötab ID-AJAX/test/index.html. Kasutatud JavaScript sõltub Prototype teegist. /ID-AJAX/static/IDCardModule.js on vajalik ID kaardiga allkirjastamiseks, /ID-AJAX/static/AUTH.js sisaldab tegevusi Mobiil-ID'ga autentimiseks ja allkirjastamiseks ning ID kaardiga autentimiseks. auth_sign.js on näiteskript autentimise ja allkirjastamise läbiviimiseks.
Näiterakendus teeb loob iga allkirjastamise jaoks uue faili, aga kui viide faili juurde (fid väärtus) on olemas, saab sama faili ka korduvalt allkirjastada. Mõistlik oleks võibolla auth/addFile meetod üldse välja lülitada ja tekitada allkirjastatavad failid mingil muul moel, kui et kasutaja need ise üles laeb.
Allkirjastamise jaoks peab lehel olema DOM element, mille id väärtuseks on pluginLocation. Skriptis auth_sign.js lisab selle lehele automaatselt funktsioon init_card_plugin() seega ei pea element olema HTML'i vägisi sisse kirjutatud.
Kogu sessiooniga seotud info on PHP poolel hallatud standardse PHP sessiooniga, seega on vajalik skritpi alguses sessioon alati käima panna käsuga session_start()
.
Sessiooni muutujates on kirjas autenditud kasutaja andmed (nimi, isikukood, kas autenditi id kaardi või mobiiliga jne) ning allkirjastamise protsessi ajal ka sellega seotud andmed.
Kõikide AJAX päringute puhul on vea korral (v.a. ID kaardiga autentimine, kui vastust üldse pole ning response.status==0
) on vastus JSON järgmise struktuuriga
- status: "ERROR"
- message: "Vea kirjeldus"
- code: "vea_kood"
JSON:
{
"status": "ERROR",
"message": "Authentication failed!",
"code": "SESSION_TIMEOUT"
}
ID kaardiga autentimisel on suurem töö jäetud serveri haldaja peale. Näiteks Zone ja Veebimajutus HTTPS toega pakettides on ID kaardi tugi juba "sisse ehitatud," seega erlist keerukust ei teki.
Autentimiseks tuleb teha AJAX päring aadressile /auth/cardAuthRequest
(lisaparameetreid pole). Vastuseks on JSON struktuur kasutaja andmetega või viga. Peamiseks vea
tekkimise allikaks on ID kaardiga seotud pool (kaart pole sisestatud, kasutaja katkestab, ID kaardi tuge pole kasutaja arvutis olemaski jne) - kõikidel nendel juhtudel lõpetab
AJAX päring töö staatusega 0.
Serveri poolel käivitatakse skript asukohaga /ID-AJAX/IDCardAuth/cardauth.php
millega samas kataloogis olevas .htaccess failis on määratud ID kaardi tuvastamise vajadus ning määrang, et ID kaardiga seotud info edastatakse skriptidele keskkonnamuutujates.
PHP skript kutsub välja Auth::CardAuthRequest();
funktsiooni, mis kasutaja andmed keskkonnamuutujatest välja loeb ja sessiooni väärtusena salvestab.
JSON struktuur on järgmine
- status: "AUTHENTICATED"
- data:
- UserIDCode: "isikukood"
- UserGivenname: "eesnimi"
- UserSurname: "perekonnanimi"
- UserCountry: "2 kohaline maa nimetus (EE)"
JSON:
{
"status": "AUTHENTICATED",
"data":{
"UserIDCode": "3901212544",
"UserGivenname": "Mati",
"UserSurname": "Maasikas",
"UserCountry": "EE"
}
}
Mobiil-ID autentimine koosneb kahest eri etapist:
- Autentimise algatamine, tehes päringu aadressile `/auth/mobileAuthRequest'
- Perioodiline autentimise kulgemise kontroll aadressil
/auth/mobileAuthStatus
Autentimise algatmisel on kohustuslikuks parameetriks phone
telefoninumbriga, täiendavalt saab edastada veel parameetri message
mis tähistab kuni 40 tähemärgi pikkust kasutaja mobiiliekraanile kuvatavat teadet.
Autentimise algatamise tagastuseks on JSON struktuur selle õnnestumise kohta. Probleemseteks punktideks on olukorrad kus telefoni number ei ole Mobiil-ID'ga seotud, on levist väljas või on mõni muu tehniline rike. Eduka päringu sooritamise korral on vastus järgmine:
- status: "OK"
- sid: numbriline sessiooni võti
- code: "kontrollkood kasutajale kuvamiseks"
JSON:
{
"status": "OK",
"sid": 128463527,
"code": "5612"
}
Kui autentimine on algatatud, tuleb järgmisena alustada perioodilist kontrolli selle kulgemise kohta. Kontrollimisel on kohustuslikuks (ja ainsaks) parameetriks sid
autentimise sessiooni võtmega.
- Kui autentimine lõpeb veaga (kasutaja vajutas "cancel", aeg sai otsa vms), on tagastusväärtuseks tavaline veateavitus.
- Kui autentimine veel kestab (kasutaja pole koodi sisestanud ega katkestanud), on JSON struktuur järgmine
- status: "WAITING"
- Kui autentimine õnnestus, on tulemus sama nagu ID kaardiga autentimise korral.
Kui vastuses on status väärtuseks "WAITING" tuleb kontrolli mõne aja pärast korrata.
Allkirjastamiseks on vaja kõigepealt mõnda faili, mida allkirjastada. Failidega majandamiseks on klass FileStore
mis asub failis filestore.php.
Mobiil-ID ja ID kaardiga allkirjastamise suurem vahe on faktis, et kui ID kaardi puhul allkirijastatakse faili, siis Mobiil-ID puhul allkirjastatakse XML elemendi räsi. ID kaardiga tuleb saata fail Sertifitseerimiskeskuse serverile, lisada ID kaardilt saadud allkirja räsi ja vastu saadakse DDOC fail, mis sisaldab nii algset dokumenti kui ka allkirja kinnitust. Mobiil ID puhul tuleb Sertifitseerimiskeskuse serverile saata räsi üle faili XML kirje loodavas DDOC failis ning vastu saadakse XML kujul allkirja kinnitus mis tuleb ise DDOC faili juurde lisada.
Näitena saab tekitada allkirjastamiseks uue faili käsuga /auth/addFile
, mille parameetritena tuleb edastada järgmised andmed
- filename - faili nimi
- contents - faili sisu
Vastuseks saadab server loodud faili identifikaatori fid
, mida saab kasutada allkirjastamise jaoks.
- status: "OK"
- fid: "faili identifikaator (42 baiti)"
JSON:
{
"status": "OK",
"fid": "1299265325ccb62cd5613213d46fdb8c39f288b0d0"
}
Kui faili identifikaator on olemas, saab seda faili allkirjastada. Sama identifikaatorit kasutades saab lisada ühele failile mitu erinevat allkirja ja seda nii ID kaardi kui ka mobiiliga.
Mõistlik oleks failide lisamine organiseerida siiski kuidagi teisit, mitte lasta neid kasutajatel vabalt üles laadida.
Faili lisamise leiab failist /ID-AJAX/auth.php funktsioonis URLHandlers::addFileHandler
.
ID kaardiga allkirjastamiseks peab lehel olema laetud JavaScripti fail /ID-AJAX/static/IDCardModule.js ning peale lehe laadimist
tuleb lisada allkirjastamiseks vajalik plugin. Demolehel teeb seda funktsioon init_card_plugin()
.
Kui plugin on lehel olemas, tuleb esiteks laadida ID kaardilt sertifikaadi andmed, saata need serverile (/auth/cardPrepareSignature
)
ja seejärel saadud andmetega viia allkirjastamine läbi. Kui allkirja andmed on olemas, saab need
saata serverile (/auth/cardFinalizeSignature
) kinnitamiseks. Protsessi saab mugavalt läbi viia JavaScript funktsiooniga
AUTH.preparesignatureRequest(fid, callback)
kus fid
on allkirjastatava faili identifikaator ja callback
on
tagasikutsefunktsioon, mis saab parameetriks väärtused error
ja data
. Esimene parameeter on seatud, kui protsessis ilmnes viga
ja teine kui kõik õnnestus.
Mobiil-ID abil allkirjastamine sarnaneb autentimisega. Esiteks tuleb algatada signeerimisprotseduur (/auth/mobileSignRequest
)
ja seejärel perioodiliselt kontrollida allkirjastamise kulgu (/auth/mobileSignStatus
).
Allkirjastatud failid saab alla laadia aadressilt /auth/getDDOC?fid={fid}
kus {fid} on allalaetava faili identifikaator
Kõikide siin kirjeldatud toimingute läbiviimist saab uurida testrakendusest.