SP-rekisteri (SAML/OIDC)

Last modified by thata@helsinki_fi on 2023/12/19 08:01

SP-rekisteriä käytetään Helsingin yliopiston login.helsinki.fi-kertakirjautumisjärjestelmään liitettyjen palveluiden metadatan hallintaan.

Palvelu löytyy osoitteesta: https://sp-registry.it.helsinki.fi/

Ohjeita kertakirjautumisen käyttöön ottoon palvelussa löydät sivulta Ohjeet Shibbolointiin.

Käyttö

Kirjautuminen ja käyttöoikeudet

SP-rekisteriin kirjautuminen

Palvelu käyttää kertakirjautumista, joten etusivulta tulee klikata Kertakirjautuminen-kuvaketta.

Työntekijästatuksen omaaville annetaan automaattisesti oikeus lisätä uusia palveluita. Nämä palvelut vahvistetaan ylläpidon toimesta, ennen niiden lisäämistä tuontato-IdP:lle.

Jos kirjautuvaa käyttäjää ei tunnisteta henkilökuntana kuuluvaksi, on hänen tunnuksensa vahvistettava IdP-ylläpidon toimesta. Ota tällöin yhteyttä atk-autentikointi@helsinki.fi kirjautumisen jälkeen.

Tarvittaessa ulkopuoliselle ylläpitäjlle voidaan antaa paikallinen tunnus palveluun.

Palvelukohtaiset oikeudet

Palvelukohtaisia oikeuksia voidaan hallita joko IAM-ryhmien tai henkilökohtiasten oikeuksien kautta. Tarkemmat ohjeet alla, kohdassa Ylläpitäjät.

HUOM. Jos ylläpidossasi on jo Helsingin yliopiston kertakirjautumisjärjestelmää käyttävä palvelu etkä näe sitä valikossa, ota yhteys IdP ylläpitoon ja lähetämme teille linkin, jolla voitte aktivoida oikeudet palveluun.

Tarvittaessa palveluun voidaan luoda myös paikallisia käyttäjätunnuksia ylläpidon toimesta.

Palvelun rakenne

Palvelut

Näyttää luettelon palveluista, joihin käyttäjällä on hallintaoikeus. Valitsemalla palvelun (entityID-sarake), saat tästä tarkemmat tiedot.

Lisäksi tällä sivulla voi lisätä uuden palvelun järjestelmään. "Lisää uusi palvelu" -napin takaa löytyvästä lomakkeesta löytyy sekä perustieto lomake, että mahdollisuus ladata tiedot metatiedoista SAML-palveluiden osalta.

Huom. ladatessa tietoja metadastasta, tarkista ettei palveluun päädy turhia yhteysosoitteita, sertifikaatteja jne.

Yhteenveto (SAML / OIDC)

Näyttää palvelun tiedot sekä mahdolliset muutokset edellisen validoinnin jälkeen.

Sivun alussa näkyy myös mahdolliset palvelusta puuttuvat ja tuotantokäytössä vaadittavat tiedot.

Jos palvelu ei ole tuotantokäytössä, näytetään poistamisnappi sivun lopussa. Tällä voit poistaa palvelun kokonaan näkyvistä. Palautus on mahdollista SP-rekisterin ylläpidon toimesta vuoden ajan.

SIvulla näkyvät "Organisaatio" ja "Ylläpitäjän huomioita" kentät ovat vain SP-rekisterin ylläpidon määritettäväsissä.

Perustiedot (SAML / OIDC)

Palvelun perustiedot ja huomiot.

Palvelulle annettu nimi näytetään palvelun kirjautumissivulla. Lisäksi kuvaus sekä linkki tietosuojaselosteeseen näytetään tietojen luovutusta koskevalla sivulla.

Täytäthän nämä kaikilla kielillä. Jos jotain kieltä ei lödyy, näytetään ne järjestyksessä en → fi → sv. 

Jos palvelussa käytetään HY:n yleisiä tietosuojailmoituksia, voit tietosuojaselosteen antamisen sijaan valita organisaatioksi Helsingin Yliopisto ja lisäksi valinnan "Tietosuojaselosteet organisaatiotiedoista". Tällöin käyttäjälle näytetään osoitteina HY:n yleinen tietosuojasivu: https://www.helsinki.fi/fi/tutustu-meihin/tietosuoja.

Huom. kirjautumisjärjestelmässä on ainakin toistaiseksi rajoite, että nämä tiedot näytetään käyttäjän selaimen pyytämän kielen mukaisesti, ei käyttäjän sivulla valitseman kielen mukaan.

Jos kyseessä on Helsingin yliopiston järjestelmä, lisää tähän myös palvelun osoite Sovellussalkussa. Palvelua ei hyväksytä tuotantoon ilman tätä.

Tekniset tiedot (SAML)

Teknisiä määrityksiä, kuten entity_id ja julkaisu tuotanto tai testipalveluun.

  • Entity Id
    • Täytyy olla URI-muotoa ja uniikki järjestelmässä. Yleinen hyväksi todettu tunniste on palvelun verkkosoite sopivalla päätteellä, esimerkiksi "https://sp-registry.it.helsinki.fi/sp". Jos tarvitset muun kuin URI-muotoisen, ota yhteyttä IdP-ylläpitoon.
  • Discovery-palvelun osoite
    • Jos palvelu on federoitu ja käyttää useampaa IdP:tä lähteenä, anna tähän IdP:n valintasivun osoite. Useimmat voivat jättää tämän huomiotta.
  • Nameidformat
  • Allekirjoita SSO assertiot
    • IdP allekirjoittaa lähettämänsä palvelulle välitetyt käyttäjätiedot/attribuutit. Yleensä pois päältä, koska oletuksena nämä salataan.
  • Allekirjoita SSO pyynnöt
    • IdP vaatii, että palvelun lähettämät autentikointipyynnöt ovat allekirjoitettuja. Jos palvelu tukee tätä, kannattaa tämä asetus kytkeä päälle.
  • Allekirjoita SSO vastaukset
    • IdP allekirjoittaa vastaukset, joita se lähettää palvelulle. Jos tämä ei ole päällä, ei palvelu voi luottaa IdP:n lähettämiin viesteihin, vaan välissä käyttäjä voi väärentää niitä.
  • Salaa SSO assertiot
    • IdP salaa palvelulle lähetetyt käyttäjätiedot/attribuutit. Näin tulisi aina tehdä, mutta jotkut SAML SP-sovellukset eivät tue salausta. Tämä on todennäköisesti muuttumassa pakolliseksi SAML2-määrityksissä.
  • Vaadi vahvaa tunnistusta
    • Testikäytössä oleva vahvemman tunnistuksen palvelu. Ei toimi testipalvelun kanssa. Jos olet kiinnostunut kokeielmaan, kysy lisätietoja IdP-ylläpidolta. Huom. jos tämä asetus on päällä ja palvelu pyytää tiettyä kirjautumismuotoa, kirjautuminen epäonnistuu.
  • Käytä SHA-1 algoritmia allekirjoituksiin
    • Käytetään, jos palvelu ei tue SHA-256 algoritmia, joka on oletus. Ensisijaisesti tulisi päivittää palvelun SAML-sovellus modernimpaan.
  • Pakota tietty nameIDFormat päälle
    • Pakottaaa tietyn nameIdFormat arvon päälle, jolloin haluttu muoto valitaan yllä olevasta listasta. Tarvitaan vain "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" arvon kanssa, jolloin nameid:nä luovutetaan oletuksena uid-parametri (lisää tämä palvelulle luovutettaviin attribuutteihin). Älä käytä, jos et tiedä mitä teet. Vain antiikkiset tai huonosti SAML:a tukevat palvelut voivat tarvita tätä ja niissäkin tapauksissa yleensä eivät tarvitse, vaikka näin väittävät.
  • Julkaise tuotantopalvelimille
    • Palvelu liitetään login.helsinki.fi tuotantopalvelimille, jolloin sille voi kirjautua millä vain HY:n käyttäjätunnuksilla
    • Tämä vaatii erikseen hyväksynnän Shibboleth-palvelun ylläpidolta
  • Julkaise testipalvelimille
    • Palvelu liitetään login-test.it.helsinki.fi testipalvelimelle. Lisätietoa tästä alla kohdassa TestipalveluSP-rekisteri (SAMLOIDC)
    • Muutokset tulevat voimaan automaattisesti ja voit määrittää testikäyttäjiä kohdassa Testikäyttäjät.
  • Palvelun käyttämä SAML-tuote
    • Tieto mitä SAML-tuotetta palvelu käyttää.
  • SP päivittää IdP-metatiedot automaattisesti
    • On suositeltavaa, että palvelu määritetään päivittämään IdP:n metadata automaattisesti. Esimerkiksi IdP:n sertifikaattipäivitykset eivät näin aiheuta ongelmia. Ohjeet tähän löytyvät osoitteesta Tuoteriippumaton SAML2-ohje.

Tekniset tiedot (OIDC)

OpenID Connect on token-pohjainen kirjautumistapa, jonka tekniset asetukset määritellään tässä kohdassa. Perustietoja OIDC:n toiminnasta esimerkiksi artikkelista https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1

  • Entity Id
    • Palvelun yksilöllinen tunniste. Järjestelmä luo oletuksena palvelulle satunnaisen tunnisteen, mutta se on mahdollista vaihtaa.
  • Grant types
    • Palvelulle sallitut tunnistustavat.
      • authorization_code flow on suositeltu tapa.
      • implicit flow on tuettuna, mutta tullaan poistamaan tulevaisuudessa vanhentuneena, kun tuki julkisen avaimen mentelmälle saadaan.
      • refresh_token sallii vanhentuneen access tokenin uusimisen ilman käyttäjän vuorovaikutusta, mutta refresh tokenin kesto on tällä hetkellä rajattu kahteen tuntiin.
    • Lisätietoja löydät esim: https://oauth.net/2/grant-types/
  • Response types
    • Palvelulle sallitut vastauustyypit:
      • code on authorization_code flown käyttämä ja valitse vain tämä, jos et tiedä mitä teet. Tällöin autorhization token ja ID token käydään hakemasas erillisestä endpointista, mikä on turvallisempaa.
      • id_token tarkoittaa, että myös id_token palautetaan suoraan.
      • token tarkoittaa, että myös auutorhization token palautetaan suoraan (yllä mainittu implicit flow käyttää tätä).
    • Lisätietoja löydät esim: https://medium.com/@darutk/diagrams-of-all-the-openid-connect-flows-6968e3990660
  • OIDC scopes
    • Palvelulle palautettavia tietoja.
    • openid scope lisätään palvelulle atuomaattisesti.
    • email scope palauttaa sähköpostiosoitteen ja profile scope nimitiedot. Voit myös erikseen pyytää attribuutteja yksittäisinä claimeina (attributes alla)
    • offline_access scope tarvitaan, jos haluat käyttää refresh tokeneita.
  • Palvelun tyyppi
    • web - perinteinen websivu.
    • natiivi - natiiviapp, joka kirjautuu suoraan, esim. mobiilisovellus tai puhdas javascript-sivu ilman backendiä.
  • Subject identifier
    • Jos palvelu haluaa tietyn tyyppisen sub-arvon, määritetään se tässä.
    • public on henkilön käyttäjätunnus ja pairwise on käyttäjälle luotu yksilöivä tunnus.
  • Julkaise tuotantopalvelimille
    • Palvelu liitetään login.helsinki.fi tuotantopalvelimille, jolloin sille voi kirjautua millä vain HY:n käyttäjätunnuksilla
    • Tämä vaatii erikseen hyväksynnän Shibboleth-palvelun ylläpidolta
  • Julkaise testipalvelimille
    • Palvelu liitetään login-test.it.helsinki.fi testipalvelimelle. Lisätietoa tästä alla kohdassa TestipalveluSP-rekisteri (SAMLOIDC)
    • Muutokset tulevat voimaan automaattisesti ja voit määrittää testikäyttäjiä kohdassa Testikäyttäjät.
  • OIDC tuote
    • Palvelun käyttämä OIDC-tuote, käytetään lähinnä tukitilanteissa ylläpidon apuna.
  • Luo uusi palvelun salaisuus
    • Lomakkeen tallentaessa luo palvelulle uuden jaetun salaisuuden.
  • Poista palvelun salaisuus
    • Poistaa palvelulta jaetun salaisuuden. Esim. käytettäessä implicit flowta tai julkisen avaimen menetelmää.
  • Näytä palvelun salaisuus -nappi
    • Näyttää palvelun salaisuuden sivulla, oletuksena piilotettu. Varmista ettei tämä joudu vääriin käsiin.

Attribuutit (SAML ja OIDC)

Palvelun tarvitsemat attribuutit ja niiden tarpeen lyhyt perustelu. OIDC-palveluiden kohdalla merkitse myös palautetaanko attribuutti Userinfo-kyselyssä, ID Tokenissa vai molemmissa.

Huomioi, että luovutettavat attribuutit näytetään käyttäjälle, kun tämä ensimmäistä kertaa kirjautuu palveluun. Perusteiden attribuuttien luovutukseen täytyy lisäksi löytyä myös tietosuojaselosteesta.

Attribuuttien luovutus on aina tarveperusteista. Jos epäilet onko joku attribuutti tarpeellinen, on vastaus melko varmasti ei.

Varmenteet (SAML)

Palvelun varmenteiden määrittäminen.

Suosittelemme vahvasti, että SP:n ja IdP:n välisessä liikenteessä ei käytetä samaa varmennetta kuin palvelun julkisilla sivuilla. Tämä helpottaa etenkin ylläpitoa, koska sertifikaattien muutoksia ei tarvitse sovittaa samaan. Lisäksi tietoturvan kannalta on hyödyllistä pitää nämä erillään, jolloin molempia ei tarvitse vaihtaa jos toinen vaarantuu. Lisätietoja esim. Hakan tiedotteessa asiasta.

Koska varmenne toimitetaan IdP:lle tämän järjestelmän kautta, ei sen tarvitse olla kolmannen osapuolen varmistama vaan itse allekirjoitettua voi hyvin käyttää.

SAML yhteysosoitteet (SAML)

Tarvittavat palvelun yhteysosoitteet IdP:lle. Käytännössä näitä tarvitaan seuraavat:

  • AssertionConsumerService urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST tarvitaan käytännössä aina autentikointiin.
  • SingleLogoutService urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect, jos palvelu tukee SLO:ta (kertauloskirjautuminen). Huom! Varmista, että palvelun uloskirjautuminen tapahtuu, jos käytetty SAML-sovellus kirjautuu ulos.

Muita on turha lisätä, jos et tiedä mitä olet tekemässä. Oletusasetuksella esimerkiksi Shibboleth SP lisää näitä kymmenkunta, josta käytännössä vain noita kahta käytetään.

Lähes poikkeuksetta näihin tarvitsee antaa vain osoite. Erillistä vastausosoitetta, järjestysnumeroa ja oletusvalintaa käytetään vain poikkeustapauksissa.

Paluuosoite (OIDC)

Palvelun sallimat paluuosoitteet. IdP ei lähetä vastausviestejä, jos paluuosoite ei vastaa palvelun ennalta rekisteröimää.

Yhteystiedot (SAML ja OIDC)

Palvelun yhteystiedot. Tekninen, hallinnollinen ja tukikontakti. Etenkin tekninen osoite on SP-rekisterin ylläpidon kannalta tärkeä.

Kannattaa käyttää palveluosoitteita eikä henkilökohtaisia sähköposteja, jos tämä on mahdollista.

Ylläpitäjät (SAML ja OIDC)

Tällä sivulla voit hallinnoida henkilöitä, joilla  on pääsy muokkaamaan palvelun tietoja.

Uusia ylläpitäjiä voi kutsua sähköpostitse, jolloin heille lähetetään 30 vuorokautta voimassa oleva aktivointikoodi.

Lisäksi oikeuksia voi lisätä IAM-ryhmille. Nämä ryhmät päivittyvät käyttäjille heidän seuraavan kerran kirjautuessa palveluun.

Testikäyttäjät (SAML ja OIDC, jos palvelu on julkaistu testipalvelimille)

Näkyy jos palvelu on julkaistu testipalveluun Technical Attributes-kohdassa.

Täällä voi määrittää käyttäjätunnuksia ja näiden attribuutteja testi IdP:lle. Lisätietoja alla, kohdassa TestipalveluSP-rekisteri (SAMLOIDC).

Näytä metatiedot (SAML ja OIDC)

Näyttää palvelun metadatan. Erikseen valittavana vahvistettu tai vahvistamaton metadata. Vahvistettu metadata on se, jota käytetään IdP:llä.

Palveluun on myöhemmin tulossa tuki erilliselle testi-IdP:lle, jossa palvelua voi testata itse generoituja käyttäjiä vastaan. Tällöin vahvistamaton metadata voidaan välittää automaattisesti testipalvelimelle.

Kirjautumistilastot

Näyttää tuotannossa olevilta palveluilta kirjautumismäärät päivittäin. Tiedot päivitetään noin puolentoista vuorokauden viiveellä.

Uuden SAML-palvelun lisääminen SP-rekisteriin

  1. Kirjaudu SP-rekisteriin.
    1. HY:n henkilökunnan pitäisi päästä suoraan palveluun, ongelmatilanteissa kannattaa olla yhteydessä atk-autentikointi@helsinki.fi.
  2. Valitse "Lisää uusi SAML palvelu" etusivulta.
  3. Anna palvelun Entity Id, nimi ja kuvaus. Jos lisäät palvelua tuotantopuolelle, anna myös tietosuojaselosteen (tai vastaavan informointiasiakirjan) URL sekä palvelun osoite Sovellussalkussa. Tallenna lomake.
    1. Palvelun tekniset tiedot voi lisätä myös lataamalla palvelun metatieto-XML:n. Tämän voi tehdä vain uutta palvelua lisätessä sivulta, jossa annetaan palelun perustiedot.
    2. HUOM. tuotantoon ei hyväksytä palveluita, joista puuttuu Sovellussalkun tai tietosuojainfon osoite. HY:n ulkopuolisten palveluiden osalta myös DPA:n tulee olla tehtynä.
  4. Varmenteet-sivulla lisää palvelun varmenne, tai varmenteet jos palvelu käyttää erillistä allekirjoitus- ja salausvarmennetta.
  5. SAML yhteysosoitteet-sivulla lisää palvelun yhteysosoitteet. SP ilmoittaa IdP:lle aina vastausosoitteen ja IdP varmistaa, että se löytyy tästä listauksesta.
    1. Pakollisena on AssertionConsumerService HTTP-POST -osoite.
    2. Lisäksi suositeltavana on SingleLogoutService HTTP-Redirect, jos palvelu tukee kertauloskirjautumista.
  6. Attribuutit-sivulla merkitse palvelun pyytämät attribuutit sekä peruste niiden käytölle.
  7. Yhteystiedot-sivulla lisää palvelun yhteysosoitteet. Vähintään teknisen tuen osoite, johin voidaan ilmoittaa kirjautumisongelmista, mutta myös hallinnollinen osoite on suositeltava.
  8. Tekniset tiedot-sivulla merkitse "Julkaise tuotantopalvelimille" tai "Julkaise testipalvelimille" sen mukaan onko palvelu menossa tuotanto vai testi-IdP:lle.
    1. Testi-IdP:n käytöstä, kuten testikäyttäjien lisäämisestä, löydät tietoa seuraavasta kohdasta.
    2. Tuotanto-IdP:lle menevät palvelut vahvistetaan erikseen IdP-ylläpidon toimesta. Kiireellisissä tapauksissa ole erikseen yhteydessä atk-autentikointi@helsinki.fi.

Uuden OIDC-palvelun lisääminen SP-rekisteriin

  1. Kirjaudu SP-rekisteriin.
    1. HY:n henkilökunnan pitäisi päästä suoraan palveluun, ongelmatilanteissa kannattaa olla yhteydessä atk-autentikointi@helsinki.fi.
  2. Valitse "Lisää uusi OIDC palvelu" etusivulta.
  3. Anna palvelun nimi ja kuvaus. Jos lisäät palvelua tuotantopuolelle, anna myös tietosuojaselosteen (tai vastaavan informointiasiakirjan) URL sekä palvelun osoite Sovellussalkussa. Tallenna lomake.
    1. HUOM. tuotantoon ei hyväksytä palveluita, joista puuttuu Sovellussalkun tai tietosuojainfon osoite. HY:n ulkopuolisten palveluiden osalta myös DPA:n tulee olla tehtynä.
  4. Paluuosoitteet-sivulla lisää palvelun käyttämät redirect_uri -paluuosoitteet.
  5. Attribuutit-sivulla merkitse palvelun pyytämät attribuutit "claims" ja halutaanko ne userinfo-kyselyllä vai ID tokenissa.
  6. Yhteystiedot-sivulla lisää palvelun yhteysosoitteet. Vähintään teknisen tuen osoite, johin voidaan ilmoittaa kirjautumisongelmista, mutta myös hallinnollinen osoite on suositeltava.
  7. Tekniset tiedot-sivulla:
    1. Valitse halutut grant_types -arvot. Oletuksena vain authorization_code.
    2. Valtise halutut paluuarvot. Yleensä code, jolloin autorhization token ja id token pyydetään erikseen saatavalla authorization code:lla (turvallisempi)
    3. Merkitse "Julkaise tuotantopalvelimille" tai "Julkaise testipalvelimille" sen mukaan onko palvelu menossa tuotanto vai testi-IdP:lle.
    4. Kirjaa talteen palvelimen client secret.

Palvelun poistaminen käytöstä

Jos palvelu ei ole tuotantokäytössä, voit poistaa palvelun Yhteenveto-sivun alareunasta.

Jos palvelu on tuotantokäytössä, tulee se ensin poistaa tuotantokäytöstä Tekniset tiedot sivulta ja odottaa, että ylläpito hyväksyy muutoksen. Tämän jälkeen voit poistaa palvelun Yhteenveto-sivulta.

Testipalvelu

HY:llä on käytössä testi-IdP, joka integroituu SP-rekisteriin. Lisätietoja palvelusta löytyy alasivulta Testipalvelu.