Tällä sivulla kuvataan joitain teknisiä yksityiskohtia, joilla ei ole suurta merkitystä palvelun käyttämisen kannalta. Niistä voi kuitenkin olla hyötyä esimerkiksi virhetilanteiden selvittämisessä.
Esimerkkipolku kirjautumisesta tietojen hakuun
- käyttäjä menee palvelun A sivulle https://palvelu-a.fi
- käyttäjä klikkaa “Kirjaudu AuroraAI-tilillä”
- käyttäjän selain ohjautuu sivuun “https://auroraai.suomi.fi/authorize?client_id=708cfe6c-a099-47fc-b77e-102957a6b696&response_type=code&scope=age&state=foobar123”
- client_id: palvelu A:n AuroraAI service id
- response_type=code: käytetään aina authorization code grant menettelyä arvolla “code”
- state: palvelun A määrittämä uniikki merkkijono jolla ehkäistään CSRF-hyökkäyksiä
- scope: lista muuttujista joita palvelu tuottaa/kuluttaa
- pelkkä “age” tarkoittaa kuluttamista, “store:age” tuottamista
- redirect_uri: osoite mihin käyttäjä ohjataan kirjautumisen jälkeen (Palvelu A:n hallinnoima osoite). Jos ei annettu, niin käytetään tiedossa olevaa palvelun A oletusarvoa.
- jos käyttäjällä ei ole AuroraAI-tiliä, hän voi sen tehdä sivulla
- jos käyttäjällä on AuroraAI-tili, hän voi kirjautua sillä sisään
- jos käyttäjä on jo kirjautunut AuroraAI-tilillä, hänelle näytetään valtuutussivu
- käyttäjän sessio tunnistetaan auroraai.suomi.fi domainin cookieilla "aai_access_token" ja "aai_refresh_token"
- valtuutussivulla käyttäjä valitsee mitä käyttäjän tietoja palvelu saa tuottaa/kuluttaa AuroraAI-verkossa
- on mahdollista myös vain kirjautua ilman valtuutuksia
- jos käyttäjä on kerran antanut valtuutuksen, se muistetaan seuraavalla kerralla ja jätetään kysymättä, tehdään suora uudelleenohjaus takaisin palveluun A
- klikkaamalla “Hyväksy luvat” käyttäjä palaa takaisin palvelun A sivulle
- sivun parametreihin on lisätty esim. “https://palvelu-a.fi/oauth/callback/auroraai?code=r303LB34duNqH61CTD79-NMzGw7ceccFdCN_5IdgjEzPrORRCvVt4Yk6gnTLKBy121rWz04t8HgvDU9HleJEZcOCMb8ejz0JdvDhK-j7yUcGp6S56uvEwyiWA7ysd6-6_qcpQi8ETuOFW-Ndzjt-fOG3bjHPgFLz9CoLgxfttj0&state=foobar123”
- “https://palvelu-a.fi/oauth/callback/auroraai”: palvelun A redirect URI, pitää olla joku profiilinhallintaan määritellyn listan sallittu osoite
- code: luvituskoodi, jolla palvelu voi pyytää access tokenin
- state: sama uniikki merkkijono kuin kohdassa 3, palvelun A pitää varmistaa että se on sama
- palvelu A tekee pyynnön POST “https://auroraai.suomi.fi/oauth/token”
- pyynnössä oltava header “Authorization: Basic base64(client_id:client_secret)”
- client_id: palvelun A AuroraAI service id
- client_secret: palvelulle A erikseen välitetty salaisuus
- pyynnön bodyssa:
- grant_type: “authorization_code” kun käytetään koodia, “refresh_token” kun myöhemmin päivitetään access tokenia
- code: kohdassa 9 parametrina annettu koodi. Koodia käytettäessä annettava myös:
- redirect_uri: sama kuin kohdassa 9
- refresh_token: kun päivitetään olemassa olevaa access tokenia, tähän laitetaan refresh token eikä codea anneta
- scope: scopea voi halutessaan pienentää uudelle access_tokenille, jolloin myös refresh_token vaihtuu
- palvelu A vastaanottaa id tokenin, access tokenin ja refresh tokenin joilla tehdä toimenpiteitä käyttäjälle
- id tokenilla palvelu A tietää kuka kirjautunut käyttäjä on (palvelukohtainen uniikki id) (JWT token, jonka allekirjoitus tarkistetaan palvelussa A)
- access tokenilla palvelu A voi tuottaa/kuluttaa käyttäjän valtuuttamia tietoja, access token on voimassa tunnin
- Refresh tokenilla palvelu A voi hakea uuden access tokenin kun se on vanhentunut, refresh token on voimassa sata päivää. Kun refresh token on vanhentumassa (voimassa enää alle seitsemän päivää), palvelulle annetaan uusi refresh token saman pyynnön yhteydessä.
- palvelu A tekee pyynnön PATCH “https://auroraai.suomi.fi/profile-management/v1/user_attributes” kertoakseen verkolle palvelussa saatavilla olevista attribuuteista
- pyynnössä oltava header “Authorization: Bearer <access token>”
- access tokenista voidaan päätellä käyttäjä ja palvelu, jolloin niitä ei tarvitse antaa parametreina
- pyynnön bodyssa JSON-enkoodattu lista lisättävistä attribuuteista, esim. [“age”, “municipality_code”]
- PATCH-semantiikan mukaisesti lista lisää attribuutteja olemassa olevaan tuettujen attribuuttien listalle, eikä korvaa olemassaolevia arvoja
- DELETE “https://auroraai.suomi.fi/profile-management/v1/user_attributes” -pyynnöllä voi palvelu A poistaa attribuutteja listalta
- pyynnössä oltava header “Authorization: Basic base64(client_id:client_secret)”
- client_id: palvelun A AuroraAI service id
- client_secret: palvelulle A erikseen välitetty salaisuus
- bodyssä JSON-enkoodattu lista poistettavista attribuuteista, esim. [“age”]
- tämä pyyntö ei ole autentikoitu access tokenilla, jotta palvelu voi poistaa attribuutteja myös deaktivoinnin jälkeen
- muut palvelut eivät voi käyttää tietoja vaikka attribuuttien sijaintitiedot jäävät deaktivoinnin jälkeenkin
- deaktivoinnin jälkeen sijaintitietoja ainoastaan käytetään käyttäjän liitetyt palvelut -listauksessa kertomaan siitä, että palvelu ei ole kertonut poistaneensa attribuutteja
- profiilinhallinta tallentaa tiedon palvelusta A saatavilla olevista attribuuteista ja vastaa palvelulle OK
- palvelu A tekee pyynnön POST “https://auroraai.suomi.fi/profile-management/v1/user_attributes” pyytääkseen verkosta käyttäjän attribuutteja
- pyynnössä vastaava Authorization header kuten kohdassa 12
- bodyssa lista pyydettävistä attribuuteista, esim. [“life_situation_meters”]
- profiilinhallinta selvittää, mistä palveluista pyydetty attribuutti olisi saatavilla
- attribuutti on saatavilla palvelusta B, joten profiilinhallinta tekee palveluun B pyynnön GET “https://palvelu-b.fi/auroraai/profile-management/v1/user_attributes”
- osoite https://palvelu-b.fi on profiilinhallinnan tiedossa
- Tehdään profiilinhallinnan JWK-avaimella JWT access token, jossa:
- palvelu B tarkistaa access tokenin allekirjoituksen (hakee julkisen avaimen osoitteesta https://auroraai.suomi.fi/oauth/.well-known/jwks.json) ja palauttaa käyttäjän pyydetyt attribuutit (scope-kenttä JWT:ssä) profiilinhallinnalle
- profiilinhallinta palauttaa käyttäjän attribuutin palvelulle A
AuroraAI-tilin tunnusvaatimukset
Tilin luonti
- tilin voi luoda vain toimivalla sähköpostiosoitteella
- sähköpostiin toimitetaan aktivointilinkki
Salasanaan liittyvät vaatimukset
- Salasanan pituuden tulee olla vähintään 12 merkkiä
- Salasanan tulee sisältää vähintään
- yksi ison kirjain
- yksi pieni kirjain
- yksi numero
- yksi erikoismerkki
- Salasanaa pitää vaihtaa 360 päivän välein
Kirjautumiseen liittyvät vaatimukset
- Kirjautuminen mahdollista vain aktiivisella ja oikealla salasanalla
- Käyttäjälle nousee ilmoitus virheellisestä kirjautumisesta ("väärä sähköposti tai salasana")
- Väärinannettu tunnus / salasana lukitsee tilin
- Käytetään Cogniton toteutusta. Viiden (5) kirjautumisyrityksen jälkeen asetetaan yhden (1) sekunnin lukko ja jokaisen seuraavan epäonnistuneen kirjautumisyrityksen jälkeen lukon kesto tuplaantuu (1s, 2s, 4s, 8s, 16s, jne.) aina 15 minuuttiin saakka.
- Cogniton implementaatio: User pool authentication flow - Amazon Cognito
Salasanan vaihtaminen - pakotettu
- Järjestelmä pakottaa käyttäjän vaihtamaan salasanan 360 päivän välein.
- Käyttäjä pystyy kirjautumaan sisään vanhentuneella salasanalla, mutta vain salasanan vaihtosivu toimii (ohjataan vaihtosivulle vaihtamaan salasana).
Salasanan vaihtaminen - unohdettu salasana
- Käyttäjä voi 'unohditko salasanan?'-sivulla pyytää salasanan uudistamista.
- Vaihtolinkki lähetetään käyttäjän sähköpostiin.
- Linkki on voimassa 24h.
- Linkki ohjaa käyttäjän salasanan vaihtosivulle anfamaan uuden salasanan.
- Käyttäjä voi kirjautua sisään vain tällä uudella salasanalla.
- Vanha salasana toimii niin kauan, kunnes käyttäjä on "aktivoinut" linkistä salasanan vaihtamisen.
- jos linkkiä ei käytetä, jää vanha salasana aktiiviseksi.
Salasanan vaihtaminen - vaihdan itse
- Käyttäjä voi vaihtaa salasanan 'vaihda salasana'-sivulla .
- Sivulla syötetään nykyinen salasana sekä uusi salasana kahdesti.
- Uusittu salasana tulee voimaan heti ja sitä tulee käyttää seuraavan kirjautumisen yhteydessä.
- Vanha salasana toimi enää uloskirjautumisen jälkeen.
Sähköpostin vaihtaminen - vaihdan itse
- Käyttäjä voi vaihtaa sähköpostin 'vaihda sähköposti'-sivulla
- Sivulle syötetään vain uusi sähköpostiosoite.
- Vaihtolinkki lähetetään käyttäjän sähköpostiin.
- Linkki on voimassa 24h
- Tili toimii vanhalla sähköpostilla niin kauan, kunnes käyttäjä on aktivoinut linkistä sähköpostin vaihtamisen.
- Jos linkkiä ei käytetä, jää vanha sähköposti jää aktiiviseksi.
Uniikki sähköposti
Kirjautuminen palvelun kautta
- Käyttäjä ohjataan kirjautumaan. Jos tiliä ei ole, sellainen tulee luoda.
- Kirjauduttaessa uudesta palvelusta ensimmäistä kertaa kysytään suostumukset tietojen tallennukseen ja siirtoon.
Tietojen tallentaminen tilille
- Käyttäjän tulee kirjautua tilille
- Palvelu ei voi tallentaa tietoja eikä hyödyntää muiden palveluiden tietoja, jos käyttäjä ei ole kirjautuneena tilille.
Tilin käyttöaika ja lukkiutuminen
- Käyttäjän AuroraAI-tili lukkiutuu (kirjautuminen vanhentuu), jos tilillä ei ole aktiivista toimintaa.
- Hallintakäyttöliittymässä lukkiutuminen tapahtuu, kun
- aktiivista toimintaa ei ole viimeiseen 30 minuuttiin, tai
- käyttäjä sulkee selaimen.
- Palvelun kautta kirjautuessa lukkiutuminen tapahtuu, kun
- aktiivista toimintaa ei ole viimeiseen 30 minuuttiin, tai
- käyttäjä sulkee selaimen.
Kirjautuminen ulos omalta tililtä
- Käyttäjä voi uloskirjautua palvelun kautta
- Palvelut toteuttavat uloskirjautumislinkin. Käyttäjä palautetaan uloskirjauksen jälkeen takaisin palveluun.
- Käyttäjä voi uloskirjautua hallintaliittymästä.
- Jos käyttäjä on tullut hallintakäyttöliittymään suoralla linkillä, käyttäjä ohjataan AAI-tilin kirjautumissivulle.
- Jos käyttäjä on tullut hallintakäyttöliittymään palvelusta, käyttäjä ohjataan palvelun sivulle.