/
Autentimine ja autoriseerimine

Autentimine ja autoriseerimine

Ülevaade

Kui volitusi omav majandustarkvara kasutaja soovib oma andmeid andmesilla vahendusel esitada, siis on vajalik algatada liidestatud tarkvara poolel isiku tuvastamise ja volituste kontrollimise protsess. Selleks on andmesilla poolel arendatud eraldi teenus, kuhu tuleks tarkvarast kasutaja suunata.

Peale isiku volituste kontrolli, on võimalik tarkvarasüsteemil pärida M2M ligipääs ning kogu edasine suhtlus andmesillaga käib M2M liidese kaudu kasutades OAuth Client Credentials skeemi.

Käesolev juhend kirjeldab, kuidas tarkvaraarendajad saavad integreerida oma süsteemi meie andmesilla API-ga, kasutades OAuth 2.0 autoriseerimiskoodi voogu (Authorization Code Flow) ja klientide autentimist Client Credentials Flow kaudu. PKCE (Proof Key for Code Exchange) on kohustuslik ja peab olema toetatud.

Ametlik spetsifikatsioon: OAuth 2.0 Authorization Code Flow

Eeltingimused

Enne integratsiooni alustamist peavad olema täidetud järgmised tingimused:

  • Tarkvaras peab olema arendatud ja valmis töötav redirect_uri endpoint, kuhu kasutaja suunatakse pärast edukat autentimist.

  • redirect_uri peab olema RIK-iga eelnevalt kokku lepitud ja edastatud.

  • Süsteem peab kasutama RIK-i poolt väljastatud avaliku client_id, mida kasutatakse kasutajate suunamiseks isikutuvastamise protsessi.

  • Süsteem peab toetama PKCE (Proof Key for Code Exchange) mehhanismi autoriseerimiskoodi kasutajavoo turvalisemaks muutmiseks.

1. Autoriseerimiskoodi hankimine

Esimene samm on suunata kasutaja autoriseerimislehele, kus tuleb isikul teostada isikutuvastuse protsess.

Päring:

GET /api/v1/auth/code-flow ?client_id=<TARKVARA_CLIENT_ID> &response_type=code &scope=datahub_connect &redirect_uri=<TEIE_REDIRECT_URI> &state=<UNIKAALNE_STATE> &code_challenge=<PKCE_KOOD> &code_challenge_method=S256 HTTP/1.1 Host: datahub.rik.sise

Parameetrid:

  • client_id – Teie tarkvarasüsteemi kliendi ID. Näiteks “earveldaja”.

  • response_type – Peab olema code.

  • scope – Peab olema datahub_connect.

  • redirect_uri – URL, kuhu kasutaja suunatakse pärast autentimist.

  • state – Unikaalne juhuslik string CSRF rünnakute vältimiseks.

  • code_challenge – PKCE kood, genereeritud SHA-256 hash'i põhjal.

  • code_challenge_method – Peab olema S256.

PKCE koodi genereerimise näide Pythonis:

import base64 import hashlib import os def generate_pkce(): code_verifier = base64.urlsafe_b64encode(os.urandom(40)).rstrip(b'=') code_challenge = base64.urlsafe_b64encode( hashlib.sha256(code_verifier).digest() ).rstrip(b'=') return code_verifier.decode(), code_challenge.decode() verifier, challenge = generate_pkce() print(f"Code Verifier: {verifier}\nCode Challenge: {challenge}")

2. Redirect URI endpoint

Tarkvarasüsteemis peab olema loodud redirect_uri endpoint, kuhu kasutaja suunatakse pärast autentimist. Antud endpoint tuleb meie poolt lisada whitelisti ning siduda tarkvarapõhise client_id-ga. See endpoint peab võtma vastu OAuth standardi järgi nõutud päringu parameetreid.

Päring, mida teie süsteemi redirect_uri vastu võtab:

GET <TEIE_REDIRECT_URI>?code=<AUTORISEERIMISKOOD>&state=<STATE>

Redirect URI võib olla veebiteenuse URI, kuid on lubatud standardi järgi ka localhost/127.0.0.1.

Parameetrid:

  • code – Authorization Code Flow autoriseerimiskood, mida kasutatakse järgmises etapis juurdepääsuloa hankimiseks.

  • state – Algse päringuga saadetud state väärtus, et vältida CSRF rünnakuid.

Teie süsteem peab kontrollima state väärtuse õigsust ning seejärel vahetama autoriseerimiskoodi “access tokeni” vastu.

3. Autoriseerimiskoodi vahetamine juurdepääsuloa vastu

Kui kasutaja on autentimise lõpetanud, suunatakse ta tagasi redirect_uri-le, mille päringu parameetrite hulgas on ka code. Selle koodiga tuleb teha järgmine päring:

Päring:

POST /api/v1/auth/token HTTP/1.1 Host: datahub.rik.sise Content-Type: application/x-www-form-urlencoded client_id=<TARKVARA_CLIENT_ID> &grant_type=authorization_code &code=<SAADUD_AUTH_KOOD> &redirect_uri=<TEIE_REDIRECT_URI> &code_verifier=<PKCE_VERIFIER>

4. Kliendi autentimisandmete hankimine

Pärast kasutaja autentimist tuleb süsteemile hankida unikaalne client_id ja client_secret, et andmesilla API-d kasutada taustal edasi Client Credentials vooga. Unikaalseid client_id ligipääse võib hankida vajadusel mitmeid tarkvara kohta. Tegemist on mitte isikustatud ligipääsuga, mida on võimalik tarkvara sees näiteks erinevate kasutajate vahel jagada. See tagab olukorra, et kõik tarkvarakasutajad ei pea ennast igakord TARA keskkonnas autentima, kuna volitatud isik on eelnevalt nende kasutajate jaoks ligipääsu juba loonud. Ehk siis tegemist on masin-masin tüüpi ligipääsuga majandustarkvara kliendi tarkvara instantsi ja andmesilla vahel.

Päring:

POST /api/v1/auth/client-credentials HTTP/1.1 Host: datahub.rik.sise Content-Type: application/json Authorization: Bearer <VOLITATUD_KASUTAJA_ACCESS_TOKEN> Represented-Party: 12345678 { "public_client_id": "majandustarkvara1", "creator_national_id": "EE39901012239", "creator_name": "Eesnimi Perekonnanimi", "contact_email": "kasutaja@example.com" }

Vastus:

{ "client_id": "system_12345", "client_secret": "secret_abcdef", "is_activated": false, "valid_until": "2026-02-10T00:00:00Z", "message": "new_agreement_created" }

Tagastatud client_id ja client_secret tuleb tarkvara poolel turvaliselt hoida. Tagastatud ligipääsu andmed aga ei ole koheselt aktiveeritud millele viitab andmeväli is_activated. Et tagastatud ligipääsuandmeid aktiveerida, on vajalik teha täiendavalt nendega /api/v1/auth/token päring. Kui täiendavat päringut ei tehta, siis ligipääsuandmed aeguvad 15 minuti pärast.

Päring:

POST /api/v1/auth/token HTTP/1.1 Host: datahub.rik.sise Content-Type: application/x-www-form-urlencoded client_id=system_12345& client_secret=secret_abcdef& grant_type=client_credentials

Vastus:

{ "access_token": "eyJhbGciOiJS...", "expires_in": 300, "refresh_expires_in": 0, "token_type": "Bearer", "not-before-policy": 0, "scope": "email profile datahub_connect" }

Peale ülaltoodud päringut on client_id “system_1234” aktiveeritud. Endpoindi /api/v1/auth/token päringu vastuses tagastatud access_token väärtusega on võimalik aruandlusega seotud andmeid edastama hakata. Päringu vastuses välja toodud väli expires_in näitab, et ajutine ligipääsu access_token kehtib 300 sekundit, ehk siis 5 minutit. See tähendab, et peale 5 minutit on vajalik uus päring teha. Näiteks on lahendusi, kus enne igat /api/v1/ledger/submission väljakutsumist tehakse /api/v1/auth/token päring uuesti, et saada kehtiv access_token.

5. Andmete saatmine API-sse

Kui autentimine on edukalt lõpule viidud, saab süsteem esitada andmeid meie API kaudu kasutades Client Credentials voogu. Siin isikupõhist access_token-it enam kasutada ei tohi. Ehk siis tuleb kasutusele võtta eelmises sammus client_id-iga: system_12345 tagastatud access_token.

Päring:

POST /api/v1/ledger/submissions HTTP/1.1 Host: datahub.rik.sise Authorization: Bearer eyJhbGciOiJS... Represented-Party: 12345678 Content-length: 1234 Content-Type: multipart/form-data; boundary=---------------------------1234 ---------------------------1234 Content-Disposition: form-data; name="report_code" ANNUAL-ACCOUNTS-MICRO ---------------------------1234 Content-Disposition: form-data; name="ledger_file"; filename="mees-ja-koer-oy1.xml" Content-Type: text/xml; charset=UTF-8 <<<file content>> ---------------------------1234

Kokkuvõte

  1. Kasutaja suunatakse autoriseerimislehele OAuth 2.0 autoriseerimiskoodi voo kaudu.

  2. Kasutaja suunatakse tagasi teie süsteemi redirect_uri-le, mis töötleb vastuse.

  3. Pärast autentimist vahetatakse autoriseerimiskood juurdepääsuloa vastu.

  4. Süsteem hangib enda jaoks unikaalse client_id ja client_secret.

  5. API-päringute tegemiseks kasutatakse OAuth Client Credentials voogu.

  6. Andmeid saab esitada API kaudu, kasutades Client Credentials põhist juurdepääsuluba.

Autentimise ja autoriseerimise skeemid