Open API štandardy

1

FYI: Budúci týždeň v utorok (31.10.2017) bude na ÚPVII zasadať pracovná skupina PS1 pre štandardy, kde je na programe (okrem iného) prezentácia návrhu Open API (diskusia a pripomienkovanie). Tiež sa tam bude riešiť štandardizovaný spôsob a obsah zverejňovaných datasetov (diskusia a schválenie).

Téma Open API je na programe dňa na podnet úlohy Akčného plánu Open Government Partnership (podobne ako štandardizovaný spôsob a obsah zverejňovaných datasetov). Ak chcete participovať, môžete sa zapojiť cez Platformu, @jsuchal (ktorý k Open API draftuje veci) podnety zváži / zapracuje.

CC: @lubor @hanecak @Ivet_Fercikova

1 Like
2

nieco sa uz diskutovalo tu "OpenAPI" ITMS2014+

3

Referencie, skor pre ostanych (kedze su aj od Jana):

4

Chcel by som upozornit, ze open data api je trosku nieco ine. Koncept Open API je toto: “sposob ako tretej strane umoznit pristupit k API v mojom mene”

Technicky sa to v praxi riesi nasledovne:

  • OAuth - velmi rozsireny “standard”. Je vsak pomerne volny voci implementatorom.
  • OpenID Connect (nemylit si s OpenID, to je nieco ine) - nadstavba nad OAuth, komplikovanejsie, moznost certifikacie (aj self certifikacie), jasne definovane ako sa robia scopes, endpointy,…
  • SOAP/WS + STS a OnBehalfOf token. (takto nejako to napriklad do buducna planuju aj v NASES pri pristupe k schranke)
1 Like
5

OK, terminologicke okienko:

  • Open Data API: jeden zo spôsobov, ako poskytovať otvorené údaje (druhým je poskytovanie cez súbory); je to API, ale zvyčajne anonymné a len na čítanie (read-only)
  • Open API: spôsob, ako využiť elektronické služby verejnej správy inak než “ručne” cez webové rozhranie; je to neanonymné API (vyžaduje prihlásenie) a umožňuje aj zápis; príbuzný buzzword: G2C

(vid https://utopia.sk/wiki/display/opendata/OpenData.sk+Meetup+%2311#OpenData.skMeetup#11-JánSuchal:GovBox )

Beriem to tak, ze tento thread a aj nadchadzajuce stretnutie PS bude o “Open API” v zmysle vyssie uvedeneho. Tot aj IIRC scope ulohy B.12 (Trello , aj ked teda zial v zneni neprezil retazec “Open API”) ci priority “Open API” v NKIVS (Trello). @jangondol, prosim skoriguj, ak sme uleteli.

6

Ano. Prehladnosti vobec nepridava fakt, ze medzicasom vznikla nejaka OpenAPI specifikacia https://www.openapis.org/, ktora len popisuje ako ma vyzerat nejake “nove-WSDL” pre REST APIs.

2 Likes
7

Skusim spisat moju definiciu OpenAPI skombinovanu s odpovedami tu + aj s constrainami, ktore si myslim ze by mali byt definovane. Bolo by super ak by sme do pondelka vecera dospeli k nejakemu ucelenemu textu so vsetkymi potrebnymi nalezitostami. Nasledne to viem hodit aj na Confluence pracovnej skupiny PS1 aby si to aj ostatni clenovia mohli pozriet.

OpenAPI

  • reprezentuje elektronickej služby verejnej správy prístupné verejnosti

  • elektronické služby sú určené ako na čítanie, no zároveň môžu byť použité aj na editáciu/tvorbu údajov

  • použitie služby je podmienené prihlásením

  • služba musí byť zaregistrovaná v Metainformačnom systéme, kde sa nachádza

    • minimálne štruktúrovaná API dokumentácia :
      • v pripade REST služby je štruktúrovane zdokumentovaná prostredníctvom OpenAPI 3.0
      • v prípade SOAP služby je štruktúrovane zdokumentovaná prostredníctvom WSDL + XSD
    • popis metadát služby na úrovni metadát je v súlade s CSPV-AP štandardom EU (kto je gestorom, endpoint, odkedy služba je zaregistrovaná)

  • ak dátový prvok používaný na rozhraní služby má mapovanie na prvok v Centrálnom modely údajov, tak je tento vzťah zapísaný štruktúrovane v dokumentácii

  • prístup môže byť riadený prostredníctvom technického komponentu API Gateway

  • ak existujú referenčné URI identifikátory pre entity v službách, je vyžadované ich použitie

4 Likes
8

Ja by som este doplnil:

  • API GW podla schvalenej Strategickej priority: Integracia a Orchestracia povinne (nebojte sa, SPOF sa da riesit)
  • Proces udelenia oprávnenia tretej strane koncovým používateľom - mozeme sa inspirovat ako to spravili banky v ramci PSD2
  • Overovanie oprávnení tretích strán pri komunikácii s Open API - tzn. ked mi pride request, ako zistim, ze ta tretia strana je opravnena prave na tuto sluzbu, prave pre tohto klienta a ci to bude zistene uz hned na vstupe (API GW) alebo az ked to pritecie do agendy nebodaj az asynchronne :wink: - opat tema central vs. decentral
  • Ako vybudovat SandBox pre prototyping tretich stran
  • API portal napr. na baze apiary.io, ktory je previazany s Meta IS (meta IS - meta udaje, API portal - integracny manual (detail))
  • Ako prinutit povinne publikovat udaje do SandBoxu a kontinualne udrziavat API portal v tomto nasom prostredi…

Asi takto zatial.

9

Nie nutne, teda v komercnom svete je bezne, ze davas aj offline pristup. Napriklad, ze ti niekto chodi kukat do schranky aj ked mu vzdy nedavas znova novy token.

Zvysok by som suhlasil.

Neviem nakolko riesi standardizacia aj procesy, lebo tam vidim velke prekazky. Technikalie ci to bude soap/rest taky ci onaky je “open data vs. ontologie” diskusia v ruzovom - je mi to takmer jedno, hlavne nech to vieme co najskor a rozumne pouzivat. Vsetko navyse je plus.

Toho sa az tak nebojim. Len sa bojim ze to nebude stat tolko co amazon API Management - Amazon API Gateway - AWS alebo Kong https://getkong.org/ :slight_smile:

Mas priklad? Lebo tuto je google oauth playground OAuth 2.0 Playground pripadne openid connect OpenID Connect  |  Authentication  |  Google for Developers - teraz neviem ci myslis vizualne alebo technicky.

Pri STS napriklad na UPVS sluzbach (s plnou vaznostou to sem davam ako pekny priklad :slight_smile: ) je to jasne, token ktory dostanes vies overit, ze ide od STS sluzby (je podpisany), vidis na co bol vydany (endpointy) a vidis onbehalfof (za koho). Toto sa riesi teda na strane vydavania tokenu. Nasledne samotne agendove pristupove prava riesis u seba - to aj tak asi nema zmysel posuvat inam lebo to bude najskor naviazane aj na biznis logiku ktoru vytrhavat z agendy je blbost (vid formulare). – TODO: treba overit ako funguje pri openidconnect/oauth.

Opat je prikladom UPVS - dev prostredie je vystavene do internetu. :+1: Co by mu vsak pomohlo su nejake dummy data na vsetky endpointy (ktore netreba pytat od sluzby), lahsie ziskanie pristupu, kvalitnejsia dokumentacia na webe a nech sa tam da vyhladavat. word dokumenty na “FTP” fakt nie su nic moc.

Podla mna je jedina cesta velmi neoddelovat od seba ani dev infrasturkturu ani dokumentaciu pre public a G2G cast. Akonahle sa to stane, tak public cast nebude “first-class citizen”.

2 Likes
10

Ake konkretne mas namysli? Nevidim problem aby tam boli definovane aj procesy. Kazdopadne toto je trochu specificka zalezitost, lebo je to aj zadanie z OGP a nachadza sa to aj v N roznych strategickych dokumentoch a tym padom sa podla mna so scope zadania da adekvatne hybat a rozsirovat tak “aby dobre bolo” a bolo jednotne miesto kde je to popisane.

Co takto pravidlo, ze poziadavky na Quality of Service a pri support a SLA nesmie byt rozdiel medzi G2G a OpenAPI sluzbami tj. ked si nejake OVM bude podpisovat zmluvu tak nemoze mat specialne podmienky pre rozne druhy sluzieb? Alebo definovat nejaku garanciu dostupnosti, ktora musi byt v systemoch vzdy deklarovana a zabezpecena?

11

Z casti aj to co pisal @ret hore a z casti to co som zazil. Neumerne kila integracnej dokumentacie, budovanie vseliakych ipsec tunelov, integracne testovanie (stale nechapem preco to ako konzument potrebujem robit a dokladovat NASESU), atd atd. Kopec detailikov co ta zabiju.

Pikoska pod ciarou. Napriklad nases na hromadnu registraciu splnomocneni na pristup do schranky ma proces. Treba poslat excel, splnocnenia (skeny), public kluce/certy v jasnej strukture a mailom. No a co cert nechcel hromadna registracia zakapava na tom, ze nasesu sa neda do emailu poslat vacsi email ako par MB. Cize im to tam musime posielat po kuskoch.

12

Keďže sa teraz riešia štandardy, pri takej veci ako “tretia strana pristupuje k API v mojom mene”, by malo existovať povinné logovanie, aby som si mohol ex post pozrieť, kto kam v tom mojom mene pristupoval… Mal by takýto audit trail štandard obsahovať? (IMHO áno, ale môžete ma skúsiť presvedčiť o opaku…)

Pred pár rokmi som v Estónsku videl demo, kde nám chlapík ukazoval, kedy si kto pozeral jeho vodičák a ktorý lekár kedy pristupoval do jeho zdravotnej dokumentácie (toto je niečo trošku iné ako Open API, ale páčil by sa mi princíp, kedy by som si vedel pozrieť, ktorá appka kam v mojom mene pristupovala a ak má appka stále autorizáciu, tak by som bol rád, aby existovala možnosť túto autorizáciu user-friendly spôsobom revokovať).

1 Like
13

Z mojho pohladu je toto akesi rozsirenie sluzby moje data kde sa taketo nieco planuje. Myslim, ze aj GDPR nieco take vynucuje.

1 Like
14

Pri službe moje dáta (organizácia pristupuje k mojim dátam vo svojom mene) je to vlastne ten príklad ako v Estónsku. Malo by byť takéto logovanie aj pri Open API (third-party appka pristupuje k API v mojom mene)? Celkom mi to dáva zmysel…

15
  1. No myslim aj vizual ale aj technicky. Ci budeme mat jednu gov branu kde pouzivatela presmerujem z tretej strany a kde to autorizuje (klient-tretia strana-sluzaba) a to sa vypropaguje do modulu co vydava tokeny.
  2. V pripade ouath based token informacia o opravneni necestuje s tokenom. Ked prijmes spravu (napr. Api gw) tak overis platnost tokenu a jeho scope volanim overovacej sluzby modulu, ktory ho vydal
16

Ci bude jedna alebo 10 neviem. Mne dava zmysel 1, kedze si nechcem robit konta kadetade a tam to sledovat. Extremisticky pohlad by bolo mat moje data naozaj len u seba :). Aj take sa da. Vlastne ved openid malo povodnu myslienku niekde tam, ze mozes si providera urobit aj kazdy sam.

Toto sa mi paci viac v tom STS WS svete, kde ten token proste mas a uz ho nemusis nijako centralne online overovat nikde. Je podpisany, plati (casova expiracia) a hotovo. Cize koncove APIs nepotrebuju riesit overovanie voci nicomu.

Toto podla vsetkeho sa da aj s OAuth ked pouzijes JWT token, kedze ten je aj podpisany. Za mna win-win.

Toto je decentralizovany scenar, ale v principe to moze robit rovnako jeden centralny api-gw komponent. Cize akokolvek to dopadne voci APIs to je takmer rovnake, pre konzumenta uplne rovnake.

17

Tu je pekna ukazka ako by to mohlo ficat. https://openidconnect.net/ v principe na konci dostanes JWT token ktory vies overit, ze neni podvrh. Overis to na strane API uplne offline (len checknes signature). A pustis cloveka do svojho API (za dalsich podmienok, je tam spravny scope, ma na to prava, etc).

18

No ak forma JWT tak naozaj to overenie robit iba na API GW, aby sme nezatazovali s touto funkcionalitou agendove sluzby…

Takze uz ina zostava zapisat to nastavene opravnenie do autorizacneho servra a upratat fyzicke end-pointy API katalog.

19

Tu je priklad co treba robit na strane API keby si teda nahodou to chcel robit aj u seba. https://auth0.com/docs/tokens/access-token#authorize-access-tokens Lahke.

20

V principe to moze by na dvoch urovniach. Predstavujem si, ze to bude takto:

  1. Niekde na third party, ktora potrebuje napriklad za teba pristupit do schranky (volajme tento scope read_ebox - kliknes na button - Connect
  2. Si presmerovany na consent screen (pripadne login predtym)
  3. Prebehne vymena komunikacie a na jej konci mas u seba v third party JWT access token, ktory vyzera takto:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS5nb3Yuc2svIiwic3ViIjoianN1Y2hhbHwxMjM0NSIsImF1ZCI6Imh0dHBzOi8vYXBpLnNjaHJhbmthLnNsb3ZlbnNrby5zay8iLCJzY29wZXMiOiJyZWFkX2Vib3giLCJpYXQiOjE1MDg5NzAxMDEsImV4cCI6MTUwOTAwNjEwMX0.fZ2CG4U9TxsR8_PAb-xcogmvYTUqnwnqcBnUr8muy1xY90BuCPC3SlVbfAkkyTNq1c-Ny_nPNTrMra-sRkLQLpOQt4V-mSV0xqsgJ9nAgY0S7XpcxBbtce3scUtej8hEzFHhfOB3cbbyN1Ozq5YYgCJgHxWOOvbV908nTz26CZw

Toto viem pouzivat ako bearer token na volania APIs. Ked ho dekodujem tak vyzera takto

{
  "iss": "https://api.gov.sk/",
  "sub": "jsuchal|12345",
  "aud": "https://api.schranka.slovensko.sk/",
  "scopes": "read_ebox",
  "iat": 1508970101,
  "exp": 1509006101
}

Pouziva sa tam PKI a teda som ho podpisal na strane token issuera privatnym klucom, na strane api to viem overit public klucom. Vlozte toto do toho toolu vyssie na miesto public key a bude to validne.

-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugdUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQsHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5Do2kQ+X5xK9cipRgEKwIDAQAB
-----END PUBLIC KEY-----

Na strane API teda viem cez public kluc ktoremu verim overit, ze to neni podvrh, viem si to otvorit a precitat ci tam je spravny scope, ktory povoluje nejaku operaciu za nejakeho usera + je tam identifikator usera (co toto bude si nechajme snivat).

Za mna takto ideal.

1 Like