Käyttäjähallintapalvelun REST-rajapinnat

Transkriptio

1 Käyttäjähallintapalvelun REST-rajapinnat Käyttäjähallintapalvelun REST-rajapinnat Käyttäjähallintapalvelun REST-rajapinnat Yleiset tiedot Resurssit GET /omattiedot GET /omattiedot/organisaatiohenkilo GET /omattiedot/kayttooikeus(/{organisaatio-oid}) POST /omattiedot/kayttooikeus GET /omattiedot/anomus GET /omattiedot/anomus/{anomus-id}/cancel GET /henkilo POST /henkilo GET /henkilo/henkilotypes GET /henkilo/{henkilo-oid} PUT /henkilo/{henkilo-oid} DELETE /henkilo/{henkilo-oid} GET /henkilo/identification GET /henkilo/{henkilo-oid}/identifications PUT /henkilo/{henkilo-oid}/aktivoi GET /henkilo/{henkilo-oid}/organisaatiohenkilo POST /henkilo/{henkilo-oid}/organisaatiohenkilo PUT /henkilo/{henkilo-oid}/organisaatiohenkilo GET /henkilo/{henkilo-oid}/organisaatiohenkilo/{organisaatio-oid} PUT /henkilo/{henkilo-oid}/organisaatiohenkilo/{organisaatio-oid} PUT /henkilo/{henkilo-oid}/organisaatiohenkilo/{organisaatio-oid}/kayttooikeusryhmat GET /henkilo/byhetu/{hetu} GET /henkilo/{henkilo-oid}/anomus POST /henkilo/{henkilo-oid}/yksiloi GET /henkilo/{henkilo-oid}/linked POST /henkilo/{henkilo-oid}/linked GET /henkilo/{henkilo-oid}/yksilointiview GET /henkilo/{henkilo-oid}/comparison GET /henkilo/{henkilo-oid}/overwrite GET /henkilo/{henkilo-oid}/manualoverride GET /organisaatiohenkilo/organisaatios GET /kayttooikeusryhma POST /kayttooikeusryhma GET /kayttooikeusryhma/{ryhma-id} GET /kayttooikeusryhma/{ryhma-id}/sallitut GET /kayttooikeusryhma/{ryhma-id}/kayttooikeus PUT /kayttooikeusryhma/{ryhma-id}/kayttooikeus POST /kayttooikeusryhma/kayttooikeus GET /kayttooikeusryhma/henkilo/{henkilo-oid} GET /kayttooikeusryhma/henkilo/current POST /kayttooikeusryhma/henkilo/current GET /kayttooikeusryhma/{henkilo-oid}/{organisaatio-oid} GET /kayttooikeus/{palvelunimi} GET /kayttooikeus/kayttaja/current GET /anomus POST /anomus PUT /anomus GET /anomus/{anomus-id} GET /anomus/{anomus-id}/reject GET /anomus/{anomus-id}/cancel GET /palvelu GET /kielisyys GET /kansalaisuus POST /salasana/valid POST /salasana/{henkilo-oid} POST /salasana/poletti POST /salasana/poletti/{poletti} POST /yksilointi/queryandadd

2 Yleiset tiedot Käyttäjähallintaa tulee aina käyttää REST-rajapintojen ylitse, jonka kautta voidaan käsitellä henkilöitä ja näiden käyttöoikeuksia. Pinnat tarjoavat myös mahdollisuuden ulkoiselle toimijalle tuoda järjestelmään henkilöitä. URI HTTP metodit Käyttötarkoitus /omattiedot GET, POST Kirjautuneen käyttäjän omien tietojen tarkasteluun ja muokkaamiseen /henkilo GET, POST, PUT, DELETE Henkilön tietojen hakemiseen ja käsittelyyn /organisaatiohenkilo GET, PUT Vain organisaatiohenkilön tietojen hakemiseen ja käsittelyyn /kayttooikeusryhma GET, POST, PUT Käyttöoikeusryhmien hakemiseen ja käsittelyyn /kayttooikeus GET Henkilön tai palvelun käyttöoikeuksien hakemiseen /palvelu GET Palvelujen haku /anomus GET, POST, PUT Anomusten hakuun ja käsittelyyn /kansalaisuus GET Kansalaisuutietojen hakuun /kielisyys GET Kielisyystietojen hakuun /salasana POST Salasanojen muokkamiseen ja validointiin /yksilointi POST Ulkoinen rajapinta muita oppilaitoksia ja organisaatioita varten, käytetään henkilödatan tuomiseen Resurssit Käyttäjähallinnan resurssit ovat tätä nykyä kaikki siirretty REST-rajapintojen päälle, joten vanhoja SOAP-rajapintoja ei tulisi enää käyttää. Näitä on vielä käytössä mutta mikään ulkoinen palvelu tai käyttöliittymä ei enää käytä vanhoja SOAP-rajapintoja. Kaikki kutsut ja vastausviestit käyttäjähallinnan REST-rajapintoihin liittyen käyttävät aina application/json notaatiota. GET /omattiedot Palauttaa kirjautuneen henkilön omat henkilötiedot, jossa on myös listattu henkilön yhteystiedot. GET /omattiedot/organisaatiohenkilo Palauttaa kirjautuneen henkilön organisaatiotiedot. GET /omattiedot/kayttooikeus(/{organisaatio-oid}) Hakee kirjautuneen käyttäjän käyttöoikeustiedot. Hakee kaikki tiedot tai vain tiettyyn organisaatioon liittyvät tiedot, riippuen siitä onko organisaatio -OID annettu haussa POST /omattiedot/kayttooikeus Tekee käyttöoikeuksien uudistuspyynnön valituista jo myönnetyistä käyttöoikeuksista.

3 GET /omattiedot/anomus Listaa kirjautuneen käyttäjän kaikki anomukset. GET /omattiedot/anomus/{anomus-id}/cancel Peruuttaa tehdyn anomuksen annetun anomustunnisteen perusteella. GET /henkilo Listaa henkilöitä annettujen hakuparametrien suhteen. POST /henkilo Luo uuden henkilön kutsussa annetun henkilöobjektin perusteella. GET /henkilo/henkilotypes Palauttaa mahdolliset henkilötyypit, mitä kirjautunut käyttäjä voi luoda. Tätä käytetään henkilöiden luonti-ikkunassa, jossa pitää määrittää henkilötyyppi. GET /henkilo/{henkilo-oid} Hakee kaikki henkilötiedot annetun henkilo-oid:n perusteella. PUT /henkilo/{henkilo-oid} Päivittää henkilo-oid:n täsmäävän henkilön tietoja DELETE /henkilo/{henkilo-oid} Passivoi henkilön annetun henkilo-oid:n pohjalta. Henkilöä ei pysty poistamaan mitenkään järjestelmästä. GET /henkilo/identification Hakee henkilön tiedot IdP:n ja identifier-tunnisteen avulla. GET /henkilo/{henkilo-oid}/identifications Hakee henkilön tunnistetiedot annetun OID:n perusteella. PUT /henkilo/{henkilo-oid}/aktivoi Aktivoi henkilön, jos tämä on passivoitu, annetun henkilo-oid:n perusteella. GET /henkilo/{henkilo-oid}/organisaatiohenkilo

4 Listaa annetun henkilön kaikki organisaatiohenkilöt. POST /henkilo/{henkilo-oid}/organisaatiohenkilo Luo uuden organisaatiohenkilön liittäen sen annettuun henkilöön. PUT /henkilo/{henkilo-oid}/organisaatiohenkilo Päivittää kaikkia henkilön organisaatiohenkilöitä, jotka annetaan kutsussa. GET /henkilo/{henkilo-oid}/organisaatiohenkilo/{organisaatio-oid} Palauttaa vain yhden organisaatiohenkilön, joka täsmää annettuihin henkilo-oid ja organisaatio-oid parametreihin. PUT /henkilo/{henkilo-oid}/organisaatiohenkilo/{organisaatio-oid} Päivittää vain yhtä organisaatiohenkilöä, joka täsmää annettuihin henkilo-oid ja organisaatio-oid parametreihin. PUT /henkilo/{henkilo-oid}/organisaatiohenkilo/{organisaatio-oid}/kayttooikeusryhmat Päivittää organisaatiohenkilön käyttöoikeuksia annetulla käyttöoikeusdatalla. GET /henkilo/byhetu/{hetu} Hakee henkilön annetun henkilötunnuksen pohjalta. Henkilötunnuksella hakeminen toimii vain kokonaisilla henkilötunnuksilla. GET /henkilo/{henkilo-oid}/anomus Listaa annetun henkilön kaikki anomukset. POST /henkilo/{henkilo-oid}/yksiloi Käynnistää henkilo-oid:in täsmäävän henkilön yksilöintiyrityksen VTJ:ään, jonka avulla henkilöä yritetään yksilöidä henkilötunnuksen ja nimitietojen perusteella. GET /henkilo/{henkilo-oid}/linked Palauttaa annettuun henkilöön liitetyt duplikaatit. POST /henkilo/{henkilo-oid}/linked Yhdistää henkilöitä toisiinsa siten, että annettu henkilo-oid on varsinanen henkilö, johon halutaan linkittää kutsussa annetut duplikaatit. GET /henkilo/{henkilo-oid}/yksilointiview Hakee mahdollisia duplikaatteja henkilökannasta, jotka täsmäävät tiettyjen ehtojen mukaan annetun henkilön tietoihin.

5 GET /henkilo/{henkilo-oid}/comparison Hakee annettuun henkilöön liitetyn vertailudatan, joka on saatu VTJ:stä niissä tilanteissa, joissa automaattinen yksilöinti ei ole onnistunut. GET /henkilo/{henkilo-oid}/overwrite Yliajaa annetun henkilön tiedot VTJ:n tiedoilla. GET /henkilo/{henkilo-oid}/manualoverride Pakottaa annetun henkilön statuksen yksilöidyksi. Tämä komento voidaan ajaa vain henkilöille, joilla ei ole henkilötunnusta. GET /organisaatiohenkilo/organisaatios Listaa kirjautuneen käyttäjän kaikki organisaatiot. GET /kayttooikeusryhma Listaa kaikki käyttöoikeusryhmät, mitkä löytyvät käyttäjähallinnasta. POST /kayttooikeusryhma Luo uuden käyttöoikeusryhmän annetun ryhmädatan perusteella. GET /kayttooikeusryhma/{ryhma-id} Hakee yhden käyttöoikeusryhmän tiedot annetun ID:n perusteella. GET /kayttooikeusryhma/{ryhma-id}/sallitut Listaa annetun ryhmän alle alistetut käyttöoikeusryhmät. GET /kayttooikeusryhma/{ryhma-id}/kayttooikeus Listaa annettuun käyttöoikeusryhmään liitetyt palvelut ja roolit. PUT /kayttooikeusryhma/{ryhma-id}/kayttooikeus Päivittää annettua käyttöoikeusryhmää syötetyllä ryhmädatalla, joka pitää sisällään annetut palvelu-rooliyhdistelmät, lokalisointitekstit ja tälle ryhmälle alistetut ryhmät. POST /kayttooikeusryhma/kayttooikeus Luo uuden käyttöoikeuden annetun käyttöoikeusdatan pohjalta.

6 GET /kayttooikeusryhma/henkilo/{henkilo-oid} Hakee kaikki käyttöoikeusryhmät annettuun henkilöön liittyen. Tulos pitää sisällään tällä hetkellä voimassaolevat ja suljetut oikeudet. GET /kayttooikeusryhma/henkilo/current Hakee kirjautuneen käyttäjän kaikki käyttöoikeusryhmät. POST /kayttooikeusryhma/henkilo/current Tekee uuden käyttöoikeusanomuksen olemassaoleville käyttöoikeuksille, jotka on valittu UI:n kautta. GET /kayttooikeusryhma/{henkilo-oid}/{organisaatio-oid} Hakee annetun henkilön tiettyyn organisaation liittyvät käyttöoikeudet, jotka pitävät sisällään sekä valitut että mahdollisesti myönnettävät. Lista on myös rajattu kirjautuneen käyttäjän eli myöntäjän omien oikeuksien mukaan. GET /kayttooikeus/{palvelunimi} Hakee annettuun palveluun liitetyt käyttöoikeudet. Palvelun nimi pitää olla järjestelmän käyttämä tunnistenimi, jota ei näytetä UI:ssa. GET /kayttooikeus/kayttaja/current Listaa kirjautuneen käyttäjän kaikki käyttöoikudet. GET /anomus Tekee haun käyttöoikeusanomuksille annettujen hakuparametrien perusteella. Jos mitään parametria ei anneta, palautetaan kaikki uudet anomukset käänteisessä aikajärjestyksessä. POST /anomus Tekee uuden käyttöoikeusanomuksen. PUT /anomus Tekee anomuksen hyväksymisen annetun anomusdata pohjalta. GET /anomus/{anomus-id} Hakee tietyn anomuksen annetun ID:n perusteella. GET /anomus/{anomus-id}/reject Hylkää annetun anomuksen. Liittää hakuparametrina annetun hylkäyssyyn anomuksen tietoihin.

7 GET /anomus/{anomus-id}/cancel Peruuttaa annetun anomuksen. GET /palvelu Hakee kaikki palvelut käyttäjähallinnasta. GET /kielisyys Hakee kaikki kielisyystiedot, jotka on syötetty käyttäjähallintaan. GET /kansalaisuus Hakee kaikki kansalaisuustiedot, jotka on syötetty käyttäjähallintaan. POST /salasana/valid Tarkistaa annetun salasanan vahvuuden. POST /salasana/{henkilo-oid} Asettaa annetulle henkilölle salasanan. POST /salasana/poletti Lähettää salasanan nollaukseen tarvittavan poletin annettuun käyttäjänimeen liittyen. POST /salasana/poletti/{poletti} Nollaa käyttäjän salasanan annetulla uudella salasanalla, joka täsmää annettuun polettiin. POST /yksilointi/queryandadd Ulkopuolinen rajapinta, jonka kautta ulkoinen palvelinjärjestelmä voi hakea ja lisätä uusia Henkilöitä järjestelmään. Käytetään hakemaan tietoa yksilöidyistä Henkilöistä joko OID:n tai henkilötunnuksen perusteella. Toteuttaa myös uusien henkilöiden luontipalveun, jolla voidaan luoda henkiöitä joilla ei ole henkilötunnusta. Esitysmuodot

8 application/json (esimerkki) request: [ { uuid: "ab23-ce12-345ade-678f " oid: " " error: null } ] reply: [ { uuid: "ab23-ce12-345ade-678f " oid: " " yksiloity: "true/false" error: null/"error code" } ] Kysely voidaan toteuttaa 3 erilaisella parametrilla/paketilla: OID: hakee suoraan OID:n avulla yksilöintitiedon jo varmasti luotuun henkilöön jos OID vastaa luotua henkilöä -> palautetaan ko. henkilön yksilöintistatus ja sama OID jos OID vastaa luodun henkilön vanhaa OID:a -> palautetaan ko.henkilön uusi OID ja yksilöintistatus jos OID ei vastaa mitään luotua henkilöä -> palautetaan null-arvo ja virhekoodi HETU: haetaan henkilötunnuksella luotujen henkilöiden joukosta jos HETU vastaa luotua henkilöä -> palautetaan ko. henkilön yksilöintistatus ja sama OID jos HETU ei vastaa mitään luotua henkilöä -> luodaan uusi henkilö, joka yritetään automaattisesti yksilöidä, palautetaan luotu OID ja yksilöintistatus ei-oid / ei-hetu: ei yritetä hakea henkilöitä luodaan aina uusi henkilö, jota ei yritetä yksilöidä, koska HETUa ei ole annettu Ylläolevasta parametrilistasta viimeinen kohta on se, jonka käyttöä tulisi mielellään välttää varsinkin massa-ajoissa, koska tämä aiheuttaa duplikaattihenkilöitä turhaan. Tämä on tarkoitettu lähinnä sitä varten, että ulkoinen toimija, jonka organisaatioon on liittynyt henkilö jonka henkilötunnusta ei vielä tiedetä, voidaan lisätä järjestelmään jo valmiiksi odottamaan. Tämä vaatii siis aina manuaalista työtä virkailijalta, jotta henkilö saadaan positiivisesti yksilöidä.