Ohjeet Shibbolointiin

Last modified by Jukka Karvonen on 2024/08/26 13:58

HY:n Shibboleth on HY:n keskitetyn kirjautumisen palvelu, jonka kautta palvelussa voi ottaa käyttöön keskitetyn kirjautumisen SAML tai OpenID Connect-protokollilla. Kirjautumisen yhteydessä käyttäjästä voidaan välittää tietoja, joita voidaan käyttää oikeuksienhallintaan.

Shibboleth-palvelun saa käyttöön tämän ohjeen mukaisesti.

Jos haluat, että sovellukseesi voi kirjautua login.helsinki.fi:sta, HAKA-, tai eduGAIN -luottamusverkoista, aloita liittyminen miettimällä alla mainitut tiedot. Haka- ja eduGAIN-rekisteröinneistä ole yhteydessä sivun alareunan yhteystiedoin.

login.helsinki.fi -rekisteröinnit ja palveluiden muutokset tehdään suoraan suoraan SP-rekisteriin. Jos teillä on jo palvelu HY:n Shibbolethissa, mutta ei pääsyä siihen edellä mainitun SP-reksiterin kautta, ole yhteydessä sivun alareunan yhteystiedoin.

Tarvittavat tiedot

Halutessasi SAML2:n tai OIDC:n -kirjautumisen käyttöön palveluun, tarvitset siitä mm. seuraava tiedot:

  • Palvelun nimi (esim. "Helsingin yliopiston Moodle").
    • Tämä näytetään käyttäjälle kirjautumisen yhteydessä, joten sen olisi hyvä olla tarjolla ainakin kaikilla palvelun käyttökielillä.
  • Lyhyt kuvaus sovelluksesta (esim. "Helsingin yliopiston Moodle verkko-oppimisympäristö").
    • Tämä näytetään käyttäjälle kirjautumisen yhteydessä, joten sen olisi hyvä olla tarjolla ainakin kaikilla palvelun käyttökielillä.
  • Palvelun omistajan/vastuuhenkilön, teknisten kontaktien ja mahdollisen Tietotekniikkakeskuksen yhteyshenkilön yhteystiedot (nimi ja sähköposti).
  • Sijaitseeko palvelu HY:n verkossa?
    • Kuka sitä ylläpitää?
    • Mikä on palveun https-osoite?
  • Halutaanko palvelun toimivan vain HY:n käyttäjillä, kaikilla Haka-korkeakouluilla vai laajemmin? (kts. Federaatiot)
  • Palvelun tarvitsemat attribuutit (esim. nimi, sähköpostiosoite, uid).
    • Katso tarkemmat tiedot attribuuteista alta.
  • Linkki sovelluksen tietosuojaselosteeseen tai vastaavaan tietosuoja-asetuksen mukaiseen informointiasiakirjaan, jossa käyttäjälle kerrotaan hänen tietojensa käytöstä järjestelmässä.
    • HY:n ulkopuolista palvelua lisättäessä on toimittajan kanssa tehtävä sopimus henkilötietojen käsittelystä (DPA) ennen keskitetyn kirjautumisen käyttöönottoa.
  • Linkki palvelun tietoihin sovellussalkussa.

Jos tarvitsette apua myös SP:n konfigurointiin, toimittakaa myös seuraavat tiedot:

  • Mikä palvelinalusta palvelulla on? Parhaiten apua saa standarditapaukseen Red Hat Enterprise Linux 7 / Apache httpd / Shibboleth SP
  • Minkälainen suojattava sovellus on? Esim. millä ohjelmointikielellä/frameworkilla tehty, mikä sovelluspalvelin jne.

Tiedot kirjataan suoraan SP-rekisteriin. Federaatioiden osalta katso ohjeet liittymisestä alta.

Palvelun tekniset määritykset

Huom. alla oleva koskee pääosin SAML:a. Jos haluat käyttää Open ID Connectia (OIDC) kirjautumiseen, löydät ohjeita täältä.

Palvelun käyttämä SAML-sovellus

Asenna käytettävä SAML2-tuote ja huolehdi, että sen tietoturvapäivitykset asennetaan automaattisesti.

Shibbolethin asentamisesta RHEL/Ubuntu palvelimille löydät ohjeet malliesimerkeistä alta.

Muiden tuotteiden asennusohjeita löydät näiden omilta sivuilta. Kattava lista SAML-tuotteista löytyy Wikipediasta. Esimerkiksi SimpleSAMLphp on hyvin tuettu toteutus.

Varmista, että palvelussa on ntp-palvelu käytössä

Kirjautuminen ei onnistu, jos palvelu on eri ajassa kuin kirjautumispalvelin. Raja on yleensä 5 sekuntia, mutta voi vaihdella.

Palvelu tunniste, entity ID

Palvelulle määritetään yksilöllinen tunniste, joka muodostetaan palvelun URL:sta ja yleensä käytetyn SAML-toteutuksen päätteestä esim. "https://palvelu.helsinki.fi/sp"

IdP:n metatiedot

Palveluun tulee määrittää luottamusverkon metadata, joka sisältää mm. kirjautumispalvelinten osoitteet sekä näiden julkiset varmenteet.

Hakan osalta vastaavat tiedot löytyvät osoitteesta https://wiki.eduuni.fi/display/CSCHAKA/Haka+metadata

Metadata kannattaa asettaa päivittymään automaattisesti, jos käytettävä SAML2-toteutus sitä vain tukee. Metadatan oikeellisuus on aina varmistettava allekirjoitusvarmenteella.

Shibboleth SP:n osalta mallia metadatan automaattisesta päivittämisestä voi katsoa esimerkistä.

Varmenteet

Palvelun ulkoinen SSL-varmenne

Keskitettyyn käyttäjätunnistukseen liitettävien verkkopalveluiden tulee toimia HTTPS-protokollan päällä. Yliopiston palveluissa näihin liittyvät TLS-varmenteet saa tilattua Tiken kautta, ca@helsinki.fi.

Shibbolthin käyttämä varmenne

Shibboleth/SAML-liitännässä kannattaa käyttää palvelun julkisesta SSL-varmenteesta erillistä varmennetta. SAML:ssa varmennetta käytetään vain SP:n ja IdP:n välisten viestien allekirjoitukseen ja salaukseen. Erillisten varmenteiden käyttö helpottaa ylläpitoa, koska varmenteita ei tarvitse vaihtaa samaan aikaan. Lisäksi tietoturvariskit ovat jossain määrin erilaisia.

Koska sertifikaatti määritetään käsin sekä IdP:hen että SP:hen, voidaan tässä hyvin käyttää itse allerkijoitettua sertifikaattia. Suositeltava käytäntö on 4096 bitin RSA-sertifikaatti 10 vuoden voimassaololla. Sertifikaatti tulee vaihtaa nopeammin, jos epäillään sen joutuneen vääriin käsiin.

Varmenteen luominen

Esimerkiksi Linux-palvelimella voit luoda varmenteen ja avaimen seuraavasti:

openssl req -new -x509 -nodes -newkey rsa:4096 -keyout sp1-test-shib-key.pem -days 3650 -subj '/CN=sp1.test.helsinki.fi' -out sp1-test-shib-cert.pem
chmod 640 sp1-test-shib-key.pem
chown root:shibd sp1-test-shib-key.pem (Huom. Ubuntussa ryhmä on _shibd)

Varmenteen vaihto

Olemassa olevan palvelun varmenteen vaihto tehdään SP-rekisterin kautta. Vaihdossa on 5. vaihetta, jotta käyttäjille ei aiheudu katkoksia vaihdosta. Vaihto kannattaa aloittaa viimeistään 2 viikkoa ennen varmenteen vanhenemista.

  1. Palveluun lisätään uusi varmenne vanhan rinnalle, siten että palvelu allekirjoittaa omat viestinsä vanhalla avaimella, mutta osaa purkaa uudella salattuja viestejä. Hakan wikistä löytyy ohjeet tähän.
  2. Uusi varmenne lisätään palvelulle SP-rekisterissä.
  3. Odotetaan, että uusi varmenne on otettu käyttöön IdP:llä ja vaihdetaan sen jälkeen varmenteiden järjestys palvelussa, siten että viestit allekirjoitetaan uudella varmenteella.
  4. Poistetaan vanha varmenne SP-rekisteristä.
  5. Odotetaan, että varmenteen poisto on viety tuotantoon ja poistetaan sen jälkeen vanha varmenne myös palvelusta.

Jos tarvitset nopeamman aikataulun, ole yhteydessä IdP-ylläpitoon sähköpostitse. Huomioi ettei IdP sinällään välitä vanhantuneesta varmenteesta ja jatkaa toimimista myös sillä. Myöskään Shibboleth SP ei tästä välitä, mutta jokut SAML SP toteutukset voivat lopettaa toiminnan vanhentuneeseen varmenteeseen.

Attribuutit

Kirjautumisen yhteydessä voidaan sovellusekelle välittää erilaisia attribuutteja. Attribuuteilla hallinnoidaan mm. palveluiden käyttövaltuuksia, eli sitä kenellä on pääsy järjestelmän eri osiin.

Esimerkiksi käytettävyyden kannalta voi olla hyödyllistä, että tietyt opiskelijaryhmät näkevät eri näkymiä. Osa attribuuteilla tehtävistä rajauksista voi olla pakollisia, kuten luottamuksellinen tieto, joka saa näkyä vain osalle käyttäjistä. Paras tapa käyttää attribuutteja löytyy usein HY:n käyttäjien ja käyttötapojen sekä palvelumuotoilun ymmärtämisestä, yhdistettynä siihen mihin järjestelmien tekniset ominaisuudet taipuvat ja on tulevan ylläpidon kannalta järkevää sovittaa.

Luettelo mahdollisista attribuuteista löytyy sivulta Shibboleth käyttäjäattribuutit.

Shibbolethin kautta jaettavat attribuutit ovat henkilötietoja ja niiden käytön tulee olla perusteltua. Lisätietoja henkilötietojen käsittelystä löydät esimerkiksi Flammasta.

Huom. Ohjelman tulee käsitellä tilanteet, joissa kaikkia pyydettyjä attribuutteja ei saada ja antaa niistä tarvittaessa selväkielinen virheilmoitus. Esimerkiksi henkilökunnalla ei usein ole opiskelijanumeroa, mutta he saattavat silti yrittää kirjautumista opiskelijoille suunnattuihin järjestelmiin.

Käyttäjän tunnistaminen

Käyttäjän yksilöimiseen on monia vaihoehtoja.

Suositeltavin on eduPersonPrincipalName (EPPN), joka HY:n tapauksessa on muotoa "<käyttäjätunnus>@helsinki.fi". Vastaavasti uid on pelkkä käyttäjätunnus, mutta sen käyttö aiheuttaa ongelmia, jos myöhemmin palvelun käyttöä halutaan laajentaa esimerkiksi Hakaan. EPPN lukitaan HY:ssä käyttäjälle, eli sitä ei koskaan anneta eteenpäin toiselle käyttäjälle. Samalla käyttäjällä voi olla useita tunnuksia, eli myös useampi EPPN. Tämä on HY:n käytäntö, eli muilla identiteetintarjoajilla tämä voi vaihdella ja usein EPPN on lukittu vain tietyksi aikaa samalle käyttäjälle.

schacPersonalUniqueCode tarjoaa opiskelijanumeron, employeeNumber SAP-HR:n henkilökuntanumeron ja schacPersonalUniqueID henkilötunnuksen. Näitä ei kuitenkaan kannata käyttää yleisesti käyttäjän yksilöimiseen, koska kaikille niitä ei ole määritettynä. Näiden hyöty on lähinnä integrointiin muiden järjestelmien kanssa.

eduPersonAffiliation antaa käyttäjän roolin organisaatiossa. Vaihtoehtoina on faculty, staff, employee, student, member, affiliate, library-walk-in. ja arvoja voi olla monta. eduPersonPrimaryAffiliation antaa vastaavasti ensisijaisen roolin. Tarkemmat määritykset näille löytää osoitteesta https://wiki.eduuni.fi/display/CSCHAKA/funetEduPersonSchema2dot2#funetEduPersonSchema2dot2-eduPersonAffiliation.

Uloskirjautuminen

Kertakirjautumisjärjestelmästä uloskirjautuminen on varsin haastava konsepti. Jos palvelu tukee SLO:ta (Single Logout), voidaan uloskirjaaminen ohjata käytetyn SAML-toteutuksen Logout-osoitteeseen. Esimerkiksi Shibboleth SP:ssä tämä on yleensä "/Shibboleth.sso/Logout". Tällöin täytyy varmistua, että myös SAML SP-sovelluksen takana oleva sovellus on kirjattu ulos.

Jos palvelu ei tue SAML2 SLO:ta, kannattaa palvelu kirjata itse ulos ja tämän jälkeen ohjata käyttäjä IdP:n SLO-linkkiin osoitteessa https://login.helsinki.fi/idp/profile/Logout, jolloin hänet kirjataan ulos myös IdP:ltä ja annetaan mahdollisuus muista palveluista uloskirjautumiseen.

Esimerkiksi Shibboleth SP voi tiedottaa ohjelmaa logoutista. Ohjeita tähän löytyy osoitteesta https://wiki.shibboleth.net/confluence/display/SHIB2/SLOWebappAdaptation

Mallitoteutuksia SAML-palvelun määrittämiseen

Erilaisia SAML-toteutuksia on useita. Eniten käytetään Shibbolethia, joka tukee Apache- ja ISS-palvelinohjelmia, mutta myös muita SAML2-määrityksen täyttäviä toteutuksia on mahdollista käyttää.

Alla on ohjeita SAML-liitännän toteuttamiseen Shibboleth SP:llä. Muilla sovelluksissa on omat konfiguraatiotapansa, mutta tarvittavat tiedot ja periaatteet ovat yleensä samoja.

Lisäksi Suomen korkoeakoulujen luottamusverkosto Hakalla on yleisiä teknisiä ohjeita Shibbolethin käyttöönottoon. Samat käytännöt pätevät myös suoraan Helsingin yliopiston Shibbolethiin liittyessä.

Federaatiohin (luottamusverkostot) liittyminen

Yleiskuvaus federaatioista löytyy toiselta sivulta.

Teknisesti järjestelmä on yhtä helppo liittää Hakaan tai eduGAINiin, kuin Helsingin yliopiston kertakirjautumisjärjestelmään. Hallinnollisesti työtä on jonkun verran enemmän, joten huomioi seuraavat asiat:

  • Hakassa ja eduGAINissa kaikki palvelut liitetään ensin testipuolelle ja vasta kun niiden toimivuus on testattu siellä, on ne mahdollista siirtää tuotantoon.
    • Testijärjestelmässä ei käytetä todellista käyttäjätietoja vaan erikseen tarkoitusta varten luotuja testikäyttäjiä.
    • Jos tarvitset erillisen QA-järjestelmän oikeilla käyttäjillä, on tällainen mahdollista liittää tuotantopuolelle, mutta sen vaatimukset ovat vastaavat kuin tuotantojärjestelmällä. Sisältäen palvelukohtaisen tietosuojaselosteen ja vastaavat tietoturvakäytännöt.
  • Varmista, että sinulla on kaikki tarvittavat tiedot (linkki vie Hakan ohjeisiin). Testivaiheessa selviää kevyemmillä tiedoilla, tuotantovaiheessa vaaditaan esimerkiksi nimi ja palvelukuvaus kolmikielisesti, yhtestiedot sekä tietosuojaseloste.
  • Metatietoja tuotantopuolelle päivitetään kerran viikossa. Kokonaisuudessaan uuden palvelun lisääminen vie yleensä vähintään pari viikkoa, vaikka kaikki olisi kunnossa ja valmiiksi konfiguroituna.

Metatiedot lisätään Hakan resurssirekisterin kautta, joten olethan yhteydessä yllä mainittuihin yhteysosoitteisiin. Tietoja ei voi ylläpitää HY:n oman SP-rekisterin kautta.

Monivaiheinen tunnistautuminen

Palveluun kirjautuessa on mahdollista vaatia monivaiheista tunnistautumista. Tällöin kirjautumisvaiheessa käyttäjä ohjataan AD-kirjautumiseen (sama kuin O365) tekemään tunnistautuminen.

Huom. erona O365-kirjautumiseen, Shibbolethissa ainakin toistaiseksi MFA muistetaan korkeintaan kolme tuntia ja sen jälkeen palveluun kirjautuessa se vaaditaan uudelleen.

Tapoja tähän on kaksi:

Kirjautumispyynnössä vaaditaan MFA

Palvelu lisää IdP:lle lähettämäänsä kirjautumispyyntöön AuthnContextClassRef-määriksen, joka vastaa monivaiheista tunnistautumista. Käytämmä REFEDS MFA-profiilin mukaista, arvoa, eli "https://refeds.org/profile/mfa".

<samlp:RequestedAuthnContext>
  <saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
    https://refeds.org/profile/mfa
  </saml:AuthnContextClassRef>
</samlp:RequestedAuthnContext>

Tämä mahdollistaa MFA:n vaatimisen esim. vain hallintaliittymään kirjautumisessa, jolloin IdP:ltä pyydetään uusi tunnistautuminen halutulla kontekstilla.

MFA-vaatimus asetetaan SP-rekisterissä

SP-rekisterissä voidaan asettaa "Tekniset tiedot"-kohdassa "Vaadi vahvaa tunnistusta" valinta päälle, jolloin kaikilta käyttäjiltä vaaditaan monivaiheinen tunnistautuminen. Huom. Tällöin palvelu ei saa vaatia mitään tiettyä AuthnContextClassRef-arvoa (kts. yllä) tai kirjautuminen päättyy virheeseen.

Jos toimita epäilyttää tai haluat testata tätä tuotantojärjestelmässä ennen kuin muutos näkyy käyttäjille, ole yhteydessä sivun alaosan yhteystiedoin.

Rajoitukset

Monivaiheinen tunnistautuminen toimii vain tunnuksilla, jotka ovat synkronoitu pilvi-AD:lle (Azure) ja jotka ovat yksilötunnuksia. Yhteiskäyttötunnuksilla käyttö ei ole mahdollista, koska vahvennusmenetelmät ovat henkilökohtaisia.

Tunnistus toimii ainakin HY:n henkilöstöllä ja tutkinto-opiskelijoilla. Myös muilla henkilöstöryhmillä käyttö on pääosin mahdollista. Kaikkia erikoistunnuksia ei ole synkronoitu pilvi-AD:lle (Azure), joten selvitä tarvittaessa tilanne näiden osalta erikseen.

Testipalvelu

HY:llä on käytössä testi-IdP, johon palveluita voi lisätä ja jossa käytetään itse määritettyjä testitunnuksia ja -attribuutteja todellisten käyttäjätunnusten sijaan.

Lisäohjeita testipaveluun on erillisellä sivulla. Määritykset testipalveluihin sekä niiden käyttäjätunnukset tehdään SP-rekisteri (SAMLOIDC)ssä.

Tukea ongelmiin?

Jos näiltä sivuilta ei löydy vastausta ongelmiin, ota yhteyttä suoran autentikoinnista vastaaviin asiantuntijoihin.

  • Sähköposti: atk-autentikointi at helsinki.fi.
  • Efect: tukiryhmä TIKE/Käyttäjähallinto.
  • HY Teams tai Helsinki.fi-Slack: Jukka Karvonen.

Muita ohjeita