Shibboleth SP:n konfigurointi

Last modified by Jukka Karvonen on 2024/11/12 10:28

Palvelun pääasiallinen konfiguraatiotiedosto on /etc/shibboleth/shibboleth2.xml. Lisäksi attribute-map, attribute-policy, protocols ja secirty-policy määritetään erillisissä tiedostoissa.

Yleisiä suosituksia

IdP:n metadata

IdP:n metadata haetaan automaattisesti shibd-prosessin toimesta. Tästä tallennetaan myös paikallinen kopio, jota varten kannattaa luoda erillinen /etc/shibboleth/metadata kansio ja määrittää prosessille kirjoitusoikeudet tähän kansioon.

mkdir /etc/shibboleth/metadata
chmod 755 /etc/shibboleth/metadata
chown shibd:shibd /etc/shibboleth/metadata (HUOM. Ubuntussa prosessin käyttäjä ja ryhmä on _shibd)

Varmenteet

Shibbolethin käyttämä varmenne kannattaa luoda itse allekirjoitettuna ja varmistaa, että avaimeen on lukuoikeus vain prosessia ajavalla shibd-käyttäjällä. Alla olevassa esimerkissä luodaan varmenne palvelulle sp1.test.helsinki.fi. Nykyisin suositellaan luotavaksi erillinen varmenne allekirjoitukseen ja salaukseen.

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

shibboleth2.xml

Pääasiallinen konfiguraatiotiedosto. Tämä voi muuttua hieman versioiden mukana, eli uuden palvelun konfiguraatiossa kannattaa käyttää asennuspaketin mukana tulevaa tiedostoa ja muokata sitä.

Alla on näytetty esimerkkitiedosto ajettaessa palvelua Linux-palvelimilla. Pääasialliset muutokset Windows/IIS konfiguraation verrattuna on listattu erikseen.

Esimerkki

Alla on esimerkki Linux/Apache shibboleth2.xml:stä. Pääasialliset erot palvelun mukana tulevaan mallitiedostoon ovat seuraavat:

  • entitityID on nimetty palvelun mukaan ja määrityksiin on lisätty viestien allekirjoitus.
  • Sessions-kohdassa handlerSSL on päällä ja cookieProsps salatulla. Nämä ovat käytännössä pakollisia.
    • checkAddress lisäisi teoriassa turvallisuutta, mutta voi aiheuttaa ongelmia NAT:n takana olevissa palveluissa tai jos asikas tai palvelu tukee vain IPv4/IPv6 protokollia. consistentAddress on myös oletuksena päällä ja vastaa pitkälle samaan turvallisuusuhkaan kuin checkAddress, eli palvelu pyytää uuden kirjautumisen, jos session IP vaihtuu.
  • SSO:sta on poistettu Discovery protokollan määritys, jota tarvitaan vain useita IdP:tä käyttäessä (esim. Haka).
  • SLO (Single Logout):
    • Notify-kohdassa voi määrittää Shibboleth SP:n ilmoittamaan palvelulle ulsokirjautumispyynnöstä. Lisätietoja https://wiki.shibboleth.net/confluence/display/SP3/Notify
    • Jos palvelu on Apachen tasolta määritetty estämään käyttö kaikilta paitsi kirjautuneilta käyttäjiltä, ei sovellukselle välttämättä tarvitse ilmoittaa uloskirjautumisesta ja Notify-elementin voi poistaa.
    • Jos palvelu ei tue SLO:ta (Hakassa pakollinen!):
      • Poista "SAML2" Logout-tagien välistä, jätä jäljelle vain "Local".
      • Poista "Notify" rivi konfiguraatiosta.
  • Errors supportContact-kohdassa mainittu sähköpostiosoite näkyy käyttäjälle, jos Shibbolethissa tapahtuu odottamaton virhe. Tähän täytyy pistää palvelun teknisen ylläpidon osoite, ei esim. IdP ylläpidon osoitetta, koska selvitys vaatii pääsyn palvelun lokeihin.
  • Metadatan paikallinen tallenne haetaan yllä mainitun mukaisesti erilliseen kansioon. Lisäksi RequireValidUntil-arvo on kommentoitu pois, koska HY:n paikallisen IdP:n metadatassa ei tällä hetkellä anneta voimassaoloaikaa. Tämä on pakollinen Hakan metadataa käytettäessä.
  • CredentailResolveri-kohdassa varmenteet ja avaimet viittaavat edellä luotuihin tiedostoihin

<?xml version="1.0"?>
<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config" xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config" clockSkew="180">
  <OutOfProcess tranLogFormat="%u|%s|%IDP|%i|%ac|%t|%attr|%n|%b|%E|%S|%SS|%L|%UA|%a"/>
  <ApplicationDefaults entityID="https://sp1.test.helsinki.fi/sp" REMOTE_USER="eppn" signing="true" cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">
    <Sessions lifetime="28800" timeout="3600" relayState="ss:mem" checkAddress="false" handlerSSL="true" cookieProps="https">
      <SSO entityID="https://login.helsinki.fi/shibboleth">SAML2</SSO>
      <Logout>SAML2 Local</Logout>
      <LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1"/>
      <!-- <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/> -->
      <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
      <Handler type="Session" Location="/Session" showAttributeValues="false"/>
      <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
    </Sessions>
    <Errors supportContact="palvelun-kontakti-osoite@helsinki.fi" helpLocation="/about.html" styleSheet="/shibboleth-sp/main.css"/>
    <Notify Channel="front" Location="https://sp1.test.helsinki.fi/logout"/>
    <MetadataProvider type="XML" reloadInterval="7200" url="https://login.helsinki.fi/metadata/sign-hy-metadata-v2.xml" backingFilePath="/etc/shibboleth/metadata/sign-hy-metadata.xml">
      <MetadataFilter type="Signature" certificate="sign-login.helsinki.fi-v2.pem"/>
    </MetadataProvider>
    <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>
    <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
    <CredentialResolver type="File" use="signing" key="sp1-test-shib-signing-key.pem" certificate="sp1-test-shib-signing-cert.pem"/>
    <CredentialResolver type="File" use="encryption" key="sp1-test-shib-encrypt-key.pem" certificate="sp1-test-shib-encrypt-cert.pem"/>
  </ApplicationDefaults>
  <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
  <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
</SPConfig>

IIS:n kanssa huomioitavaa

Apache konfiguraatiossa Shibbolethia käyttävät sivustot ja sijainnit määritetään Apachen konfiguraatioissa. IIS:n puolella nämä määritetään suoraan Shibbolethin asetuksissa. Shibbolethin IIS-ohjeet löytää osoitteesta https://wiki.shibboleth.net/confluence/display/SP3/IIS

ISAPI-määrityksissä listataan IIS-site id:t, joissa Shibbolethia halutaan käyttää ja RequestMapper-määrityksissä kerrotaan tarkemmin kuinka ja missä sijainneissa. AccessControl-parametrillä voi tehdä määrityksiä käyttjän attribuuttien perusteella. Alla oleva esimerkki aiheuttaisi Shibboleth-session vaatimisen koko https://site1.example.org/ sivustolla, että https://site2.example.org:446/secure osoitteessa. Jälkimmäisessä vaadittaisiin lisäksi, että käyttäjällä on staff arvo affiliation-attribuutissa.

<?xml version="1.0"?>
<SPConfig...>
  ...
  <InProcess logger="native.logger">
    <ISAPI normalizeRequest="true" safeHeaderNames="true">
      <Site id="1" name="site1.example.org" port="443" scheme="https"/>
      <Site id="2" name="site2.example.org" port="446" scheme="https"/>
    </ISAPI>
  </InProcess>...    
  <RequestMapper type="Native">
    <RequestMap>
      <Host name="site1.example.org" scheme="https" port="443" authType="shibboleth" requireSession="true"/><Host name="site2.example.org" scheme="https" port="446">
        <Path name="secure" authType="shibboleth" requireSession="true">
          <AccessControl>
            <Rule require="affiliation">staff</Rule>
          </AccessControl>
        </Path>
      </Host>
    </RequestMap>
  </RequestMapper>
  ...
</SPConfig>

Huomioita ja ohjeita Path-määrityksistä löytää osoitteesta https://wiki.shibboleth.net/confluence/display/SP3/HowToRequestMap

attribute-map.xml

attribute-map.xml:ssä määritetään palvelun IdP:ltä hakemat attribuutit. Yksinkertaisimmillaan siinä on yksi REMOTE_USER arvoon haettava yksilöllinen tunniste, esim. uid tai eppn (eduPersonPrincipalName).

Esimerkki

Käyttäjältä parsitaan viisi yleistä attribuuttia, joista eppn-arvon varmistetaan olevan muotoa "arvo@scope". HY:n tapauksessa tämä on "uid@helsinki.fi".

<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
  </Attribute>
  <Attribute name="urn:oid:2.5.4.4" id="sn"/>
  <Attribute name="urn:oid:2.5.4.42" id="givenName"/>
  <Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="mail"/>
  <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" id="affiliation"/>
</Attributes>

Käytettävät attribuutit ja niiden viittaukset löydät erillisestä luettelosta.

attribute-policy.xml

attribute-policy.xml:ssä voi määrittää suodattimia saatuihin arvoihin, esim. määrättyjä arvoja tai regexiä käyttäen. Usein tarkistuksia ei kuitenkaan tehdä tässä vaan attribuutteja käsittelevässä sovelluksessa. Esimerkkitiedosto toimii useimmissa tapauksena soveltuvana politiikkana ja sieltä löytyy esimerkkejä muutoksiin.

Testipalvelun kanssa kannattaa huomioida ScopingRules-kohta, jota sovelletaan attribuutteihin, joihin on valittu attribute-map asetuksissa ScopedAttributeDecoder. Oletuksena tämä rajoittaa scopen IdP:n metadatan mukaisiin arvoihin, tarkoituksena on estää ettei esim. joku muu IdP voi antaa "@helsinki.fi" scopea. Testipalvelussa käyttäjien arvot, ml. scopen voi määrittää itse, jolloin jos haluat käyttää muuta kuin testipalvelun metadatassa olevaa "@helsinki.fi"-scopea, poista <Rule xsi:type="saml:AttributeScopeMatchesShibMDScope"/> määritys ScopingRules-kohdan alta.

Esimerkki protocols.xml

protocols.xml:ssä määritetään SP:n hyväksymät protokollat eri tilanteissa. Tämän voi myös usein jättää oletukselle. Käytettävät protokollaperheet määritetään shibboleth2.xml:n SSO-kohdassa (esimerkissä on jätetty vain SAML2).

Käytännössä kirjautumiseen tarvitaan vain SAML2 SSO HTTP-POST ja uloskirjautumiseen joko SAML2 Logout HTTP-Redirect tai Local Logout, riippuen tuetaanko SLO:ta. Tällöin tiedostoon kannattaa jättää vain seuraava sisältö:

<Protocols xmlns="urn:mace:shibboleth:2.0:native:sp:protocols">
  <!-- SAML 2.0 -->
  <Protocol id="SAML2">
    <Service id="SSO">
      <Initiator id="SAML2" />
      <Binding id="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" path="/SAML2/POST" />
    </Service>
    <Service id="Logout">
      <Initiator id="SAML2" />
      <Binding id="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" path="/SLO/Redirect" />
    </Service>
  </Protocol>
  <!-- Local Logout -->
  <Protocol id="Local">
    <Service id="Logout">
      <Initiator id="Local" />
    </Service>
  </Protocol>
</Protocols>

Palvelun metadata

shibboleth2.xml-tiedostossa on MetadataGenerator kohta kommentoitu pois, koska kyseessä on testikäyttöön tarkoitettu ominaisuus. Tällä saa kuitenkin palvelun tekniset pohjatiedot vietäväksi SP-rekisteriin, joten sen voi kommentoida palvelun konfiguroinnin jälkeen väliaikaisesti päälle metadatan latausta varten.

Kun palvelu on konfiguroitu ja määritetty moduulina Apacheen, mene osoitteeseen https://sp1.test.helsinki.fi/Shibboleth.sso/Metadata (tai mikä palvelun osoite onkaan). Automaattisesti luodusta metadatasta löytää mm. tekniset osoitteet, jotka tulee syöttää SP-rekisteriin. Uusi palvelu kannattaa luoda SP-rekisteriin tätä pohjatiedostoa käyttäen.