SSO-integraation tekninen kuvaus

Yleistä

Tässä dokumentissa sanalla palvelu viitataan aina kolmannen osapuolen toteuttamaan sivustoon, joka halutaan liittää osaksi asiakkaan kertakirjautumispalvelua. Sanalla käyttäjä viitataan palvelua käyttävään tahoon, tyypillisesti jäseneen.

Alla kuvataan ensin kirjautumisen vaiheet yleisellä tasolla, jonka jälkeen esittelemme tyypillisen integraation toteutustavan.

 

Kirjautumisprosessi

  1. Käyttäjä saapuu palveluun. Palvelu tarkistaa, onko käyttäjällä paikallista sessiota. Jos sessio on olemassa, kaikki seuraavat vaiheet ohitetaan.
  2. Palvelu siirtää käyttäjän SSO:n puolelle kirjautumisosoitteeseen. Kirjautumisosoitteen saat Vitec Avoinen asiakaspalvelusta.
  3. Kun käyttäjä on kirjautunut onnistuneesti, SSO siirtää käyttäjän takaisin palvelun antamaan paluuosoitteeseen.
  4. Palvelu verifioi POST-parametrina saadun käyttäjätunnisteen. Verifiointi tehdään lähettämällä palvelintason kysely SSO:n rajapintaan. Vastauksena rajapinta palauttaa käyttäjän perustiedot.
  5. Palvelu tarkistaa perustiedoista, onko käyttäjällä oikeus palveluun. Jos ei, kirjautuminen keskeytetään.
  6. Palvelu perustaa paikallisen session, eli kirjaa käyttäjän sisään ja siirtää käyttäjän palvelun kotisivulle.

Integraation toteutus

  1. Tilaa API-avain osoitteesta asiakaspalvelu@avoine.fi
    • Ilmoita samalla tarvitsemanne paluuosoitteet, mukaan lukien palvelun mahdolliset kehitysosoitteet (esim. http://localhost:9000/login/verify). Mikäli lopullinen paluuosoite ei ole vielä tiedossa, voitte ilmoittaa sen myös jälkikäteen.
  2. API-avaimen ohella toimitamme vastauksena palvelutunnisteen, joka on osa aiemmin mainittua kirjautumisosoitetta.
  3. Toteuta käyttäjän siirto kirjautumisosoitteeseen.
    • Siirto tehdään tyypillisesti tavallisella HTTP-redirectillä.
  4. Toteuta käyttäjätunnisteen verifiointi paluuosoitteessa.
    • Käyttäjä saapuu paluuosoitteeseen POST-requestillä. 
    • Käyttäjätunniste on POST-parametrissa ssoid.
    • Verifiointi tehdään esimerkiksi näin:
      • curl -X POST -H "Content-Type: application/json" -d '{"id":"<satunnaista>","method":"GetUserData","params":["<API-avain>", "<käyttäjätunniste>"],"jsonrpc":"2.0"}' https://tunnistus.avoine.fi/mmserver
    • Jos käyttäjätunniste on oikea, saat palvelimelta vastauksena käyttäjän perustiedot JSON-objektina. Jos vastaus on jotain muuta, keskeytä prosessi.
      • Objektin sisältö riippuu asiakkaan järjestelmästä, joten suosittelemme aluksi tutkimaan rajapinnan vastausta ja toteuttamaan varsinaisen verifioinnin vasta sen jälkeen.
      • Perustiedoissa on järjestelmästä riippumatta mukana groups-property, jossa on listattu käyttäjän ryhmätunnisteet. Tyypillisesti palvelun tulee päätellä näistä, onko käyttäjällä oikeus palveluun.
      • Voit ilmoittaa Avoinen asiakaspalveluun ryhmät, joiden tulee päästä kirjautumaan palveluun. Asiakaspalvelumme kertoo teille niitä vastaavat ryhmätunnisteet. 
  5. Toteuta tarpeen mukaan käyttäjän lisäys tai päivitys palvelun paikalliseen käyttäjähallintaan, kirjaa käyttäjä sisään ja siirrä käyttäjä palvelun kotisivulle.

Uloskirjautuminen

Voit kirjata käyttäjän ulos SSO:sta linkittämällä osoitteeseen https://tunnistus.avoine.fi/sso-logout/.