Tehniline kirjeldus

v 1.27, 25.04.2024

• 1 Ülevaade
  • 1.1 OpenID Connect
  • 1.2 Siseriiklik ja piiriülene autentimine
• 2 Autentimisprotsess kasutaja vaatest
• 3 Autentimisvoog tehnilises vaates
• 4 Päringud
  • 4.1 Autentimispäring
    • 4.1.1 Atribuutide küsimine välismaalase kohta
    • 4.1.2 E-posti aadressi küsimine
    • 4.1.3 Mobiilinumbri küsimine
    • 4.1.4 Autentimismeetodite valikuline kasutus
  • 4.2 Tagasisuunamispäring
  • 4.3 Identsustõendipäring
    • 4.3.1 Identsustõend
  • 4.4 Kasutajainfopäring
• 5 Turvatoimingud
  • 5.1 Identsustõendi kontrollimine
    • 5.1.1 Allkirja kontrollimine
    • 5.1.2 Otspunktide TLS ühenduse kontrollimine
    • 5.1.3 Tõendi väljaandja kontrollimine
    • 5.1.4 Tõendi adressaadi kontrollimine
    • 5.1.5 Tõendi ajalise kehtivuse kontrollimine
    • 5.1.6 Autentimismeetodi kontrollimine
    • 5.1.7 Minimaalse lubatud eIDAS autentimistaseme kontrollimine
    • 5.1.8 Seansi loomine
  • 5.2 Võltspäringuründe vastane kaitse
  • 5.3 Logimine
  • 5.4 Identsustõendi allkirjastamise võtme vahetus
• 6 Otspunktid ja aegumisajad
• 7 Soovitusi liidestajale
• 8 eIDAS autentimistasemed
• 9 Erasektori asutuse erisused
• Muutelugu

1 Ülevaade

Käesolev dokument määratleb autentimisteenuse TARA tehnilised omadused ja annab soovitusi klientrakenduse e-teenusega liidestamiseks.

Autentimisteenus TARA on Riigi Infosüsteemi Ameti poolt pakutav teenus, millega asutus saab oma e-teenusesse lisada erinevate autentimismeetodite toe:

• ID-kaart
• Mobiil-ID
• Smart-ID
• EU eID (piiriülene autentimine läbi eIDAS taristu)

Tehniline kirjeldus on suunatud TARA liidestajatele (arendajatele). Lugejalt eeldame HTTP protokolli tundmist. Kasulik, kuid mitte vajalik on OpenID Connect või OAuth 2.0 kogemus. Lugeja peab olema valmis vajadusel hankima lisateavet OpenID Connect protokolli originaaltekstist [Core].

Kui leiate vea või soovite midagi küsida, siis palun pöörduge meie kasutajatoe poole: help@ria.ee.

Tehnilises kirjelduses on püütud järgida ühtset terminoloogiat. Sõnaseletusi leiab sonastikust ja viidatud materjalides. Arvestama peab, et OpenID Connect, OAuth 2.0 jm mõistesüsteemid ei ole ideaalselt ühtlustatud. Näiteks, TARAga liidestuvat, e-teenust pakkuvat asutuse infosüsteemi nimetame siin “klientrakenduseks”. OAuth ja mõneski muus kontekstis on klientrakendus aga “teenusepakkuja” (service provider).

1.1 OpenID Connect

Autentimisteenus TARA põhineb OpenID Connect protokollil (Viited, [Core]), mis omakorda tugineb OAuth 2.0 protokollile. OpenID Connect ja OAuth 2.0 on ulatuslikud, paljude võimalustega standardid.

TARA-s on nimetatud protokollidest valitud piiritletud alamhulk ning tehtud mõned kohandused. Peamised valikud ja kohandused OpenID Connect täisprotokolliga võrreldes on järgmised:

• Teenus toetab volituskoodi voogu(authorization code flow). Volituskoodi voogu peetakse kõige turvalisemaks ja sellisena on avalike teenuste jaoks sobiv.
• Kogu teave autenditud kasutaja kohta edastatakse rakendusele identsustõendis (ID token).
• Rakendusele edastatakse ka eIDAS autentimistase, kui see on teada (acr väites).
• Teenus toetab kasutajaliidese keele-eelistuse andmist autentimispäringus (parameetriga ui_locales).
• Autentimismeetodi valib kasutaja autentimisteenuses või liidestunud infosüsteem (parameetri scope abil).
• Piiriülene autentimine, vastavalt eIDAS tehnilisele spetsifikatsioonile.
• Klientrakenduse dünaamilist registreerimist ei toetata. Klientrakenduse registreerimine toimub RIA-s eraldi protseduuriga.
• Ühekordset sisselogimist (SSO) ja seansihaldust (session management) ei toetata. Ühekordse sisselogimise teenuse jaoks kasutada Riigi SSO teenust (GovSSO) mille dokumentatsioon on leitav siit.

Sõltuvalt kasutajate tagasisidest võib TARA funktsionaalsus laieneda.

1.2 Siseriiklik ja piiriülene autentimine

TARA võimaldab nii siseriiklikku kui ka piiriülest autentimist. See tähendab, et autentida saab nii Eesti e-identimissüsteemi (ID-kaardi, Mobiil-ID jms kasutaja) kui ka EL teise liikmesriigi e-identimissüsteemi kasutaja.

eIDASe kontekstis teostab TARA kasutusvood “Eestlase autentimine Eesti e-teenuses” ja “Eesti e-teenust kasutava välismaalase autentimine” (joonis 1). Sh on võimalik välismaalase autentimist Eesti e-teenuse jaoks kasutada nii, et TARA kasutajaliidest kasutajale ei kuvata vaid kasutaja suunatakse otse välisriigi autentimisteenusesse (loe automaatse suunamise kohta p4.1.4)

Joonis 1. Siseriiklik ja piiriülene autentimine

2 Autentimisprotsess kasutaja vaatest

1 Kasutaja on e-teenust osutavas klientrakenduses.

• kasutaja võib olla nii eestlane kui ka välismaalane
• kasutajale esitatakse kuva, millel on nupp “Logi sisse” vms
• kasutaja vajutab “Logi sisse”.

2 Klientrakendus suunab kasutaja TARA-teenusesse (sirviku ümbersuunamiskorralduse abil)

• ümbersuunamis-URL-is on autentimispäring.

3 Kasutajale avaneb autentimismeetodi valiku kuva. Siin võib kasutaja:

• valida ID-kaardiga autentimise (samm 4)
• valida Mobiil-ID-ga autentimise (samm 5)
• valida Smart-ID-ga autentimise (samm 6)
• valida EU eID-ga autentimise (piiriülese autentimise) (samm 7)
• pöörduda tagasi klientrakendusse.

4 ID-kaardiga autentimine

• algab kasutajale teabe kuvamisega autentimissertifikaadi kohta (vajalik võib olla sertifikaadi valik kasutaja poolt)
• kasutaja sisestab PIN1-koodi
• eduka autentimise korral edasi samm 8, vea korral samm 9.

5 Mobiil-ID-ga autentimine

• kasutaja sisestab mobiilinumbri ja isikukoodi
• kasutaja mobiilseadmele kuvatakse kontrollkood
• kinnituse ootamine
• eduka autentimise korral edasi samm 8, vea korral samm 9.

6 Smart-ID-ga autentimine

• kasutaja sisestab Eesti isikukoodi
• kasutaja mobiilseadmele kuvatakse kontrollkood
• kinnituse ootamine
• eduka autentimise korral edasi samm 8, vea korral samm 9.

7 EU eID-ga (piiriülene) autentimine

• kasutaja valib sihtriigi
• kasutaja suunatakse läbi eIDAS taristu välisriigi autentimisteenusesse
• kasutaja autendib end välisriigi autentimisvahendiga
• eduka autentimise korral (ning kui välisriigi autentimisvahendi tase on piisav) edasi samm 8
• vea korral samm 9.

NB! EU eID autentimise korral on võimalik sihtriigi valik teha ka otse TARA-ga liidestunud infosüsteemis ning saata soovitud riigi kood autentimispäringuga. Sellisel juhul kasutajale TARA kasutajaliidest ei kuvata ja tehakse automaatne edasisuunamine läbi eIDAS taristu otse välisriigi autentimisteenusesse, kus kasutaja autendib end välisriigi autentimisvahendiga. Eduka autentimise korral (ning kui välisriigi autentimisvahendi tase on piisav) edasi samm 8

8 Autenditud kasutaja

• suunatakse tagasi klientrakendusse
• klientrakendus pärib TARA serverilt identsustõendi
• identsustõend (identity token) on allkirjastatud tõend eduka autentimise kohta
• identsustõendis sisalduvad autentimisel tuvastatud kasutaja andmed (atribuudid)
• klientrakendus annab kasutajale asjakohasel viisil teada, et sisselogimine õnnestus.

9 Veateate lehelt

• saab kasutaja minna tagasi autentimismeetodi valikusse
• ja seal kas üritada uuesti, võimalik, et teise autentimismeetodiga
• või katkestada autentimise ja minna tagasi klientrakendusse.

10 Lisaks on kasutajal võimalik:

• saada täiendavat teavet TARA-teenuse kohta.

3 Autentimisvoog tehnilises vaates

Kirjeldame detailselt suhtluse sirviku, klientrakenduse serverikomponendi ja TARA serverikomponendi vahel.

Need kolm osapoolt suhtlevad HTTP päringute ja vastuste abil.

Käime läbi peamised päringud ja nende vastused (joonis 2).

Joonis 2. Autentimispäring

Voog algab sirvikust. Klientrakendusest on sirvikusse laetud leht, millel kasutaja saab vajutada “Logi sisse” või alustada autentimist muul viisil.

Kasutaja nupuvajutuse tulemusena saadab sirvik klientrakendusele (täpsemalt klientrakenduse serverikomponendile) HTTP päringu 1a. Klientrakendus võib autentimist alustada ka ise, kasutaja muu toimingu peale.

Klientrakendus koostab autentimispäringu. Autentimispäringu koosseis on kirjeldatud eraldi jaotises allpool. Klientrakendus saadab sirvikusse päringuvastuse 1b. Päringuvastus sisaldab HTTP ümbersuunamiskorraldust (redirect) ja autentimispäringut.

Sirvik täidab ümbersuunamiskorralduse. See toimub nii, et sirvik võtab päringuvastusest 1b autentimispäringu ja saadab selle TARA serverikomponendile, päringuna 2a.

TARA serverikomponent, saades autentimispäringu 2a, koostab autentimismeetodi valiku lehe ja saadab selle päringuvastusena 2b sirvikusse.

Kasutajale kuvatakse autentimismeetodite valiku leht. Jätkame voo kirjeldamisega joonisel 3.

Joonis 3. Tagasisuunamispäring

Kasutaja valib autentimismeetodi. Valik edastatakse TARA serverikomponendile HTTP päringuga 3a.

Järgneb autentimisdialoog, vastavalt kasutaja poolt valitud autentimismeetodile. Autentimisdialoogis võidakse sirviku ja TARA serverikomponendi vahel vahetada mitmeid sõnumeid ja teha mitmeid ümbersuunamisi. Näiteks piiriülese autentimise korral saadetakse kasutaja mitmete ümbersuunamistega välisriigi autentimisteenusesse. Neid päringuid ja vastuseid tähistame joonisel “…”.

Autentimisdialoog jõuab lõpule ja kasutaja on vaja suunata tagasi klientrakendusse.

TARA serverikomponent saadab sirvikusse HTTP päringuvastuse 3b, milles on ümbersuunamiskorraldus kasutaja tagasisuunamiseks klientrakendusse.

Sirvik täidab ümbersuunamiskorralduse 3b, saates klientrakenduse serverikomponendile HTTP päringu 4a (tagasisuunamispäringu).

Tagasisuunamispäringus sisaldub õnnestunud autentimise korral volituskood (authorization code). Tagasisuunamispäring on täpsemalt kirjeldatud eraldi jaotises allpool.

Volituskood lunastatakse autenditud isiku isikukoodi, nime jm isikuandmete vastu eraldi päringu tegemisega TARA serverikomponendi poole (joonis 4).

Joonis 4. Identsustõendipäring

Klientrakenduse serverikomponent saadab TARA serverikomponendile identsustõendipäringu 5a. Identsustõendipäringus esitab klientrakendus tagasisuunamispäringus saadud volituskoodi. Klientrakendus tõendab oma ehtsust, lisades päringusse salasõna (client secret). Identsustõendipäring on nn backend-päring - see ei käi läbi sirviku.

TARA serverikomponent, saades identsustõendipäringu 5a, kontrollib salasõna ja väljastab vastuses 5b identsustõendi. Identsustõend sisaldab andmeid autentimise fakti (autentimise ajamoment, autentimismeetod) ja tuvastatud isiku kohta (isikukood, ees- ja perekonnanimi, piiriülese autentimise korral ka eraldi sünniaeg jm andmed). TARA serverikomponent allkirjastab identsustõendi. Identsustõend on täpsemalt kirjeldatud eraldi jaotises allpool.

Klientrakendus saab identsustõendi (5b). Rünnete vältimiseks peab klientrakendus kontrollima, et identsustõend on tõesti TARA poolt välja antud, klientrakendusele suunatud ja ajaliselt kehtiv.

Sellega on autentimine tehtud. Klientrakendus teab nüüd kasutaja isikut.

Tavaliselt loob klientrakendus seejärel kasutajaga seansi. Seansi loomine ei puutu enam TARA kompetentsi.

Klientrakendus saadab sirvikusse HTTP vastuse 4b, näiteks lehe “Sisse logitud”.

4 Päringud

4.1 Autentimispäring

Autentimispäring on HTTP GET päring, millega kasutaja suunatakse klientrakendusest TARA-sse autentima.

Autentimispäringu näide (URL-i query-osa on loetavuse huvides jagatud mitmele reale):

GET https://tara.ria.ee/oidc/authorize?

redirect_uri=https%3A%2F%2Feteenindus.asutus.ee%2FCallback&
scope=openid&
state=hkMVY7vjuN7xyLl5&
response_type=code&
client_id=58e7ba35aab5b4f1671a

Autentimispäringu elemendid:

4.1.1 Atribuutide küsimine välismaalase kohta

Välismaalase autentimisel suunab TARA välismaalase tema koduriigi autentimisteenusesse. Euroopa Komisjoni määrusega on riigid kokku leppinud, et teise riigi autentimisteenus on alati kohustatud väljastama füüsilise isiku kohta neli atribuuti: 1) eesnimi; 2) perekonnanimi; 3) sünniaeg; 4) isikukood vm identifikaator.

Füüsilise isiku autentimise korral tagastatakse TARAs alati nn kohustuslikud atribuudid (eesnimi, perenimi, sünniaeg ja isiku identifikaator). Täiendavate lisaatribuutide pärimist ning juriidilise isiku autentimist läbi TARA hetkel ei toeta.

4.1.2 E-posti aadressi küsimine

Skoobiga email saab nõuda, et identsustõendis väljastatakse kasutaja e-posti aadress. See võimalus on suunatud asutustele, kelle klientrakendus nõuab kasutaja autentimisel e-postiaadressi kindlakstegemist. Skoop email tuleb lisada põhiskoobile openid. Identsustõendis väljastatakse väited (claims) email ja email_verified. Näiteks:

"sub": "EE60001019906",
"email": "60001019906@eesti.ee",
"email_verified": false

Väite email väärtus loetakse kasutaja autentimissertifikaadi SAN laiendist (RFC822 tüüpi Subject Alternative Name väljast). E-posti aadress väljastatakse ainult juhul, kui kasutaja autenditakse Eesti ID-kaardiga. Klientrakenduses tuleb kindlasti arvestada, et kasutaja ei tarvitse olla oma e-posti suunanud - s.t sellel aadressil saadetud kiri ei tarvitse kasutajani jõuda.

Väite email_verified väärtus on alati false. See tähendab, et TARA ei kontrolli ega väljasta teavet, kas kasutaja on oma eesti.ee e-posti aadressi suunanud või mitte. (Vastav funktsionaalsus võib lisanduda tulevikus).

4.1.3 Mobiilinumbri küsimine

Skoobiga phone saab nõuda, et Mobiil-ID’ga autentimisel väljastatakse identsustõendis kasutaja telefoninumber. See võimalus on suunatud asutustele, kes kasutavad Mobiil-ID allkirjastamist, mis nõuab sisendina ka kasutaja telefoninumbrit. Skoop phone tuleb lisada põhiskoobile openid. Identsustõendis väljastatakse väited (claims) phone_number ja phone_number_verified. Näiteks:

"sub": "EE60001019906",
"phone_number": "+37200000766",
"phone_number_verified": true

Väite phone_number väärtus on E.164 formaadis telefoninumber koos riikliku suunakoodiga.

Väite phone_number_verified väärtus on alati true. See tähendab, et phone_number väites väljastatud telefoninumbri kuulumine autenditud isikule on autentimisprotsessi käigus kontrollitud.

Väited phone_number ja phone_number_verified väljastatakse ainult juhul, kui kasutaja autentimiseks kasutatakse Mobiil-ID’d.

4.1.4 Autentimismeetodite valikuline kasutus

Vaikimisi kuvatakse kasutajale kõik toetatud ja eIDAS autentimistaseme poolt lubatud autentimismeetodid. Soovi korral on kuvatavaid autentimisvalikuid võimalik juhtida scope parameetri väärtuste abil. Sobivaid autentimismeetodeid on võimalik kombineerida, koostades loetelu soovitud autentimismeetoditest (lubatud väärtuste nimekiri on toodud tabelis 1).

Autentimismeetodite valikulise kasutuse korral on täiendava turvameetmena vajalik identsustõendis amr väite kontroll (loe ka jaotis 5.1 Identsustõendi kontrollimine).

Tabel 1 - autentimisvalikute kuvamine

Näide 1: Kõik autentimismeetodid scope=openid

Näide 2: Ainult ID-kaardi ja Mobiil-ID kasutus scope=openid%20idcard%20mid

Näide 3: Ainult piiriülene autentimine scope=openid%20eidas

Näide 4: Piiriülene autentimine ilma TARA kasutajaliideses riigi valikuta. Riik valitakse autentimist alustanud infosüsteemis. scope=openid%20eidasonly%20eidas%3Acountry%3Abe

4.2 Tagasisuunamispäring

Tagasisuunamispäring on HTTP GET päring, millega kasutaja suunatakse autentimise järel TARA-st tagasi klientrakendusse.

Tagasisuunamine tehakse klientrakenduse poolt autentimispäringus kaasa antud naasmisaadressile. Tagasisuunamispäringus edastab TARA klientrakendusele volituskoodi (authorization code), mille alusel klientrakendus pärib (eraldi päringuga) TARA-lt autenditud isiku isikukoodi, nime jm atribuudid. Tehniliselt tehakse tagasisuunamine HTTP redirect-päringuga.

Tagasisuunamispäringu näide:

HTTP GET https://eteenus.asutus.ee/tagasi?
code=71ed5797c3d957817d31&
state=OFfVLKu0kNbJ2EZk

Tagasisuunamispäringu elemendid:

Päring võib sisaldada muid URL-i parameetreid, mida klientrakendus peab ignoreerima.

Veateade tagasisuunamispäringus. Kui TARA ei suutnud autentimispäringut töödelda - päring kas oli vigane, kasutaja otsustas autentimise katkestada või tekkis muu viga, siis saadab TARA tagasisuunamispäringus veakoodi (URL-i parameeter error) ja veakirjelduse (URL-i parameeter error_description).

Juhul kui kasutaja katkestab TARA-s autentimise (“Tagasi teenusepakkuja juurde” link esilehel), tagastatakse veakood user_cancel.

Muude veakoodide tagastamisel lähtub TARA OpenID Connect standardist (loe võimalike veakoodide kohta siit ja siit) ja veakirjelduse tekst esitatakse alati inglisekeelsena.

Tagastatakse ka state, kuid volituskoodi (code) ei saadeta. Nt:

HTTP GET https://eteenus.asutus.ee/tagasi?
error=invalid_scope&
error_description=Required+scope+%3Copenid%3E+not+provided.+
TARA+do+not+allow+this+request+to+be+processed&
state=qnYY56Ra8QF7IUzqvw+PPLzMKoHtQkuUWbV/wcrkvdU=

Tagasisuunamispäringu vigade korral on tavaliselt probleem liidestuses ja error_description parameetris esitatavat veakirjeldust ei ole vaja otse kasutajale kuvada. Klientrakenduses tuleks kontrollida, kas saadeti veakood.

Autentimise katkestamine. Kasutaja võib e-teenusesse tagasi pöörduda ka ilma autentimismeetodit valimata ja autentimist läbi tegemata (link “Tagasi teenusepakkuja juurde”). See võimalus on mõeldud juhuks, kui kasutaja vajutas klientrakenduses “Logi sisse”, kuid tegelikult ei soovi sisse logida.

Autentimise katkestamise korral suunatakse kasutaja tagasi teenusepakkuja juurde tagasisuunamispäringuga, mille veakood on user_cancel ¹

¹ Alates augustist 2020 ei nõua RIA teenusega liitumise taotluses asutuselt enam eraldi URL-i tagasipöördumisurli kasutaja katkestamise jaoks (URL, kuhu suunatakse juhul kui kasutaja vajutab “Tagasi teenuspakkuja juurde”. NB! OpenID Connect protokolli kohane tagasisuunamis-URL ja siin nimetatud URL on erineva tähendusega).

4.3 Identsustõendipäring

Identsustõendipäring on HTTP POST päring, millega klientrakendus pärib TARA serverilt identsustõendi (ID token).

Identsustõendipäringu näide (HTTP POST päringu keha on loetavuse huvides jagatud mitmele reale):

POST /oidc/token HTTP/1.1
Host: tara.ria.ee
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

grant_type=authorization_code&
code=SplxlOBeZQQYbYS6WxSbIA&
redirect_uri=https%3A%2F%2eteenus.asutus.ee%2Ftagasi

Identsustõendipäringus tuleb esitada salasõna. Selleks tuleb päringusse lisada Authorization päis (request header), väärtusega, mis moodustatakse sõnast Basic, tühikust ja Base64 kodeeringus stringist <client_id>:<client_secret> (vt RFC 2617 HTTP Authentication: Basic and Digest Access Authentication, jaotis 2 Basic Authentication Scheme).

HTTP POST päringu keha peab olema esitatud OpenID Connect protokolli kohaselt serialiseeritud kujul.

Päringu kehas tuleb esitada järgnevad parameetrid:

4.3.1 Identsustõend

TARA server kontrollib, et identsustõendit küsiv klientrakendus on TARAs registreeritud. Seejärel väljastab päringu vastuses (HTTP response body) identsustõendi.

Päringu vastus on JSON-struktuur, milles on neli elementi (vt järgnev tabel).

Päringu vastus võib sisaldada muid välju, mida klientrakendus peab ignoreerima.

Identsustõend on TARA poolt väljastatav tõend autentimise fakti kohta.

Identsustõend väljastatakse veebitõendi (JSON Web Token, JWT) vormingus.

Identsustõend on alati allkirjastatud.

Näide (identsustõendi sisu e payload):

{
  "jti": "0c597356-3771-4315-a129-c7bc1f02a1b2",
  "iss": "https://tara-test.ria.ee",
  "aud": "TARA-Demo",
  "exp": 1530295852,
  "iat": 1530267052,
  "nbf": 1530266752,
  "sub": "EE60001019906",
  "profile_attributes": {
    "date_of_birth": "2000-01-01",
    "family_name": "O’CONNEŽ-ŠUSLIK TESTNUMBER",
    "given_name": "MARY ÄNN"
  },
  "amr": [
    "mID"
  ],
  "state": "1OnH3qwltWy81fKqcmjYTqnco9yVQ2gGZXws/DBLNvQ=",
  "nonce": "",
  "at_hash": "X0MVjwrmMQs/IBzfU2osvw=="
}

Identsustõendis väljastatakse järgmised väited (claims).

Identsustõend võib sisaldada muid OpenID Connect protokolli kohaseid välju, kuid neid teenuses ei kasutata.

Klientrakendus peab identsustõendile järgi tulema kohe tagasisuunamispäringu saamisel. Kui identsustõendit ei pärita 30 sekundi jooksul, siis volituskood (authorization code) aegub ja autentimisprotsessi tuleb korrata.

4.4 Kasutajainfopäring

Kasutajainfopäring võimaldab kehtiva OAuth 2.0 pääsutõendi alusel küsida infot autenditud kasutaja kohta. Päring peab olema esitatud HTTP GET meetodil. Kehtiva pääsutõendi korral väljastatakse JSON vormingus vastus.

Pääsutõend tuleb esitada kasutajainfot väljastavale otspunktile Bearer Token meetodil HTTP päises (soovituslik) või URLi parameetrina.

Näide 1 - pääsutõendi edastamine Authorization päises:

GET /oidc/profile HTTP/1.1
Host: tara.ria.ee
Authorization: Bearer AT-20-qWuioSEtFhYVdW89JJ4yWvtI5SaNWep0

Näide 2 - pääsutõendi edastamine access_token parameetrina :

GET /oidc/profile?access_token=AT-20-qWuioSEtFhYVdW89JJ4yWvtI5SaNWep0 HTTP/1.1
Host: tara.ria.ee

Kehtiva pääsutõendi korral väljastatakse JSON vormingus vastus.

Näide:

{
  "amr": [
    "mID"
  ],
  "date_of_birth": "2000-01-01",
  "family_name": "O’CONNEŽ-ŠUSLIK TESTNUMBER",
  "given_name": "MARY ÄNN",
  "sub": "EE60001019906",
  "auth_time": 1550735597
}

Vastuses esitatavad väited väljastatakse identsustõendi alusel.

¹ Väljastatakse ainult juhul, kui antud väide on esitatud ka identsustõendis.

Päringu vastus võib sisaldada muid välju, mida klientrakendus peab ignoreerima.

Vigade käsitlemine

Juhul kui kasutajainfo otspunktile esitatav pääsutõend puudub või on aegunud tagastatakse veakood ja lühikirjeldus WWW-Authenticate päises vastavalt OpenID Connect Core 1.0 spetsifikatsioonile

Näide:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token",error_description="The access token has expired"

5 Turvatoimingud

5.1 Identsustõendi kontrollimine

Klientrakendus peab identsustõendit kindlasti kontrollima. Teostada tuleb kõik protokollikohased (OpenID Connect ja selle alusprotokoll OAuth 2.0) kontrollid.

Kontrollida tuleb:

• tõendi allkirja
• tõendi väljaandjat
• tõendi adressaati
• tõendi ajalist kehtivust
• kasutaja autentinud autentimismeetodit tõendis
• ülepiirilise autentimise korral eIDAS autentimistaset tõendis

Lähemalt nendest kontrollidest allpool. Vajadusel saate täpsemat teavet OpenID Connect ja OAuth 2.0 protokollikirjeldustest.

5.1.1 Allkirja kontrollimine

Identsustõend väljastatakse autentimisteenuse TARA poolt allkirjastatult. Allkiri vastab JWT standardile.

Allkirjaalgoritmina kasutab TARA RS256. Klientrakendus peab suutma vähemalt selle algoritmiga antud allkirja kontrollida. Allkirja kontrollimine on otstarbekas teostada standardse JWT teegiga, mis toetaks kõiki JWT algoritme. Seda vähetõenäoliseks, kuid siiski võimalikuks juhuks, kui RS256-s peaks avastatama turvanõrkus, mis tingib algoritmi vahetamise.

Allkirja kontrollimisel tuleb kasutada TARA avalikku allkirjavõtit (edaspidi “võti”). Võtme saate võtmeväljastuse otspunktist.

Võti on tüüpiliselt stabiilne. Vahetame võtit vastavalt turvasoovitustele, kuid ei ole välistatud erakorraline võtmevahetus võtme korrumpeerumise korral. Võtmevahetuse protsess on kirjeldatud eraldi peatükis.

Võtmel on identifikaator (kid). Võtmeidentifikaatorite osas järgime OpenID Connect ja OAuth 2.0 soovitatud praktikat, mis teeb võimalikuks võtmevahetuse ilma teenuse katkestuseta.

Identsustõendi päringu vastuses väljastab TARA klientrakendusele ka kid (JWT päise (header) element kid). See kid osutab võtmele, mida peate väljastatud tõendi allkirja kontrollimisel kasutama.

Soovitame võtit puhverdada (koos kid väärtusega), kuna see vähendab TARA serveri poole tehtavate päringute arvu. Kuid aktsepteeritav on ka võtme pärimine igas autentimises.

Eeltoodust lähtuvalt peab allkirja kontrollimisel teostama järgnevad tegevused:

1 - JWT päisest lugema element kid väärtuse.

2.1 - Juhul kui võtit ei puhverdata, teostama päringu võtmeväljastuse otspunktile ning võtma JWT päisest saadud kid väärtusele vastava võtme.

2.2 - Võtme puhverdamisel tuleb seda teha koos kid väärtusega. Valideerimisel võrrelda vastusest saadud kid väärtust puhverdatud võtme kid väärtusega. Juhul kui väärtused kattuvad kasutada puhverdatud võtit. Mittekattumise korral tuleb teostada päring võtmeväljastuse otspunktile ning võtta JWT päisest saadud kid väärtusele vastav võti ning puhverdada see koos vastava kid väärtusega. Alternatiivina võib puhverdada võtmeväljastuse otspunktist kõik võtmed koos kid väärtustega ning valideerimisel kasutada puhvrist sobivat võtit. Sellisel juhul peaks puhver olema aeguv. Soovitav puhvri eluiga peaks jääma vahemikku 5 minutit kuni 24 tundi.

3 - Teostama allkirja kontrolli JWT päises oleva kid väärtusele vastava võtmega.

Ülalesitatu teostamist võib mõjutada, kas liidestate TARA-ga “karbitoodet”, üritate hakkama saada mõne OpenID Connect teegi seadistamisega või programmeerite liidestuse ise. Teegid ja karbitooted ei tarvitse puhverdamist toetada.

NB! Kindlasti tasuks vältida võtme käsitsi kirjutamist klientrakenduse konfiguratsiooni. Võtme vahetusest teatatakse tüüpiliselt küll ette (va kiirest turvavajadusest tingitud vahetus), kuid selline lahendus vajab klientrakenduse poolset käsitsi seadistust ning toob kaasa teenuse katkemise perioodiks mil TARA kasutab juba uut võtit aga klientrakendusse ei ole uut võtit seadistatud.

5.1.2 Otspunktide TLS ühenduse kontrollimine

Klientrakendusest TARA poole sooritatavatel päringutel (kõikidesse otspunktidesse ehk teenuseteabe otspunkti, võtmeväljastusotspunkti, tõendiväljastusotspunkti) tuleb TLS ühenduse algatamisel sooritada korrektselt kõik vajalikud kontrollid. Soovitatav on neid mitte ise implementeerida, vaid kasutada mõnda HTTPS või TLS ühenduste funktsionaalsusega teeki.

Klientrakenduses peab TLS ühenduse usaldusankruks määrama järgmised juursertifikaadid:

• DigiCert Global Root G2;
• GlobalSign R4;
• GTS Root R1;
• GTS Root R2;
• GTS Root R3;
• GTS Root R4;
• ISRG Root X1;
• ISRG Root X2.

Soovitatav ei ole klientrakenduses usaldada teiste CA-de sertifikaate ega tervet operatsioonisüsteemi CA sertifikaatide hoidlat. Veebisirvikud usaldavad paljude CA-de sertifikaate, kuid neil on sertifikaatide volitamata väljastamise probleemi leevendamiseks kasutusel Certificate Transparency mehhanism. TARA autentimisvoog on kombinatsioon veebisirviku poolt ja klientrakenduse poolt tehtavatest päringutest, seega autentimisvoo terviklikuks õnnestumiseks rakendub mõlema poolt sooritatavate kontrollide ühend.

HTTPS või TLS ühenduste funktsionaalsusega teek peab iga ühenduse algatamisel teostama järgnevad kontrollid:

• kontrollima, kas moodustub valiidsete allkirjadega sertifikaadiahel, mis lõpeb mõnega ülalnimetatud juursertifikaatidest;
• kontrollima, kas päringus olev hostname (tara.ria.ee või tara-test.ria.ee) vastab serveri esitatud sertifikaadis olevale CN väljale või sisaldub SAN väljal;
• kontrollima ahela kõikidel sertifikaatidel kehtivuse alguse ja lõpu väärtuseid;
• kontrollima sertifikaatides defineeritud constraint‘e (basic, name, key usage, critical extensions).

Lisaks tuleb jälgida ahela kõikide sertifikaatide tühistamist mõnel järgnevatest viisidest:

• RIA teavitab sertifikaatide tühistamisest liidestujate kontaktisikuid e-kirjaga.
• Klientrakendus võib kontrollida CA poolt pakutavat kehtivuskinnitusteenust (OCSP) või tühistusnimekirja (CRL), kuid peab arvestama, et RIA ei vastuta CA kui välise osapoole teenuste kättesaadavuse eest. tara.ria.ee ja tara-test.ria.ee otspunktid võivad, aga ei pruugi kehtivuskinnituse klammerdamist (OCSP stapling) pakkuda või see võib etteteatamata muutuda.

5.1.3 Tõendi väljaandja kontrollimine

Identsustõendi elemendi iss väärtus peab olema https://tara-test.ria.ee (TARA testkeskkonna puhul) või https://tara.ria.ee (TARA toodangukeskkonna puhul).

5.1.4 Tõendi adressaadi kontrollimine

Klientrakendus peab kontrollima, et saadud tõend on välja antud just temale. Selleks veenduda, et identsustõendi elemendi aud väärtus ühtib klientrakendusele registreerimisel väljaantud kliendinimega (Client ID).

5.1.5 Tõendi ajalise kehtivuse kontrollimine

Kontrollitakse kolme identsustõendis sisalduva elemendi abil - iat, nbf, exp. Klientrakendus kasutab kontrollimisel oma kellaaega. Kontrollida tuleks, et:

1) “not before” ajamoment on kätte jõudnud:

nbf <= jooksev_aeg + kellade_lubatud_erinevus

2) “expired” ajamoment ei ole kätte jõudnud:

exp > jooksev_aeg - kellade_lubatud_erinevus.

kellade_lubatud_erinevus väärtus valida ise. Need kontrollid on vajaliku rünnete ja sassiminekute vältimiseks.

TARA põhimõte on, et identsustõendile tuleb järgi tulla kohe, 30 sekundi jooksul. Selle aja ületamisel identsustõendit ei väljastatagi.

5.1.6 Autentimismeetodi kontrollimine

Juhul kui kasutusel on autentimismeetodite valikuline kuvamine (vt jaotis 4.1.4 Autentimismeetodite valikuline kasutus), peab identsustõendis veenduma, et identsustõendi amr väites (authentication method reference) toodud autentimismeetod on lubatud. Vastasel juhul võetakse vahendajaründe risk, kus autentimispäringu scope parameetri manipuleerimise läbi on võimalik kasutajal autentida meetodiga, mis pole liidestuja süsteemis aktsepteeritav (nt ID-kaardiga autentimise asemel kasutatakse Smart-ID-d).

Näide: Kui autentimispäringus on scope parameetris määratud ainult ID-kaart, tuleb veenduda, et identsustõendi amr väide sisaldaks koodi idcard (koodide nimekiri on toodud jaotises 4.3.1 Identsustõend).

5.1.7 Minimaalse lubatud eIDAS autentimistaseme kontrollimine

Välistamaks ligipääsu soovitust madalama turvalisusastmega autentimisvahenditele, peab autentimisel kontrollima, et identsustõendi acr väites esitatud autentimistase ei oleks väiksem minimaalsest lubatud autentimistasemest (loe autentimistasemete kohta siit).

Näiteks, kui liidestuja soovib kasutada vaid kõrge eIDAS autentimistasemega autentimisvahendeid ja täpsustab acr_values parameetris high väärtuse, tohib aktsepteerida ainult identsustõendeid, mille acr väite väärtus on high.

Juhul kui autentimispäringus eIDAS autentimistaset acr_values parameetri abil ei täpsustatud, peab identsustõendis olev väärtus olema substantial või high.

5.1.8 Seansi loomine

Identsustõendi eduka kontrollimise järel loob klientrakendus kasutajaga seansi (“logib kasutaja sisse”). Seansi loomine ja pidamine on klientrakenduse kohustus. Kuidas seda teha, ei ole enam autentimisteenuse TARA skoobis.

Märkus. Tavaliselt peetakse veebirakendusega seanssi küpsises hoitava seansitõendi (session token) abil. Seansitõend võib olla juhusõneline (opaque) või veebitõend (JWT). Identsustõend ei sobi otseselt seansitõendiks, sest identsustõendi kehtivusaeg väljendab tõendi väljastamise perioodi, mitte seansi kehtivusperioodi. Küll aga saab klientrakendus seansitõendi koostada identsustõendi põhjal, valides seansi sobiva kehtivusaja.

5.2 Võltspäringuründe vastane kaitse

Klientrakenduses tuleb rakendada võltspäringuründe (cross-site request forgery, CSRF) vastaseid kaitsemeetmeid. Seda tehakse turvakoodide state ja nonce abil. state kasutamine on kohustuslik; nonce kasutamine on vabatahtlik. Kirjeldame state kasutamise protseduuri, kasutades klientrakenduses seatud küpsist (sellisel juhul ei pea klientrakendus saadetud state parameetri väärtust ise meeles pidama).

Turvakoodi state kasutatakse autentimispäringule järgneva tagasisuunamispäringu võltsimise vastu. Klientrakenduses tuleb teostada järgmised sammud:

1 Genereerida juhusõne, näiteks pikkusega 16 tärki: XoD2LIie4KZRgmyc (tähistame R).

2 Arvutada juhusõnest R räsi H = hash(R), näiteks SHA256 räsialgoritmiga ja teisendades tulemuse Base64 vormingusse: vCg0HahTdjiYZsI+yxsuhm/0BJNDgvVkT6BAFNU394A=.

3 Seada vahetult enne autentimispäringu tegemist klientrakenduse domeenile küpsis, mille väärtuseks juhusõne R.

Set-Cookie ETEENUS=XoD2LIie4KZRgmyc; HttpOnly,

kus ETEENUS on vabalt valitud küpsisenimi. Küpsisele tuleb rakendada atribuuti HttpOnly.

4 Seada TARA autentimispäringu tegemisel p 2 arvutatud räsi parameetri state väärtuseks:

GET ... state=vCg0HahTdjiYZsI+yxsuhm/0BJNDgvVkT6BAFNU394A=

Parameetri state pikkus peab olema minimaalselt 8 tähemärki.

Tagasisuunamispäringu töötlemisel peab klientrakendus tegema järgmist:

5 Võtab päringuga tuleva küpsise ETEENUS väärtuse (tagasisuunamispäringuga saadetakse kasutaja kaks asja: kasutaja brauserist juhusõne küpsisena ja juhusõnest arvutatud räsiväärtus state parameetris).

6 Arvutab küpsise väärtusest räsi ja teisendab base64 kodeeringusse.

7 Kontrollib, et räsi ühtib tagasisuunamispäringus tagasipeegeldatava state väärtusega.

Tagasisuunamispäringut tohib aktsepteerida ainult ülalkirjeldatud kontrolli õnnestumisel.

Kirjeldatud protseduuris on võtmetähtsusega väärtuse state sidumine sessiooniga. Seda tehakse küpsise abil. (See on autentimise ajutine sessioon. Töösessiooni moodustab klientrakendus pärast autentimise edukat lõpuleviimist).

Täiendav teave: OpenID Connect protokollis kahjuks ei ole teema selgelt esitatud. Mõningast teavet saab soovi korral mitteametlikust dokumendist OpenID Connect Basic Client Implementer’s Guide 1.0, jaotis “2.1.1.1 Request Parameters”.

Soovi korral võite veel tutvuda ründe (ja kaitse) detailse seletusega: Võltspäringurünne ja kaitse selle vastu.

5.3 Logimine

Logimine peab võimaldama rekonstrueerida TARA ja klientrakenduse suhtluse käigu TARA iga kasutuse jaoks. Selleks tuleb nii TARA kui ka klientrakenduse poolel logida kõik päringud ja päringute vastused: autentimispäring, tagasisuunamispäring ja identsustõendipäring. Kuna edastatavad andmemahud ei ole suured, siis tuleb logida nii URL kui ka identsustõend täielikul kujul. Logide säilitamistähtaja määramisel arvestada klientrakenduse olulisust. Orientiiriks pakume 1..7 aastat. Probleemide lahendamiseks pöördumisel palume esitada väljavõte logist (mis päringud TARA poole saadeti? mis saadi vastuseks?).

5.4 Identsustõendi allkirjastamise võtme vahetus

Võtmevahetuse protsessis järgitakse OpenID Connect standardit.

RIA teavitab identsustõendi allkirjastamise võtme vahetamisest liidestujate kontaktisikuid e-kirjaga.

Kuni teavitatava kuupäevani allkirjastab TARA identsustõendeid seni kasutusel oleva võtmega. Alates teavitatavast kuupäevast hakkab TARA allkirjastama identsustõendeid uue võtmega, mis lisatakse võtmeväljastuse otspunkti hiljemalt sellega esimese identsustõendi allkirjastamise ajaks. Seega on teatud ajaperioodil võtmeväljastuse otspunktis nähtavad kaks avalikku võtit korraga, kumbki oma unikaalse kid identifikaatoriga. Näide kahe võtme publitseerimisest:

{
   "keys": [
      {
         "use": "sig",
         "kty": "RSA",
         "kid": "8b2c7561-fdf8-41d4-b466-ab323c3865c6",
         "alg": "RS256",
         "n": "sqEw...",
         "e": "AQAB"
      },
      {
         "use": "sig",
         "kty": "RSA",
         "kid": "1c5b7961-41d4-b468-a768-db523c3617f4",
         "alg": "RS256",
         "n": "y7XY...",
         "e": "AQAB"
      }
   ]
}

Vana avalik võti eemaldatakse võtmeväljastuse otspunktist pärast seda kui sellega allkirjastatud viimased identsustõendid on aegunud.

Vaata ka peatükki Allkirjade kontrollimine, kus kirjeldatakse, kuidas peab avalikku võtit allkirja kontrollimiseks kasutama.

6 Otspunktid ja aegumisajad

6.1 Testteenus

6.2 Toodanguteenus

6.3 Aegumisajad (timeout)

7 Soovitusi liidestajale

TARA-ga liidestamine on lihtne. Siiski on vaja töid kavandada ja hoolikalt teostada.

Liidestuja peab erilist tähelepanu pöörama, et kõik protokollikohased kontrollid saaksid tehtud - turvaelemendi state ja kui kasutatakse, siis ka nonce kontroll, identsustõendi kontroll jm. Vt ID token validation [Core].

Liidestamise protsess näeb välja järgmine.

Asutus peaks välja selgitama, kas ja millistes oma e-teenustes soovib TARA kasutada. Selleks tuleks tutvuda TARA ärikirjeldusega, teenustaseme leppega (SLA-ga), käesoleva tehnilise kirjeldusega. Vajadusel pidada nõu RIA-ga, help@ria.ee.

Seejärel kavandada ja teostada teenuse kasutamiseks vajalik arendustöö - klientrakenduse täiendamine OpenID Connect protokolli kohase klientkomponendiga, sh testimine. Hinnanguline töömaht: kogenud arendajal u 2 päeva; kui OpenID Connect-i pole varem teinud, siis 2 nädalat. Aluseks käesolev tehniline kirjeldus

Arenduse valmides tuleb liidest testida. Selleks kasutatakse TARA testteenust. Asutus esitab taotluse testteenusega liitumiseks. Taotluse võib esitada juba enne arenduse algust. Taotluses teatab asutus:

• teenuse, millega soovitakse liituda (test- või toodanguteenus)
• kinnituse, et liituja on välja arendanud omapoolse liidese ja seda TARA testteenuse vastu testinud (toodanguteenusega liitumise puhul)
• e-teenuse või -teenused, mille kasutajaid soovitakse TARA abil autentida
• kasutajate arvu prognoosi
• kohustumuse kasutada teenust eesmärgipäraselt. Sh testteenust kasutada ainult testimiseks, mitte toodangus autentimiseks
• nõustumuse teenustasemega (SLA-ga)
• klientrakenduse identifikaatori ettepanek -client_id, OpenID Connect protokolli kohaselt
• klientrakenduse testversiooni tagasisuunamis-URL (redirect-URL), OpenID Connect protokolli kohaselt. Lubatud on ainult HTTPS protokoll. URL-i fragmendi osa (# sümbol ja sellele järgnev osa) kasutamine ei ole lubatud.
• autentimismeetod või meetodid, mida soovitakse kasutada
• klientrakenduse haldaja kontaktandmed (e-post, telefon, isikukood).

Taotlus esitatakse ja edasine suhtlus teenuse haldamisel käib läbi RIA kasutajatoe, help@ria.ee. Vt lähemalt RIA autentimisteenuste lehel.

RIA, rahuldades taotluse:

• väljastab asutusele klientrakenduse salasõna client_secret. Salasõna on ette nähtud identsustõendi päringute allkirjastamiseks
• avab asutuse klientrakenduse testversioonile juurdepääsu testteenusele.

Järgneb liidestuse testimine. RIA abistab siin võimalike probleemide lahendamisel. Vaata lähemalt testimise juhiseid.

Tasub pilk heita abi peatükile.

Liitumine TARA toodanguteenusega. Eduka testimise järel asutus esitab taotluse toodanguteenuse avamiseks klientrakendusele. Taotluses näidatakse klientrakenduse toodanguversiooni tagasisuunamis-URL (redirect_uri), OpenID Connect protokolli kohaselt jm andmed

RIA, rahuldades taotluse, väljastab asutusele klientrakenduse toodanguversiooni salasõna client_secret ja avab asutuse klientrakenduse toodanguversioonile juurdepääsu toodanguteenusele.

8 eIDAS autentimistasemed

eIDAS autentimistase on eIDAS määruse kohaselt autentimisvahendile määratud usaldusväärtuse tase (kõrge, märkimisväärne, madal), mis on määratud rakendusmääruse (EL) 2015/1502 sätete alusel. Taseme määramisel hinnatakse autentimisvahendi kasutuse erinevaid aspekte - identiteedi väljastamise alused, lahenduse haldus, tehniline lahendus ja organisatoorsed protsessid (loe rohkem siit).

TARA-s kasutatavate siseriiklike autentimisvahendite autentimistasemed kinnitab RIA. Autentimistaseme määramisel tuginetakse eIDAS rakendusmääruses toodud autentimistasemete nõuetele.

Siseriiklikele autentimismeetoditele on TARA-s määratud järgmised autentimistasemed:

¹NB! Tase kehtib vaid Eesti isikukoodiga isikutele, kellele on Smart-ID konto. Tuleb arvestada, et mitteresidendid (Eesti e-residendid) pole eristatavad residentidest.

Välisriigi autentimismeetodite autentimistasemed on määratud vastava välisriigi enda poolt ja neist teavitatakse teisi liikmesriike vastavalt eIDAS määruse nõuetele. Nimekirja kõigist ülepiiriliselt kasutatavatest autentimismeetoditest, millest riigid on teisi liikmesriike teavitanud, leiab siit.

9 Erasektori asutuse erisused

Erasektori asutuste liidestumisprotsessid ja autentimisvood on avaliku sektori asutustega identsed.

Võrreldes avaliku sektori asutustega on erasektori asutuste jaoks autentimisel lubatud kohustuslik skoop openid koos piiriülese eIDAS-autentimise skoopidega eidas, eidasonly, eidas:country:xx. Vt ka scope parameetri kohta autentimispäringus.

eidas:country:xx skoop töötab üksnes koos eidasonly autentimisvalikuga.

eidas:country:xx skoop võimaldab TARAga liidestujal jätta vahele TARA kasutajaliidese kuva ning suunata autentija vahetult skoobis määratud riigi autentimisteenusesse.

Testkeskkonnas on erasektori asutustele kuvatud rohkem riike, kui toodangukeskkonnas toetatud on. Kõik kuvatud riigid ei pruugi toetada erasektori autentimist.

Toodangukeskkonnas on erasektori asutustele hetkel toetatud autentimiseks järgnevad riigid:

NB! Riigi Infosüsteemi Amet ei taga teiste riikide autentimisteenuste toimimist. Erasektori autentimise võimalus sõltub eIDAS liikmesriikidest ning võib vastavalt liikmesriikide tegevusele muutuda.

Muutelugu