TARA-Stat. Kasutusjuhend

Sisukord

• 1 Ülevaade
• 1 Tarkvara kirjeldus
  • 1.1 Ülevaade
  • 1.2 Logikirje lisamise otspunkt
  • 1.3 Statistika väljastamise otspunkt
  • 1.4 Võtmed ja salasõnad
  • 1.5 Olulised asukohad
  • 1.6 Sõltuvused
  • 1.7 Konfigureerimine (ülevaade)
• 2 Paigaldamine ja seadistamine
  • 2.1 Ülevaade
  • 2.2 Juurdepääsude avamine
  • 2.3 Käivitamine ja seiskamine
  • 2.4 Monitooringuga ühendamine
  • 2.5 Diagnostika
  • 2.6 Logibaasi haldamine
• 3 Kasutamine
• 4 Testimine
  • 4.1 Logikirjete lisamise testrakendus
• 5 Turvamine
  • 5.1 Juurdepääsu kaitse
  • 5.2 Transpordi kaitse
  • 5.3 Sisendi puhastamine
  • 5.4 Andmebaasi kaitse
• 6 Käideldavus
• LISA 1 Veateated

1 Ülevaade

TARA-Stat on mikroteenus autentimisteenuse TARA kasutusstatistika tootmiseks ja vaatamiseks.

Käesolev dokument esitab tarkvara kirjelduse ja juhised tarkvara paigaldamiseks, hooldamiseks ja kasutamiseks.

Dokument on mõeldud TARA-Stat paigaldajale, käitajale ja kasutajale.

TARA-Stat-i on arendanud Riigi Infosüsteemi Amet.

Tähistused:

• <tara-stat> (TARA-Stat masina domeeninimi)
• <tara-stat-https-port> (TARA-Stat veebirakenduse HTTPS serveri pordinumber)
• <tara-stat-tls-port> (TARA-Stat veebirakenduse Syslog TCP TLS serveri pordinumber)

1 Tarkvara kirjeldus

1.1 Ülevaade

TARA-Stat pakub:

• võimalust autentimisteenuses TARA toimuvate autentimisündmuste logimiseks
• võimalust logi põhjal statistika arvutamiseks ja vaatamiseks. Eelkõige huvitab autentimiste arv klientrakenduste lõikes ajaperioodil.

Üldistatud arhitektuurijoonis (pordinumbrid on näitlikud):

TARA-Stat kasutajaliides statistikakasutajale:

TARA-Stat koosneb kahest komponendist:

Komponente käitatakse ühes masinas, Linux-i teenustena.

TARA-Stat-l on neli liidest:

TARA-Stat suhtleb 5 välise osapoolega.

1.2 Logikirje lisamise otspunkt

Logikirje lisamise otspunkt võtab TARA-Serverilt vastu Syslog vormingus kirjeid autentimissündmuste kohta. Logikirje tuum on JSON-vormingus.

Kirje:

• tuleb saata TCP protokolliga URL-ile <tara-stat>:<tara-stat-tls-port>, kus <tara-stat> on TARA-Stat-i domeeninimi
• peab lõppema tärgiga newline (0x0a0)
• Syslog-kirje sõnumiosa (MSG) peab olema vormistatud JSON dokumendina:

1) autentimise alguse sündmuse logimisel:

{
  "time" : "<kuupäeva formaat>",
  "clientId" : "openIdDemo",
  "method" : "banklink",
  "bank" : "SEB",
  "operation" : "START_AUTH"
}

2) autentimise eduka lõpu logimisel:

{
  "time" : "<kuupäeva formaat>",
  "clientId" : "openIdDemo",
  "method" : "banklink",
  "bank" : "SEB",
  "operation" : "SUCCESSFUL_AUTH"
}

3) autentimise ebaeduka lõpu logimisel:

{
  "time" : "<kuupäeva formaat>",
  "clientId" : "openIdDemo",
  "method" : "banklink",
  "bank" : "SEB",
  "operation" : "ERROR",
  "error" : "INTERNAL_ERROR",
}

• time, clientId, method ja operation peavad saadetavas päringus olema alati. bank on kohustuslik ainult juhul kui tegemist on pangalingi kirjega (method väärtus on banklink ). Kui mõni neist on puudu, siis tagastab TARA-Stat veateate Valesti moodustatud logikirje. Element error ei ole kohustuslik; see lisatakse TARA-Stat-i ainult siis, kui operation väärtus on ERROR.

TARA-Stat võtab saadetud kirjest olulised väljad, moodustab nendest logikirje ja salvestab logibaasi (MongoDB).

Logibaasi salvestatakse kirje vormingus:

{
  "time": "<ISO 8601 kuupäev>",
  "clientID": "<klientrakenduse nimi>",
  "method": "<autentimismeetod>",
  "bank": "<panga kood>",
  "operation": "<sündmuse koodnimetus>",
  "error": "<veateade>"
}

kus:

• ISO 8601 kuupäev on ajatempel kujul 2018-04-28, millele võib järgneda kellaaja osa
• klientrakenduse nimi on TARA-s registreeritud klientrakenduse nimi
• autentimismeetod peab olema vastavalt TARA tehnilises kirjelduses määratule.
• panga kood on pangalingiga autentimise puhul panga lühinimetus (läbivalt suurte tähtedega)
• sündmuse koodnimetus peab olema vastavalt TARA kasutusstatistika spetsifikatsioonile:
  • START_AUTH - autentimine alanud
  • SUCCESSFUL_AUTH - autentimise edukas lõpp
  • ERROR - autentimise ebaedukas lõpp
• veateade lisatakse ainult siis, kui see päringus saadeti (operation väärtus ERROR).

1.3 Statistika väljastamise otspunkt

Statistika väljastamise otspunkti e statistikakasutaja UI kaudu saab kasutaja tutvuda TARA kasutusstatistikaga.

• avada sirvikus leht https://<tara-stat>/stat:<tara-stat-https-port>
• määrata periood (võib jääda ka tühjaks)
  • sisestades regulaaravaldise
  • nt 2018-04 valib 2018. a aprilli logikirjed
• vajutada nupule
• kuvatakse autentimiste arv perioodi jooksul klientrakenduste lõikes.

Samas saab ka aegunud logikirjeid kustutada. See toimub perioodi etteandmisega. Enne kustutamist küsitakse kinnitust. Selline kustutamine on otstarbekas, kuna tõendusväärtus ega pikaajalisem säilitamine pole kasutusstatistika logi puhul eesmärk.

1.4 Võtmed ja salasõnad

TARA-Stat paigaldamiseks ja käitamiseks on vaja järgmisi võtmeid ja salasõnu (saladusi):

Statistikakasutaja on TARA-Stat-i suhtes anonüümne inimene. Ta pöördub sisevõrgust TARA-Stat veebirakenduse statistika väljastamise otspunkti poole. Statistikakasutajat ei autendita, juurdepääs piiratakse kontekstiga.

1.5 Olulised asukohad

Kaustastruktuur

/opt/tara-stat        
              /tara-stat          -- TARA-Stat rakendus
                        index.js  -- TARA-Stat veebirakendus       
              /config/
                      /config.js  -- TARA-Stat konf-ifail
                      /keys       -- kaust TARA-Stat võtmete ja
                                     sertide hoidmiseks

• https://github.com/e-gov/TARA-Stat – avalik koodirepo
• ` index.js` - veebirakendus (peaprogramm)
• ` scripts` - paigaldusskriptid

• ` docs` - avalik dokumentatsioon

• /opt/tara-stat/tara-stat/log.txt – TARA-Stat veebirakenduse logi

• /lib/systemd/system/tarastat.service – TARA-Stat veebirakenduse systemd haldusüksuse kirjeldusfail

• /etc/mongod.conf – MongoDB konf-ifail
• /var/log/mongodb/mongod.log – MongoDB logi
• var/lib/mongodb – MongoDB andmebaasifailid
• /lib/systemd/system/mongod.service – MongoDB systemd haldusüksuse kirjeldusfail

1.6 Sõltuvused

Tootmissõltuvused:

Arendussõltuvused:

Märkus. “Standardne” tähendab laialt kasutatavat, stabiilset teeki, millest npm abil paigaldatakse viimane versioon. Kui versioon on tühi, siis kasutatakse standardseid võimalusi, mis ei nõua sidumist konkreetse versiooniga.

1.7 Konfigureerimine (ülevaade)

Konfigureeritakse järgmiste failidega:

TARA-Stat konfiguratsiooni hoitakse eraldi, mitteavalikus repos.

2 Paigaldamine ja seadistamine

2.1 Ülevaade

TARA-Stat paigaldatakse ühes instantsis, ühte masinasse. Kõrgkäideldavus ei ole TARA-Stat praeguses teostuses eesmärk. Tõrke korral tekib küll statistikas auk, kuid ärivajaduse rahuldamiseks on aktsepteeritav ka mõneti lünklik statistika.

Paigalduse üldine käik:

• masina ettevalmistamine > virtuaalmasin on loodud; Ubuntu 16 LTS on paigaldatud
• paigalda koodirepo (või uuenda seda)
• paigalda Node.js
• paigalda MongoDB
• paigalda konf-ifail ja seadista
• paigalda võtmed
• käivita rakendus

Täpsem teave ei ole avalik.

2.2 Juurdepääsude avamine

Vaja on tagada:

• TARA-Server-lt tulevate TCP TLS päringute teenindamine
• statistikakasutajalt (pöördub sirvikuga) tulevate HTTPS päringute (sh AJAX) teenindamine
• monitooringulahenduselt (kui kasutatakse) tulevate HTTPS päringute teenindamine.

TARA-Stat kuulab HTTPS ühendusi pordil ja Syslog TCP ühendusi pordil . Need pordid on määratud failis `config.js`.

2.3 Käivitamine ja seiskamine

Nii TARA-Stat veebirakendus kui ka MongoDB käitatakse systemd hallatavate teenustena. Teenused käivitatakse ja seisatakse standardsete systemctl käskudega, nt:

sudo systemctl start mongod (käivita teenus mongod)

sudo systemctl stop tarastat (peata teenus tarastat)

Teenuste tarastat ja mongod käivitamise järjekord ei ole oluline. Kuid peab arvestama, et tarastat sõltub mongod-st - kui logibaas ei ole üleval, siis ei saa logikirjeid salvestada ega statistikat väljastada.

2.4 Monitooringuga ühendamine

Päringu https://<tara-stat>/status saamisel kontrollib TARA-Stat oma logibaasi ülevalolekut. Kui logibaas on üleval, siis tagastatakse HTTP vastus 200 OK, vastasel korral 500 Internal Server Error.

2.5 Diagnostika

TARA-Stat ülevalolekut saab lõppkasutaja seisukohast kontrollida nii:

• lülitu tööarvutiga organisatsiooni sisevõrku (VPN)
• sirvikus ava https://<tara-stat>:<tara-stat-https-port>.

Märkus. Kui rakendus peaks teatama, et ühendus ei ole turvaline, siis see on tingitud self-signed serdist. Aktsepteeri turvaerind. Ilmub rakenduse avaleht. Kui paigaldatud on organisatsiooni CA poolt väljaantud sert, siis teadet ei tule.

TARA-Stat masinas saab teenuste tarastat ja mongod ülalolekut kontrollida:

systemctl status tarastat (kuva teenuse tarastat staatus)

systemctl status mongod (kuva teenuse mongod staatus)

Probleemide lahendamiseks saab kasutada teenuse enda logisid (vt jaotis “Olulised asukohad”):

sudo journalctl -u tarastat (tarastat koondlogi vaatamine vahendiga journalctl)

tail /opt/tara-stat/tara-stat/log.txt – TARA-Stat veebirakenduse logi

tail /var/log/mongodb/mongod.log (andmebaasisüsteemi logi)

2.6 Logibaasi haldamine

Kui tekib vajadus välja selgitada, mis seisus on MongoDB andmebaasi sisu või või logibaasi tühjendada, siis tee järgmist:

mongo -u andmehaldur -p changeit -authenticationDatabase users; (ava MongoDB käsureavahend, logides sisse kasutajaga andmehaldur)

(kui autentimine pole sisse lülitatud, siis lihtsalt mongo)

use logibaas (lülitu logibaasile)

show collections (peab näitama: autentimised)

db.autentimised.count() (kuva kirjete arv logibaasis)

db.autentimised.find().sort({_id:1}).limit(5); (kuva 5 viimast kirjet)

db.autentimised.remove({}) (tühjenda logibaas)

exit (välju CLI-st)

Andmebaasi kasutajate haldamiseks tuleb käsureavahendisse sisse logida administraatorina:

mongo -u userAdmin -p changeit -authenticationDatabase admin (ava MongoDB käsureavahend, logides sisse kasutajaga userAdmin)

show dbs (kuva andmebaasid. Loetelus peab olema admin ja logibaas)

use admin (lülitu andmebaasile admin)

show users (kuva kasutajakontod valitud andmebaasis; peab näitama kasutajat admin)

use users (lülitus andmebaasile users)

show users (kuva kasutajakontod andmebaasis users; peab näitama kasutajaid andmehaldur ja rakendus)

db.auth("andmehaldur", "changeit") (logi sisse andmehaldurina)

Vaata lisaks:

• mongo
• mongo Shell Quick Reference

3 Kasutamine

TARA-Stat kasutajaliides on avatud ainult asutuse töötajatele.

Sirvikus ava https://<tara-stat>:<tara-stat-https-port>.

4 Testimine

Testimisvahendeid toodangus ei kasutata. Neid võib repo sisuga koos tootmismasinasse kopeerida, kuid neid ei ole vaja (ega tohigi) skriptidega ega muul viisil aktiveerida.

4.1 Logikirjete lisamise testrakendus

LogikirjeteSaatmiseTest.js on lihtne Node.js rakendus, mis etendab logikirjeid TARA-Stat logibaasi saatvat TARA-Server-it.

Testrakendus kasutab TARA-Stat konf-ifaili config.js ja võtmeid.

Testrakenduse võib käivitada TARA-Stat-ga samas masinas.

Soovi korral võib testrakenduse paigaldada eraldi masinasse. Selleks tuleb täita kõik ülalkirjeldatud paigaldussammud, v.a MongoDB paigaldamine.

Testrakenduse käivitamiseks sisesta:

cd /opt/tara-stat/tara-stat/TEST
nodejs LogikirjeteSaatmiseTest

Iga käivitamisega genereeritakse juhuslikult teatud arv logikirjeid ja saadetakse TARA-Stat logibaasi.

5 Turvamine

TARA-Stat-is on rakendatud järgmised turvavalikud.

5.1 Juurdepääsu kaitse

1. TARA-Stat paigaldatakse eraldi VM-i. VM-is ei ole teisi rakendusi.
2. TARA-Stat on ligipääsetav ainult organisatsiooni sisevõrgus.
3. Logikirje lisamise otspunkt (Syslog TCP ühendus) on kaitstud kahepoolselt iseallkirjastatud (self-signed) sertidega.
4. Statistika väljastamise otspunkt API võtmega kaitset ei vaja, kuid on ligipääsetav ainult organisatsiooni sisevõrgus.
5. Elutukse otspunkt on ligipääsetav ainult organisatsiooni sisevõrgus.
6. Veebirakendus pöördub MongoDB poole eraldi andmebaasikasutajana (rakendus). Andmebaasikasutaja autenditakse. Kasutusel on MongoDB vaikimisi autentimismehhanism - soolaga salasõna põhine.
7. Admin on eraldi andmebaasikasutaja.
8. Nii veebirakendus kui ka MongoDB käitatakse eraldi, spetsiaalsete kasutajate alt (tarastat ja mongod).
9. Ligipääs andmebaasile (kirjutamine) on kaitstud ka failisüsteemi õiguste tasemel.
10. Andmebaas ei ole nähtav VM-st väljapoole. Andmebaasi kasutab ainult samas masinas asuv veebirakendus.

5.2 Transpordi kaitse

1. Veebirakenduse API-s on kasutusel ainult HTTPS.
2. Veebirakenduse ja MongoDB suhtluses ei rakendata TLS-i. Kuna andmebaas suhtleb ainult samas masinas oleva rakendusega ja masinas ei ole teisi rakendusi, ei ole TLS-i hädavajalik.

5.3 Sisendi puhastamine

Kaitse on rakendatud ohuvektorile: rakenduse kokkujooksmine vales vormingus andmete saatmisel logikirjete vastuvõtmise otspunkti (puhvri ületäitumine eraldajateta kirjete puhul; viga JSON-kirje parsimisel).

5.4 Andmebaasi kaitse

1. Andmebaasi ei krüpteerita, kuna konfidentsiaalsusvajadus ei ole kõrge.
2. Andmebaasi auditilogi ei peeta, kuna terviklusvajadus ei ole nii kõrge.

Vajadusel vt taustaks:

• MongoDB turvakäsitlus sisaldab turvameelespead rea soovitustega.

6 Käideldavus

TARA-Stat-i võib logikirjeid saata mitu TARA-Serveri instantsi.

TARA-Stat ise ei ole mõeldud mitmes instantsis paigaldamiseks. Mitmes instantsis paigaldamine oleks küll võimalik, kuid kasutusstatistika koguneks siis instantside kaupa.

LISA 1 Veateated

Sirviku teated:

Veebirakenduse veateated: