Tehdyt toimenpiteet
Shibboleth 2 Service Provider asennus
Shibboleth Service Provider -ohjelmiston versio 2.X (käytä aina viimeisintä versiota) on yhteensopiva Shibboleth 1.3:n kanssa sekä uutena ominaisuutena se tukee SAML 2:ta. Shibboleth 1.3 ja SAML 2 eivät ole keskenään yhteensopivia, mutta Shibboleth 2 SP -ohjelmistossa ne voivat olla samaan aikaan käytössä, jolloin molemmat protokollat ovat tuettuna samassa asennuksessa.
Helpointa asennus on suorittaa esimerkiksi Internet2:n toimittamien valmiiden Red Hat Linux rpm-pakettien tai Windows-asennusohjelmiston avulla. Lähdekoodista kääntämällä voidaan myös asennus suorittaa alustoille, joille ei ole valmiita asennuspaketteja. Saatavilla olevat versiot ohjelmistosta tarvittavine kirjastoineen voi ladata http://shibboleth.internet2.edu/downloads.html
Suurimmat erot aiempaan Shibboleth 1.3 versioon koskevat SAML2 tukea, joka tuo uusia konfiguraatiovaihtoehtoja mukanaan. Shibboleth on SAML1.1:sta laajennettu protokolla, joka ei ole yhteensopiva muiden kuin toisten Shibboleth toteutusten kanssa. Hakassa on käytetty koko sen olemassaolon ajan Shibbolethia tiedonsiirtoon.
Pääosiltaan Shibboleth 2 on hyvin samankaltainen kuin aiempi versio 1.3. SAML2 tuen käyttöönotto ei vaadi erityisiä toimenpiteitä, oletusasetuksilla Shibboleth 2 asennus ottaa myös SAML2:n käyttöön.
SAML2 määrittelyt löytyvät OASIS:in sivuilta: http://www.oasis-open.org/specs/index.php#samlv2.0
Asennus
Shibboleth-projektin omat asennusohjeet löytyvät https://wiki.shibboleth.net/confluence/display/SHIB2/Home. Niihin kannattaa ehdottomasti tutustua ennen asennusta. Sieltä löytyvät myös kaikki vaihtoehdot asetuksille sekä asetuksia, jotka eivät oletuksena ole lainkaan mukana. Apua asennuksessa tarjoaa myös Haka helpdesk osoitteessa haka@csc.fi.
Suositeltavimmat, joskaan eivät ainoat mahdolliset, alustat ovat Red Hat Enterprise Linux ja CentOS. Asennus on niille helpointa, joskin lähes mitä tahansa Linuxia voi käyttää, mutta asennuksessa saattaa tulla jonkin verran mutkia.
Koska Shibboleth ja SAML2 voivat toimia yhtäaikaa samassa Shibboleth-asennuksessa, on yleensä järkevää alusta asti ottaa myös SAML2 käyttöön Shibbolethin rinnalla. SAML2:n käyttöönotto ei vaadi erityisiä toimenpiteitä.
Esimerkissä on käytetty Red Hat Enterprise Linux käyttöjärjestelmää ja Apache WWW-palvelinta. Paketit on asennettu Internet2:n toimittamista rpm-paketeista rpm-komennon avulla.
Shibboleth vaatii useamman kirjaston toimiakseen:
- log4shib
- Xerces-C
- XML-Security-C
- XML-Tooling
- OpenSAML
Näistä on suositeltavaa aina käyttää versioita, jotka ovat saatavilla Shibboleth-projektin toimittamina. Joidenkin käyttöjärjestelmien mukana voi tulla versioita, jotka eivät kuitenkaan toimi täydellisesti Shibbolethin kanssa.
Vaadittujen kirjastojen asennuksen jälkeen voi asentaa itse Shibboleth Service Provider -ohjelmiston ja siirtyä sen konfigurointiin.
WWW-palvelin
Ennen Shibbolethin asennusta tulisi asentaa Apache palvelin https-protokollalla toimimaan valmiiksi. Shibboleth toimii www-palvelimen osana, palvelimelle kerrotaan ladattavan Shibboleth vaatima moduli (IIS:ssä filtteri) sekä määritellään mitkä hakemistot tai tiedostot halutaan suojattavan Shibbolethilla. Käyttäjän yrittäessä avata sisältöä, joka on määritelty www-palvelimessa Shibbolethissa suojatuksi ja johon käyttäjällä ei ole valmista sessiota, siirtyy hallinta shibd-prosessille. Shibd toimii Shibbolethin konfiguraation mukaisesti käynnistäen session luonnin asetusten mukaisesti.
Rpm-asennuksen yhteydessä asennus luo valmiin /etc/httpd/conf.d -hakemistoon tiedoston shib.conf, jossa ladataan tarvittava moduli sekä suojataan esimerkkinä secure-hakemisto WWW-palvelimessa.
# Load the SHIBBOLETH module
LoadModule mod_shib /usr/lib/shibboleth/mod_shib_20.so
<Location /secure>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>
Tarvittaessa kyseinen esimerkki löytyy myös /etc/shibboleth -hakemistosta apacheX.config tiedostosta Apachen version mukaisesti.
Shibboleth-prosessi
WWW-palvelimessa olevan modulin lisäksi tarvitaan shibd-prosessi. Red Hat asennuksessa sille on käynnistysskripti /etc/init.d -hakemistossa, jota voi joutua muokkaamaan oman ympäristön mukaiseksi.
Mikäli shibd:tä ajetaan jollain muulla käyttäjätunnuksella kuin root, tulee huolehtia että kyseisellä käyttäjällä on oikeudet lukea ja kirjoittaa log-tiedostoja ja /var/run -hakemistoon muodostuvia Shibbolethin käytönaikaisia tiedostoja.
Konfigurointi
Shibboleth Service Provider ohjelmiston konfiguraatio tiedostot sijaitsevat /etc/shibboleth -hakemistossa. Pääasiallinen Shibbolethin konfigurointi tehdään shibboleth2.xml -tiedostossa. Alla olevat esimerkit ovat osia shibboleth2.xml -tiedostosta, jollei toisin ole mainittu. Suurin osa muutoksista ei vaadi shibd-prosessin uudelleenkäynnistystä, mutta uudelleenkäynnistämisellä saa logeihin helposti tarvittavat tiedot ongelmatilanteissa.
Koko shibboleth2.xml -tiedoston dokumentaatio on saatavilla Shibboleth 2 Wikissä.
Session luonti
Käyttäjältä tulevat sivunlatauspyynnöt, jotka on WWW-palvelimessa määritetty käsiteltäväksi Shibbolethissa, lajitellaan Shibbolethin asetuksissa noudattamaan tiettyä käytöstä. Yksi SP-palvelin voi siis sisältää useita Shibboleth-suojattuja palveluita, joilla on erilainen käytös esim. WAYF-ohjauksen, sessioiden kestojen ja palvelun nimen suhteen. Esimerkissä hakemistoon secure-kohdistuvat pyynnöt saavat oletusluokan default mukaisen käsittelyn.
Alla olevaan palvelimen.nimi.fi on se, josta käyttäjän selain tietoa hakee ja on konfiguroitu www-palvelimeen. Eli jos palvelimessa abc123.domain.fi toimii palvelu nimeltä asiapalvelu.domain.fi, käytetään tässä palvelun nimeä. Hakemiston eli alla secure tulisi puolestaan vastata Apachen konfiguraatiossa suojattavaa hakemistoa.
<RequestMapper type="Native">
<RequestMap applicationId="default">
<Host name="palvelimen.nimi.fi">
<Path name="secure" authType="shibboleth" requireSession="true"/>
</Host>
</RequestMap>
</RequestMapper>
Yllä olevassa on määritetty mikä sisältö saa default-luokan, seuraavassa määritellään kyseisen luokan ominaisuudet, joista tärkeimpänä entityID eli palvelun nimi. EntityID voi teknisesti olla mikä tahansa merkkijono, mutta sen tulee käyttöympäristössään uniikki. Suositeltava lähtokohta esim. Hakaa ajatellen on palvelimen nimeen perustuva.
<ApplicationDefaults id="default" policyId="default"
entityID="https://palvelimen.nimi.fi/shibboleth"
homeURL="https://palvelimen.nimi.fi"
REMOTE_USER="eppn persistent-id targeted-id"
signing="false" encryption="false">
<Sessions lifetime="28800" timeout="3600" checkAddress="false"
handlerURL="/Shibboleth.sso" handlerSSL="false"
exportLocation="http://localhost/Shibboleth.sso/GetAssertion"
idpHistory="false" idpHistoryDays="7">
Käyttäjän pyynnön vaatiessa tunnistautumisen, voidaan käyttäjä ohjata valitsemaan oma tunnistuslähteensä tai ohjata suoraan johonkin tunnistuspalveluun. Alla olevassa ohjataan uuteen DS-palveluun kaikissa tilanteissa.
<SSO
discoveryProtocol="SAMLDS" discoveryURL="https://DS-PALVELUN.OSOITE.FI/SHIBBOLETH/DS">
SAML2 SAML1
</SSO>
Yllä oleva DS-palvelu on mahdollista ohittaa esim. rakentamalla linkki(url), jota käytettäessä palveluun kirjautuva käyttäjä ohjataan tunnistautumaan suoraan tiettyyn tunnistuspalveluun. Alla olevaa esimerkkilinkkiä käytettäessä käyttäjä ohjautuu CSC:n attribuuttitestipalveluun CSC:n IdP-palvelimen kautta.
<HTML>
...
<a href="https://talli.funet.fi/Shibboleth.sso/DS?target=https://talli.funet.fi/haka/attribute-test&
entityID=https://idp.csc.fi/idp/shibboleth">Linkki</a>
...
</HTML>
Varmenteet
Shibboleth Service Provider 2:n asennus luo tarvittavan varmenteen testausta varten /etc/shibboleth -hakemistoon sp-key.pem ja sp-cert.pem tiedostoihin. Niiden sijainti tiedostojärjestelmässä konfiguroidaan seuraavasti.
<CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
Hakassa käytetään Soneran tai Terenan allekirjoittamia varmenteita, mutta testauksessa voi käyttää mitä tahansa varmenteita mm. niitä, jotka Shibboleth-asennus tekee /etc/shibboleth -hakemistoon.
Metadata
Kukin SP tarvitsee tiedon muista Shibboleth-palvelimista, joihin SP luottaa. Nämä palvelimet kuvataan metadatoissa, Hakan metatiedon löydät luottamusverkoston metatieto -sivuta. Kunkin SP:n tulee huolehtia että sillä on käytössään tuorein metadata, sekä käyttäjien palvelimiseksi sekä tietoturvan vuoksi.
Suositeltava tapa helpottamaan päivittämistä on asettaa SP hakemaan metatieto suoraan verkosta ja samalla tarkistaa metadatan allekirjoitus allekirjoittavan varmenteen avulla. Allekirjoittavan varmenteen voi hakea Hakan metadatasivulta ja tallentaa sen paikalliseen tiedostojärjestelmään. Metadatasta tehdään varmuuskopio paikalliselle levylle, mikäli jostain syystä yhteys verkossa olevaan metadatatiedostoon katkeaa.
<MetadataProvider type="XML"
uri="https://haka.funet.fi/metadata/haka-metadata.xml"
backingFilePath="haka_metadata_signed_local.xml"
reloadInterval="7200">
<SignatureMetadataFilter
certificate="/etc/shibboleth/haka-metadata-signing.crt.pem"/>
</MetadataProvider>
SP voi käyttää metadataa suoraan tiedostojärjestelmästä:
<MetadataProvider type="XML" file="metadata.xml"/>
Erilaisia tapoja hakea metadataa voi yhdistää eli voi asettaa SP:n hakemaan Haka-metatiedon verkosta ja pitää käsin ylläpidettävää metadataa sen rinnalla esim. organisaation sisäisiä palvelmia varten. Tällöin ne kerätään <MetadataProvider type="Chaining"> elementin sisään omina MetadataProvider elementteinään.
Service Providerin metadatan eli tiedot, jotka sen kanssa toimivat IdP:t tarvitsevat voi julkaista suoraan SP:ssä. Julkaistusta metadatasta saa tarvittavat tiedot palvelun liittämiseen IdP-palvelimeen.
<Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>
Attribuuttien hallinta
SP:n saamat attribuutit IdP:sta käsitellään SP:ssa ennen niiden luovuttamista tunnistuksen vaativalle sovellukselle. Attribuuttien käsittelyn asetukset on määritelty attribute-map.xml ja attribute-policy.xml -tiedostoissa. Niiden sijanti konfiguroidaan:
<!-- Map to extract attributes from SAML assertions. -->
<AttributeExtractor type="XML" path="attribute-map.xml"/>
<!-- Default filtering policy for recognized attributes, lets other data pass.-->
<AttributeFilter type="XML" path="attribute-policy.xml"/>
Ensin mainitussa määritellään mitä nimiä attribuuteista käytetään SP:n ja IdP:n välisessä tiedonsiirrossa sekä millä nimellä kukin attribuutti luovutetaan sovellukselle. SP:n ja IdP:n välisessä tietojensiirrossa käytettävät urn- ja oid-muotoiset nimet on määritetty Hakassa käytettävässä FunetEduPerson-skeemassa. Shibboleth 1.3 profiililla käytetään urn-nimiä ja SAML2-profiilissa oid-nimiä.
Nimi, jolla attribuutti luovutetaan sovellukselle on SP:n asennuksessa vapaasti valittavissa omien mieltymysten mukaisesti. Alla olevassa esimerkissä on sukunimi-attribuutti, jonka urn ja oid löytyvät siis skeemasta, määritetty esiintymään SHIB_sn nimisessä ympäristömuuttujassa. Sovelluksessa niitä käsitellään kuten muitakin ympäristömuuttujia sovelluksen toteuttavasta ohjelmointikielestä riippuen.
<Attribute name="urn:mace:dir:attribute-def:sn" id="SHIB_sn"/>
<Attribute name="urn:oid:2.5.4.4" id="SHIB_sn"/>
Attribute-policy.xml -tiedostossa attribuutteille voidaan lisäksi luoda sääntöjä SP:ssä mikäli halutaan tehdä tarkistuksia niiden sisällöille Shibbolethissa ennen niiden luovuttamista eteenpäin. Attribuuteista voidaan esim. tarkistaa onko attribuutin scope eli attribuutti@domain.fi attribuutin @-merkin jälkeinen osa sama kuin metadatassa on määritetty kyseiselle IdP:lle.
<afp:PermitValueRule id="ScopingRules" xsi:type="AND">
<Rule xsi:type="NOT">
<Rule xsi:type="AttributeValueRegex" regex="@"/>
</Rule>
<Rule xsi:type="saml:AttributeScopeMatchesShibMDScope"
xmlns:saml="urn:mace:shibboleth:2.0:afp:mf:saml"/>
</afp:PermitValueRule>
<afp:AttributeRule attributeID="SHIB_eppn">
<afp:PermitValueRuleReference ref="ScopingRules"/>
</afp:AttributeRule>
Attribute-map.xml esimerkkitiedosto, johon on koottu FunetEduPerson-skeeman mukaisia attribuutteja. Selkeyden vuoksi voi tiedostosta karsia ne attribuutit pois, joita palvelussa ei lainkaan käytetä.
Sirrettyjä attribuutteja ja muitakin Shibboleth istunnon tietoja voi tarkastella diagnostikkapalvelun avulla. Ottamalla käyttöön esimerkin mukaisen shibboleth2.xml -tiedostossa, löytyy tietoja istunnosta osoitteesta https://hostname/Shibboleth.sso/Session
<!-- Session diagnostic service. -->
<Handler type="Session" Location="/Session" showAttributeValues="true" />
Pääsynvalvonta
Web-sovelluksen muokkaaminen Shibboleth-tunnistusta käyttäväksi on aina tapauskohtaista. Yksinkertaisimmillaan se voi olla hyvin helppoa (suojataan sovelluksen sijainti Shibbolethilla ja tehdään sopiva attribuuttipohjainen sääntö) ja vaikeimmillaan työlästä (tehdään skriptejä, jotka vastaanottavat Shibboleth tunnistustiedot ja ohjaavat tietoja eri paikkoihin) tai jopa mahdotonta.
Attribuuttien sisältöihin perustuvaa pääsynvalvontaa voi suorittaa usealla eri tavalla:
- Apache www-palvelimen avulla
- Shibbolethin omalla XML-muotoisella tavalla IIS:n tai Apachen kanssa
- sovelluksessa ohjelmointikielellä ympäristömuuttujissa olevien attribuuttien avulla
Näistä kaksi ensimmäistä tapaa soveltuvat paremmin yksinkertaisiin tapauksiin, joissa esim. tarkistetaan että käyttäjällä jokin attribuutti sisältää tietyn sisällön. Viimeinen tapa soveltuu käyttöön laajemmissa sovelluksissa, joissa on jokin ohjelmointikieli käytössä. Esimerkit käytöstä: http://www.switch.ch/aai/support/serviceproviders/sp-access-rules.html
Loki-tiedostot
Shibboleth tekee lokia suorittamistaan tapahtumista /var/log/shibboleth -hakemistoon. Yleensä kaikkiin virheisiin ja ongelmiin löytyy syy lokitiedostoista.
Lokien käyttäytymistä hallitaan /etc/shibboleth -hakemiston shibd.logger ja native.logger asetustiedostoissa. Yleensä vaaditaan logien asettaminen debug-tilaan, jotta ongelmatilanteista saadaan selvyys. Tuotantokäytössä ei kuitenkaan tulee debug-tilaa pitää päällä, pitkäkestoinen debug-tila voi aiheuttaa kaatumisia.
# set overall behavior
log4j.rootCategory=DEBUG, shibd_log
Mikäli lokitiedostoihin ei tule mitään, kannattaa ensimmäiseksi tarkistaa onko shibd-prosessilla oikeus kirjoittaa lokien sijantipaikkaan. Ongelmat voivat myös esiintyä ennen kuin toiminta siirtyy Shibbolethille, jolloin WWW-palvelimen lokeista voi olla hyötyä.
