10 Autentimine

PISTRIKu API päringute autentimine ja autoriseerimine

PISTRIKu API kõigi teenuste tarbimine eeldab päringu tegija autentimist ja autoriseerimist (edaspidi autentimine API kihis). Lisaks API kihile toimub autentimine päringu liikumise teekonnal päringu algatajast API-ni kokku kolmes kohas:

1. Kliendi turvaserveriga ühenduse loomisel - PISTRIKu API tarbija ehk kliendi (nt cURL) ja tarbija turvaserveris (consumer security server) registreeritud kliendi alamsüsteemi vahel. Täpselt selgitatud peatükis: Autentimine x-tee turvaserveris
2. X-tee turvaserverite vahel - tarbiva ja pakkuva turvaserververi vahelise kahepoolse autentimisega krüpteeritud ühendus luuakse automaatselt turvaserverite poolt vastavalt x-tee transpordiprotokollile
3. PISTRIKu APIs - päringu päises oleva võtme kontroll vastu iseteeninduskeskkonnas ettevõtja poolt genereeritud API võtit

Lisaks teostatakse päringu saabumisel teenusepakkuja turvaserverisse ligipääsuõiguse kontrolli eelnevalt turvaserveris salvestatud ligipääsuõigustele (access control list), vastavalt x-tee transpordiprotokollile (16. Verify service access rights)

Autentimine API kihis

Ettevõtjate poolt PISTRIKusse sisestatud ärisaladusena käsitletavale teabele x-tee teenuste kaudu ligipääsuks tuleb igale päringule juurde lisada salajane API võti, mille on ettevõtja eelnevalt iseteeninduskeskkonnas omale genereerinud. Antud lahendus põhineb bearer token authorization meetodil, st iga HTTP päringu päises peab olema Authorization: Bearer <yourSecretBearerToken>. Token-i väärtusena on kasutusel base64 kodeeringus juhusõne opaque tokens.

Kõik PISTRIKu API x-tee päringud peavad sisaldama järgmiseid päiseid:

Päis	Selgitus	Näidis
X-Road-Client	X-tee teenuse tarbija alamsüsteem	ee-test/GOV/70008658/pistrik-client
Authorization	PISTRIKu iseteeninduskeskkonnas genereeritud API võti	Bearer qfVhvXbC7vqa3VPnRWWqOqLbB5Oh0XQQd4WFBgrQ5HbCdRBGKxCN1aSvBKmcdbYMmWwR7bZBkI0oOXWdaeFWvg==

Important

NB! API võti peab olema genereeritud PISTRIKu iseteeninduskeskkonnas x-tee teenuse tarbija alamsüsteemi omaniku poolt, st x-tee päringu päises olev clientMemberCode on võtme genereerinud juriidilise isiku äriregistrikood.

Juhul kui liidestutakse platvormiteenuse pakkuja vahendusel siis tuleb täiendavalt juurde lisada X-Road-Represented-Party päis ja Authorization: päises kasutada API võtmena PISTRIKus platvormiteenuse kliendi poolt genereeritud ja antud platvormiteenuse pakkujaga seotud API võtit:

Päis	Selgitus	Näidis
X-Road-Client	Platvormiteenuse pakkuja alamsüsteem	ee-test/GOV/70008658/pistrik-client
X-Road-Represented-Party	Platvormiteenuse pakkuja kliendi (ehk kelle andmeid PISTRIKusse edastatakse) äriregistrikood	12345678
Authorization	PISTRIKu iseteeninduskeskkonnas genereeritud API võti	Bearer qfVhvXbC7vqadVPnRWWqOqLbBSOh0XQQdCWFBgrQ5HbCdRBGKxCN1aSvBKmcdbYMmWwR7bZBkI0oOXWdaeFWvg==

API võtme genereerimine

API võtmeid saab genereerida PISTRIKuga andmeid vahetada sooviv juriidilise isiku esindaja, kes on PISTRIKu iseteeninduskeskkonda sisse loginud äriregistri esindusõigusega või omab PISTRIKus süsteemisisest volitust `API juurdepääsuhalduse privileegiga.

Ühel juriidilisel isikul võib olla mitu API võtit (et võimaldada API võtmete roteerimist). Lisaks võib iga API võti olla seotud ühe platvormiteenuse pakkujaga, kui PISTRIKuga andmeid masinliidese kaudu vahetada sooviv isik kasutab mõne platvormiteenuse pakkuja teenust.

API võtit saab genereerida menüüpunkti API => API juurdepääsuload alt.

Caution

Turvalisuse tagamiseks kuvatakse API võtme salajane väärtus kasutajale PISTRIKu iseteeninduskeskkonnas vaid üks kord võtme esialgsel genereerimisel. Hiljem pole võimalik varemloodud võtme väärtust vaadata, küll aga saab luua uue võtme väärtuse.

Caution

Veenduge, et kõrvalised isikud ei pääseks API võtmele ligi! Kuna sellega saab x-tee turvaserveris asjakohast ligipääsu omades, Teie ettevõtte/asutuse nimel PISTRIKus andmeid vaadata, lisada, muuta ja kustutada!

Otseliidestuja API võtme genereerimine

Platvormiteenuse pakkujale API võtme genereerimine

Autentimine x-tee turvaserveris

Reeglina tuleb x-tee päringuid käivitava kliendi ja turvaserveri vahel luua kahepoolse autentimisega krüpteeritud ühendus (mutual TLS authentication RFC 8120).

Turvaserveri kasutusjuhendis on pikemalt lahti selgitatud vaikeseadistus:

HTTPS - a.k.a. HTTPS with Client Authentication protocol (default for new clients) should be used to protect against unauthorised communication in addition to potential eavesdropping and interception. Before HTTPS can be used, internal TLS certificates must be created for the information systems and uploaded to the Security Server.

By default the connection type for all the Security Server clients is set to HTTPS to prevent unauthorised use of the clients.

It is strongly recommended to keep the connection type of the Security Server owner as HTTPS to prevent Security Server clients from making operational monitoring data requests as a Security Server owner.

Turvaserveri alamsüsteemi poole pöörduva kliendi autentimiseks kasutatava serdi ja privaatvõtme võib ka ise genereerida. Vastav juhend on toodud järgmises peatükis: Autentimisserdi ja privaatvõtme genereerimine .

Autentimisserdi ja privaatvõtme genereerimine

X-tee päringuid teostavale kliendile 10-aastase kehtivusajaga autentimissertifikaadi ja privaatvõtme genereerimiseks saab kasutada näiteks openssl käsurea töövahendit:

openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes -out 70008658_TEST_pistrik-client_public_cert.pem -keyout 70008658_TEST_pistrik-client_private.key

Genereeritud sertifikaat (70008658_TEST_pistrik-client_public_cert.pem) tuleb edastada turvaserveri administraatorile ja lisada see PISTRIKu x-tee teenuseid tarbiva alamsüsteemi alla tarbija turvaserveris.

Privaatvõti (70008658_TEST_pistrik-client_private.key) koos serdiga tuleb võtta kasutusele x-tee päringuid algatavas klientrakenduses. Näiteks käsurea töövahendi cURL näitel:

curl --location '$consumerSecurityServerUrl' \
--cert 70008658_TEST_pistrik-client_public_cert.pem \
--key 70008658_TEST_pistrik-client_private.key \
--cacert security_server_certificate.pem

Turvaserveri TLS serveri serdi allalaadimine

Selleks, et klientrakendus saaks kontrollida turvaserveri identiteeti on kasutusel turvaserveri autentimiseks serveri TLS sertifikaat. Vaikimisi on kasutusel self-signed sertifikaat, mis tuleb klientrakenduses lisada usaldusväärsete serdiväljastajate (CA – certificate authority) alla. Turvaserveri TLS serdi saab alla laadida näiteks käsurea töövahendiga openssl:

openssl s_client -connect $consumerSecurityServerUrl:443 < /dev/null | sed -ne '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p' > security_server_certificate.pem

Important

Ülaltoodud opensslkäsus paikneva turvaserveri aadressi $consumerSecurityServerUrl alguses ei tohi olla protokolli https osa.