OAuth2.0 autorizācijas API

OAuth 2.0 autorizācijas modelis ļauj pakalpojuma sniedzēja lietojumprogrammai iegūt piekļuvi HTTP pakalpojumam vai resursam tā galalietotāja vārdā, kuram pieder resurss, vai pašas pakalpojuma sniedzēja lietojumprogrammas vārdā. Lai to izdarītu, Pakalpojumu sniedzēja lietojumprogramma iegūst piekļuves marķieri, veicot šādas darbības:

1. API autorizācijas koda pieprasījums.
2. API piekļuves marķiera pieprasījums.

Iegūstiet autorizācijas kodu

Šī darbība ietver autorizācijas koda piešķiršanas tipa OAuth 2.0 pieprasījuma izpildi. Atšķirībā no citām integrācijas platformas API (izņemot SignAPI), šīs operācijas ziņojumi netiek apmainīti tieši starp pakalpojuma sniedzēja lietotni un integrācijas platformu, bet gan netieši, izmantojot gala lietotāja pārlūkprogrammas pāradresācijas

Šī darbība ļauj pakalpojuma sniedzēja lietojumprogrammai iegūt atļauju no galalietotāja, lai piekļūtu kādam no viņa resursiem vai identitātes datiem. Galalietotāja autorizācija tiek iegūta, izmantojot autorizācijas koda akreditācijas datus. Autorizācijas kods tiek nosūtīts kā atbilde pārlūkprogrammā. Pakalpojuma sniedzēja lietojumprogramma apmainās ar autorizācijas kodu pret atbilstošo piekļuves marķieri, lai piekļūtu resursam.

Pieprasījums

Lai sāktu autorizācijas koda piešķiršanas plūsmu, Pakalpojumu sniedzēja lietojumprogramma novirza galalietotāja pārlūkprogrammu uz vienu no Autorizācijas servera /trustedx-authserver/oauth/ galapunktiem. Šīs novirzīšanas rezultātā pārlūkprogramma nosūta HTTP pieprasījumu, piemēram, tālāk norādīto, kas atbilst OAuth 2.0 autorizācijas pieprasījuma ziņojumam. Pieprasījums jānosūta, izmantojot TLS, un jāizmanto GET metode.

GET /trustedx-authserver/oauth/{as}?response_type=code&
             client_id=...&
             state=...&
             redirect_uri=...&
             scope=...&
             prompt=...&
             acr_values=...&
             ui_locales=...&
             sign_identity_id = ...&
             digests_summary = ...&
             digests_summary_algorithm = ...&

📘

PIEZĪME

Visām lietojumprogrammām, kas integrētas integrācijas platformas autorizācijas serverī, izmantojot pārlūkprogrammas novirzīšanu (OAuth 2.0), tas jādara, izmantojot konsekventu bāzes URL, kuram ir tāds pats DNS domēna nosaukums, tas pats ports (pēc noklusējuma 8082) un tas pats tīmekļa lietojumprogrammas nosaukums (pēc noklusējuma)., trustedx-authserver). Pārlūkprogrammām vienmēr ir jāpievienojas integrācijas platformas autorizācijas serverim, izmantojot to pašu bāzes adresi, lai identitātes sniedzējs varētu uzturēt sesijas un konsekventi lietot SSO.

Parameters

📘

Piezīme

Nejauciet HTTP sesiju , kas lietojumprogrammai ir ar pārlūkprogrammu, ar drošības kontekstu vai sesiju , ko lietojumprogramma izveido vai atjaunina, kad OAuth 2.0 plūsma ir pabeigta. HTTP sesija pastāv iepriekš no brīža, kad pārlūkprogramma piekļūst tīmekļa lietojumprogrammai, un pat tad, ja lietotājs vēl nav autentificējies. Drošības konteksts ir dati par autentificētu gala lietotāju, kurus lietotne parasti glabā HTTP sesijā, lai atcerētos, ka tieši šis gala lietotājs ir pieteicies lietotnē, izmantojot pārlūkprogrammu, un/vai OAuth piekļuves marķieri. Tāpat kā lietotne, arī TrustedX uztur HTTP sesiju ar pārlūkprogrammu un drošības kontekstu autentificētajam gala lietotājam.

Piemērs: Autorizācijas pieprasījums

Šajā piemērā parādīts OAuth 2.0 autorizācijas pieprasījuma ziņojums no portāla . Pakalpojuma sniedzēja lietojumprogramma pieprasa autorizāciju ar tvērumu urn:lvrtc:fpeil:aa autorizācijas serverim lvrtc-eips-as ar nosacījumu, ka pieteikšanās lapa tiek rādīta latviešu valodā.

GET /trustedx-authserver/oauth/lvrtc-eips-as?response_type=code&
                                   client_id=port%C4%81ls&
                                   state=1234567890&
                                   redirect_uri=https%3A%2F%2Fwww.demoapp.lv%2Foauth%2Fback&
                                   scope=urn%3Alvrtc%3Afpeil%3Aaa&
                                   prompt=login& ui_locales=lv HTTP/1.1
Host: eidas.eparaksts.lv

Piemērs: paraksta autorizācijas pieprasījums

Papildu parametri galalietotāja autentifikācijai ir jāizmanto, lai iegūtu atļauju no galalietotāja ģenerēt ciparparakstu ar servera parakstīšanas identitāti, kas ir iespējota, izmantojot paroli, kas glabājas HSM (parakstīšanas procedūrā Servera parakstīšana pārbauda jebkuru parakstāmo datu atbilstību uz parakstīšanai sniegtajiem datiem).

Ja galalietotājs jau ir autentificēts ar aktīvu SSO, galalietotājam būs jāievada tikai parakstīšanas (HSM) parole.

GET /trustedx-authserver/oauth/{as}?response_type=code&
           client_id=...&
           state=...&
           redirect_uri=...&
           scope=...&
           prompt=...&
           acr_values=...&
           ui_locales=...& 
           sign_identity_id=...&
           digests_summary_algorithm=...&
           digests_summary=...

Atbilde

Kad galalietotājs ir autentificēts (vai lietots SSO) un galalietotājs ir piešķīris autorizāciju, Pakalpojuma sniedzēja lietojumprogramma no galalietotāja pārlūkprogrammas saņem šāda veida HTTP GET pieprasījumu. Šis HTTP pieprasījums ir OAuth 2.0 autorizācijas atbilde vai OpenID Connect autentifikācijas atbilde. Pakalpojumu sniedzēja lietojumprogramma saņem šo pieprasījumu uz novirzīšanas URL, kas norādīts autorizācijas vai autentifikācijas pieprasījuma ziņojumā (pieprasījuma parametrs redirect_uri) vai reģistrētajā novirzīšanas URL.

GET {redirection_uri_path}?code={code}&state={state} HTTP/1.1
Host: {redirection_uri_host}

Kur {redirection_uri_host}{redirection_uri_path} ir novirzīšanas URI uz pakalpojumu sniedzēja lietojumprogrammu.

Iegūstiet piekļuves marķieri (access token)

Apraksts

Šī darbība iegūst OAuth 2.0 piekļuves marķieri. Šo darbību var izsaukt kā daļu no OAuth 2.0 autorizācijas koda piešķiršanas plūsmas vai izmantojot OAuth 2.0 pakalpojumu sniedzēja piekļuves datu piešķiršanas plūsmu.

Galalietotāja piekļuves marķieris

Kad tiek izmantota autorizācijas koda piešķiršanas plūsma, iegūtais piekļuves marķieris apliecina galalietotāja piešķirto autorizāciju Pakalpojuma sniedzēja lietojumprogrammai, kas veic izsaukumu, lai šī galalietotāja vārdā piekļūtu noteiktiem resursiem vai pakalpojumiem (identitātes dati, paraksta identitātes utt. .). Lai iegūtu tokenu, Pakalpojuma sniedzēja lietojumprogrammā jāuzrāda autorizācijas kods, kas iegūts Autorizācijas iegūšanas operācijā

🚧

Šāda veida piekļuves marķieris tiek izmantots, lai tiktu saņemta galalietotāja:

• Elektroniskā identitātes pārbaude;
• identitātes parakstīšana;
• eParaksts mobile saistītie parakstīšanas un autentifikācijas sertifikāti;
• PKSC#1 paraksts

Introspect piekļuves marķieri

Kad tiek izmantota Pakalpojuma sniedzēja piekļuves datu piešķiršanas plūsma, iegūtais piekļuves marķieris parāda Pakalpojuma sniedzēja lietojumprogrammas administratīvo autorizāciju, kas veic izsaukumu, lai piekļūtu noteiktiem resursiem vai pakalpojumiem (ti, bez tiešas resursa īpašnieka iejaukšanās) vai piekļuvei Pakalpojuma sniedzēja resursiem. Pakalpojumu sniedzēja pieteikums. Tokens tiek izsniegts, ja autorizācijas serveris, kas apstrādā pieprasījumu, nav saistīts ar identitātes sniedzēju. Šāda veida marķieri var izmantot, lai piekļūtu resursiem, kas nav saistīti ar galalietotājiem vai jebkura domēna galalietotāja resursiem.

Pieprasījums

Lai iegūtu marķieri, Pakalpojumu sniedzēja lietojumprogrammai ir jānosūta autorizācijas serverim, izmantojot TLS, šāds pieprasījums. Šis pieprasījums tiek nosūtīts tieši no Pakalpojumu sniedzēja lietojumprogrammas uz autorizācijas serveri un netiek nosūtīts caur pārlūkprogrammu.

POST /trustedx-authserver/oauth/{as}/token

Parametri

Content-type galvene

Content-Type: application/x-www-form-urlencoded; charset=UTF-8

HTTP POST pieprasījumā ir jāiekļauj šāds galvenais atribūts: Autorizācija – API piekļuves marķieris (access token).

Authorization: Basic <API-Key>

Pamatteksts (body)

Pieprasījuma saturs atšķiras atkarībā no OAuth 2.0 plūsmas veida, kurā tiek pieprasīts marķieris:

Saturs autorizācijas koda piešķiršanas plūsmas gadījumā (izmanto elektroniskās identitātes pārbaudes/parakstīšanas pieprasījumiem)

Saturs klienta piekļuves datu piešķiršanas plūsmas gadījumā — piekļuves marķiera pārbaude (izmanto, lai piekļūtu pakalpojumam SignAPI)

Piemērs (gala lietotāju piekļuves marķieris)

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Host: eidas-demo.eparaksts.lv
Authorization: Basic cG9ydCVDNCU4MWxzOmRybyVDNSVBMSVDNCVBQmJh
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
  
grant_type=authorization_code&
   redirect_uri=https%3A%2F%2Fwww.portals.lv%2Foauth%2Fback&
   code=4515...e0ba

Piemērs (piekļuves marķiera pārbaude)

Sekojošais piemērs parāda situāciju, kurā Pakalpojuma sniedzēja lietojumprogramma ar identifikatoru "Portal" un paroli "drošība"pārsūta pieprasījumu serverim ar identifikatoru "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic cG9ydCVDNCU4MWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
            scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Atbilde

Atbildot uz to, integrācijas platformas autorizācijas serveris izdod nesēja tipa OAuth 2.0 piekļuves marķieri un atgriež to JSON struktūrā.

{
"access_token" : {string},
"token_type" : "Bearer",
"expires_in" : {number}
}

Parametri

Piemērs

Piekļuves marķieris ar galalietotāja autentifikāciju:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
{
"access_token" : "a2b4...6daf",
"token_type" : "Bearer",
"expires_in" : 120
}

Introspect piekļuves marķieris:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}