====== Pokročilý návod k Shibboleth SP ======

Tato stránka popisuje pokročilou konfiguraci Shibboleth SP, která je sice pro drtivou většinu služeb zcela zbytečná, ale své uplatnění v ojedinělých případech najde.

===== Více domén pro jednu službu =====

Má-li být služba dostupná pod více doménovými jmény -- **platí i pro adresu s "www" a bez "www" před doménou** -- lze toho docílit pohým přidáním odpovídajících elementů ''<AssertionConsumerService>'' do metadat služby v rámci federace.

V základním [[cs:tech:sp:shibboleth|návodu]] je popsána úprava elementu ''[[cs:tech:sp:shibboleth#metadata_sluzby|<Handler>]]'' týkajícího se metadat:

<code xml>
<Handler type="MetadataGenerator" Location="/Metadata" signing="false" template="metadata-template.xml"/>
</code>

Následující úpravou v souboru ''metadata-template.xml'' zajistíme, že služba bude dostupná na doménách www.example.org, www.example.com a www.example.net pouhým doplněním odpovídajících elementů ''<AssertionConsumerService>'':

<code xml>
<?xml version="1.0" encoding="utf-8" ?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">

    <md:SPSSODescriptor>
  
        <!-- Další endpointy pro alternativní DNS jména -->
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
            Location="https://www.example.org/Shibboleth.sso/SAML2/POST" index="1"/>

        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
            Location="https://www.example.com/Shibboleth.sso/SAML2/POST" index="2"/>

        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
            Location="https://www.example.net/Shibboleth.sso/SAML2/POST" index="3"/>
        
    </md:SPSSODescriptor>

</md:EntityDescriptor>
</code>

Samozřejmostí je, že všechny uvedené domény musí být pomocí DNS záznamů směrovány na jeden a ten samý server, kde Shibboleth SP provozujeme.

<WRAP tip>
Element ''DiscoveryResponse'' doporučujeme z finálních metadat odebrat. Je to nejjednodušší způsob, jak vyřešit bezpečnostní kontrolu na WAYFu.
</WRAP>

===== Více služeb pod jedním Shibboleth démonem (jedno entityID) =====

Chceme-li provozovat pod jedním Shibboleth démonem (proces/služba ''shibd'') více služeb na různých doménách v rámci federace, je to možné. Tato možnost se hodí například pro situace, kdy chceme hostovat více instancí nějaké služby na jednom (fyzickém nebo virtuálním) serveru. Typickou záležitostí je tzv. DokuWiki farming, kdy máme jeden operační systém, jednu instalaci DokuWiki, ale několik různých instancí s vlastním vzhledem, stránkami, použitými rozšířeními atd.

Konfiguraci vysvětlím na následujícím příkladu: Máme virtuální server na doméně ''blackhole.example.org'' s doménovými aliasy ''blackhole1.example.org'' a ''blackhole2.example.org''.

V konfiguračním souboru ''/etc/shibboleth/shibboleth2.xml'' přidáme metadatovou šablonu přidáním ''template="metadata-template.xml"'':

<code xml>
<Handler type="MetadataGenerator" Location="/Metadata" signing="false" template="metadata-template.xml"/>
</code>

V šabloně ''/etc/shibboleth/metadata-template.xml'' pak uvedeme následující:

<code xml>
<?xml version="1.0" encoding="utf-8" ?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">

  <md:SPSSODescriptor>

    <md:Extensions>
      <!-- UIInfo -->
        <mdui:UIInfo xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">
        <mdui:DisplayName xml:lang="en">Black Hole</mdui:DisplayName>
        <mdui:DisplayName xml:lang="cs">Černá díra</mdui:DisplayName>
        <mdui:Description xml:lang="en">Black Hole -- testing Shibboleth SP</mdui:Description>
        <mdui:Description xml:lang="cs">Černá díra -- testovací Shibboleth SP</mdui:Description>
        <mdui:InformationURL xml:lang="en">https://blackhole.example.org/en</mdui:InformationURL>
        <mdui:InformationURL xml:lang="cs">https://blackhole.example.org/cs</mdui:InformationURL>
        <mdui:Logo height="128" width="128">https://blackhole.example.org/logo.png</mdui:Logo>
      </mdui:UIInfo>
    </md:Extensions>

    <!-- ------------------------- -->
    <!-- alternative DNS hostnames -->
    <!-- ------------------------- -->

    <!-- blackhole1.example.org -->
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://blackhole1.example.org/Shibboleth.sso/SAML2/POST" index="1"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign" Location="https://blackhole1.example.org/Shibboleth.sso/SAML2/POST-SimpleSign" index="2"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="https://blackhole1.example.org/Shibboleth.sso/SAML2/Artifact" index="3"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS" Location="https://blackhole1.example.org/Shibboleth.sso/SAML2/ECP" index="4"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" Location="https://blackhole1.example.org/Shibboleth.sso/SAML/POST" index="5"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" Location="https://blackhole1.example.org/Shibboleth.sso/SAML/Artifact" index="6"/>

    <!-- blackhole2.example.org -->
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://blackhole2.example.org/Shibboleth.sso/SAML2/POST" index="7"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign" Location="https://blackhole2.example.org/Shibboleth.sso/SAML2/POST-SimpleSign" index="8"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="https://blackhole2.example.org/Shibboleth.sso/SAML2/Artifact" index="9"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS" Location="https://blackhole2.example.org/Shibboleth.sso/SAML2/ECP" index="10"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post" Location="https://blackhole2.example.org/Shibboleth.sso/SAML/POST" index="11"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" Location="https://blackhole2.example.org/Shibboleth.sso/SAML/Artifact" index="12"/>

  </md:SPSSODescriptor>
 
  <md:Organization>
    <md:OrganizationName xml:lang="en">EXAMPLE, a. l. e.</md:OrganizationName>
    <md:OrganizationName xml:lang="cs">EXAMPLE, z. s. p. o.</md:OrganizationName>
    <md:OrganizationDisplayName xml:lang="en">EXAMPLE</md:OrganizationDisplayName>
    <md:OrganizationDisplayName xml:lang="cs">EXAMPLE</md:OrganizationDisplayName>
    <md:OrganizationURL xml:lang="en">http://www.example.org/</md:OrganizationURL>
    <md:OrganizationURL xml:lang="cs">http://www.example.net/</md:OrganizationURL>
  </md:Organization>

  <md:ContactPerson contactType="technical">
    <md:GivenName>John</md:GivenName>
    <md:SurName>Doe</md:SurName>
    <md:EmailAddress>mailto:john.doe@example.org</md:EmailAddress>
  </md:ContactPerson>

</md:EntityDescriptor>
</code>

Stačí pak v Apachi definovat pro zbývající doménová jména (blackhole1.example.org a blackhole2.example.org) konfiguraci, aktivovat ji a restartovat Apache. Je třeba nezapomenout na aktualizaci metadat ve federaci.

Na všech doménách pak bude k dispozici samostatné přihlašování pomocí Shibbolethu. Služby budou v rámci federace vystupovat pod jedním entityID, avšak všechny služby budou mít samostatné přihlášení (''/Shibboleth.sso/Login''), sezení (''/Shibboleth.sso/Session'') atd.

===== Více služeb pod jedním Shibboleth démonem (více entityID) =====

Chceme-li provozovat pod jedním Shibboleth démonem (proces/služba ''shibd'') více služeb na stejné doméně v rámci federace, avšak s rozlišnými entityID, je to možné. Hodí se to např. pro situace, kdy chceme hostovat více instancí nějaké služby na jednom (fyzickém nebo virtuálním) serveru. Typickou záležitostí je jedna služba dvě různé federace s různými metadaty a entityID.

Konfiguraci vysvětlím na následujícím příkladu: Máme virtuální server ''blackhole.example.org'' a pro produkční federaci má služba entityID ''<nowiki>https://blackhole.example.org/shibboleth</nowiki>'', zatímco pro testovací je to ''<nowiki>https://blackhole.example.org/shibboleth/cztestfed</nowiki>''.

V konfiguračním souboru ''/etc/shibboleth/shibboleth2.xml'' nakonfigurujeme vše pro federaci //eduID.cz// podle [[:cs:tech:sp:shibboleth|návodu]] a následně provedeme tyto úpravy:

<code xml>
<SPConfig ...>

  <ApplicationDefaults ...>
  
    <!-- czTestFed -->
    <ApplicationOverride id="cztestfed" entityID="https://blackhole.example.org/shibboleth/cztestfed">
    
      <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
        checkAddress="false" handlerSSL="true" cookieProps="https"
        handlerURL="/cztestfed/Shibboleth.sso">
        
        <SSO discoveryProtocol="SAMLDS" discovery="https://ds.eduid.cz/wayf-cztestfed/">
          SAML2
        </SSO>
        
      </Sessions>

      <MetadataProvider type="XML" validate="true"
        url="https://metadata.eduid.cz/entities/cztestfed"
        backingFilePath="cztestfed.xml" maxRefreshDelay="900">
 
        <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
        <MetadataFilter type="Signature" certificate="metadata.eduid.cz.crt.pem" verifyBackup="false"/>
 
        <DiscoveryFilter type="Blacklist" matcher="EntityAttributes" trimTags="true" 
            attributeName="http://macedir.org/entity-category"
            attributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
            attributeValue="http://refeds.org/category/hide-from-discovery" />
      </MetadataProvider>
      
    </ApplicationOverride>
  
  </ApplicationDefaults>

</SPConfig>
</code>

V konfiguraci Apache pak přidáme novou lokaci:

<code apache>
<VirtualHost *:443>
  ServerName        blackhole.example.org
  # ...
  
  <Location /cztestfed/>
    AuthType           shibboleth
    Require            shibboleth
    ShibRequestSetting applicationId cztestfed
  </Location>
</VirtualHost>
</code>

Nyní restartujeme Shibboleth a Apache:

<code bash>
systemctl restart shibd
systemctl restart apache2
</code>

Na adrese ''<nowiki>https://blackhole.example.org/Shibboleth.sso/Metadata</nowiki>'' nalezneme metadata pro produkční federaci a na adrese ''<nowiki>https://blackhole.example.org/cztestfed/Shibboleth.sso/Metadata</nowiki>'' nalezneme metadata pro testovací federaci czTestFed. Stačí tedy metadata zaregistrovat do odpovídajících federací a vše je hotovo.

Služba běžící v našem případě výše s jiným entityID nemusí být součástí jiné federace. V případě, že byste potřebovali v tomto ohledu radu, pište na [[info@eduid.cz]].

===== Vyžadování atributů =====

Pokud máme službu, která vyžaduje určité atributy bez nichž nebude fungovat (v tomto příkladě //uniqueId//, //mail// a //cn//), můžeme jejich vyžadování zanést do konfigurace. Pokud se následně přihlásí uživatel, jehož IdP vyžadované atributy neuvolnilo, můžeme mu zobrazit uživatelsky přívětivou webovou stránku s informacemi, které atributy chybí, a koho případně kontaktovat.

<code xml>
<SPConfig ...>

  <ApplicationDefaults
    entityID="https://sp.example.org/shibboleth"
    REMOTE_USER="uniqueID"
    sessionHook="/Shibboleth.sso/AttrChecker"
    metadataAttributePrefix="Meta-">

    <Sessions ...>

      <Handler
        type="AttributeChecker"
        Location="/AttrChecker"
        template="attrChecker.html"
        attributes="uniqueId mail cn"
        flushSession="true" />

    </Sessions>

    <AttributeExtractor
      type="Metadata"
      DisplayName="displayName"
      InformationURL="informationURL">

        <ContactPerson
          id="Technical-Contact"
          contactType="technical"
          formatter="$EmailAddress"/>

    </AttributeExtractor>

  </ApplicationDefaults>

</SPConfig>
</code>

Pro ''<Handler>'' je možné použít i jiný zápis, který umožňuje specifičtější pravidla a používání logických //AND// a/nebo //OR//. Bližší informace naleznete v [[https://wiki.shibboleth.net/confluence/display/SP3/Attribute+Checker+Handler|dokumentaci]].

Dále je nutné do souboru ''attrChecker.html'' (na vhodné místo samozřejmě) přidat seznam atributů, které byly vyžadovány, ale služba je od IdP neobdržela -- v tomto případě byly vyžadovány atributy //uniqueId//, //mail// a //cn//. Stránku ''attrChecker.html'' můžete samozřejmě libovolně upravit a to včetně kaskádových stylů, aby vzhled zapadal do vzhledu služby.

<code html>
<p>
Your identity provider (<a href="<shibmlp Meta-informationURL/>"><shibmlp Meta-displayName/></a>) didn't release sufficient user information. These are the missing attributes:
</p>

<ul>
<shibmlpifnot uniqueId><li>uniqueId</li></shibmlpifnot>
<shibmlpifnot mail><li>mail</li></shibmlpifnot>
<shibmlpifnot cn><li>cn</li></shibmlpifnot>
<shibmlpifnot cn><li>givenName</li></shibmlpifnot>
<shibmlpifnot cn><li>sn</li></shibmlpifnot>
</ul>

<p>
You can contact the IdP's administrator at the following <a href="mailto:<shibmlp Meta-Technical-Contact/>?subject=Missing%20attributes&body=Hello,%0A%0AThe%20application%20at%20SPECIFY_APPLICATION_URL%20requires%20user%27s%20eduPersonUniqueId%2C%20cn%20and%20mail%20attributes%20available%20in%20order%20to%20allow%20the%20user%20to%20log%20in.">email address</a>.
</p>
</code>