cs:tech:idp:common

Tento návod je již zastaralý a zůstává zde spíše jen pro dokumentačí důvody. Přejděte na aktuální návod.


Instalace Shibboleth IdP 2.4 (Linux) - Tomcat + Apache frontend

Požadavky

  • Java 6 nebo vyšší
  • Tomcat 6.0.17 nebo vyšší (ale ne 7)
  • Apache 2.2.x s modulem mod_proxy_ajp
  • Shibboleth IdP 2.x - k dispozici zde

Upgrade

Pokud aktualizujete Shibboleth IdP, prostudujte si návody:

Příprava

Shibboleth

Veškeré komponenty nainstalujeme v adresáři /opt. Pro účely instalace vytvoříme dočasný adresář, kde stáhneme a rozbalíme balík Shibboleth IdP 2:

# mkdir /opt/tmp
# cd /opt/tmp
# wget http://www.shibboleth.net/downloads/identity-provider/latest/shibboleth-identityprovider-2.x.x-bin.tar.gz
# tar xvfz shibboleth-identityprovider-2.x.x-bin.tar.gz

Java

Je potřeba nastavit proměnnou prostředí JAVA_HOME. Je dobré toto nastavení zapsat do .bashrc či .bash_profile.

export JAVA_HOME="/usr/lib/jvm/java-6-sun/jre"

Apache Tomcat

server.xml

V hlavní konfiguraci server.xml je potřeba nastavit AJP konektor (případně zakomentovat ostatní, které se nepoužívají):

    <!-- Define an AJP 1.3 Connector on port 8009 -->
    <Connector port="8009" address="127.0.0.1" enableLookups="false"
               tomcatAuthentication="false" protocol="AJP/1.3" redirectPort="443" />

Endorsed knihovny

Shibboleth IdP přichází s vlastní implementaci Xalan a Xerces knihoven. Ty je potřeba zkopírovat z distribuce do tzv. „endorsed“ adresáře v CATALINA_HOME.

:!: U Tomcat 6 došlo k změně a adresář $CATALINA_HOME/common/endorsed se nevytváři a nezpracovává implicitně. Místo toho je potřeba vytvořit adresář $CATALINA_HOME/endorsed (např. v Debianu je to /usr/share/tomcat6/endorsed/) a nakopírovat tam soubory z endorsed/ adresáře z distribuce Shibboleth IdP.

Pokud Tomcat z nějakých důvodů nenachází „endorsed“ knihovny anebo pokud je máte v jiném adresáři, je potřeba do startovacích skriptu nastavit, aby se Tomcat spouštěl s parametrem -Djava.endorsed.dirs=<dir>, kde <dir> je adresář obsahující „endorsed“ knihovny.

Proměnné prostředí

Do proměnné prostředí JAVA_OPTS (obsahuje parametry pro spouštění Javy) je potřeba přidat následující parametry:

  • -Xmx###m - kde ### je maximální velikost paměti v MB, kterou může alokovat Tomcat. Doporučená hodnota je minimálně 512 MB.
  • -XX:MaxPermSize=### - kde ### je maximální velikost paměti pro generování permanentních objektů. Doporučená hodnota je 128 MB.

Například v Debianu stačí do souboru /etc/default/tomcat6 přidat:

JAVA_OPTS="-Djava.awt.headless=true -Xmx512M -XX:MaxPermSize=128M -Dcom.sun.security.enableCRLDP=true"

Podrobné informace o ladění výkonu JVM najdete na stránkách Internet2.

Context Deployment Fragment

Obvykle, pro nasazení aplikace u Tomcat serveru je potřeba zkopirovat příslušný WAR soubor do adresáře webapps, kde ho Tomcat rozbalí. Pro pohodlí je lepší místo toho sdělit serveru umístění WAR souboru. Tomcat pak daný soubor sleduje a při každé jeho změně automaticky obnovuje aplikaci. Je to vhodné zvlášť v případech, kdy ladíte různá nastavení nebo šablony přihlašovacích stránek. Po každé změně stačí spustit znovu instalační skript a o zbytek se postará Tomcat.

K tomu je potřeba vytvořit soubor CATALINA_BASE/conf/Catalina/localhost/idp.xml s obsahem:

<Context docBase="IDP_HOME/war/idp.war"
         privileged="true"
         antiResourceLocking="false"
         antiJARLocking="false"
         unpackWAR="false" 
         swallowOutput="true" 
         cookies="false" />

Kde CATALINA_BASE je pracovní adresář Tomcat (například v Debianu je CATALINA_BASE=/var/lib/tomcat6/) a IDP_HOME je adresář, kde nainstalujeme Shibboleth IdP (/opt/shibboleth-idp).

Podrobnější informace najdete na stránkach Shibboleth Wiki.

Shibboleth IdP

Úpravy před instalaci

Běhěm instalace se vygenerují konfigurační soubory, metadata a self-signed certifikát. Kromě toho se vytvoří servletový balíček WAR, který je pak připraven pro použití v servletovém kontejneru (Tomcat). Pokud chceme provést změny v konfiguraci servletu nebo upravit některé JSP soubory, musíme to udělat před spuštěním instalace. Pokud chceme provést změny dodatečně, musíme po každé změně znovu spustit instalační skript. Skript zjistí, že už existuje instalace IdP a zeptá se, zda chceme přepsat existující instalaci. Při negativní odpovědi skript pouze vytvoří nový WAR.

Příklad změny konfigurace může být nastavení přistupových práv pro stránku zobrazující stavové informace. Výchozí nastavení dovoluje tuto stránku zobrazit pouze z localhostu. V nastavení servletu lze nastavit seznam IP rozsahu v CIDR formátu, z kterých lze k této stránce přistoupit. Nastavení servletu je v souboru src/main/webapp/WEB-INF/web.xml:

    <!-- Servlet for displaying IdP status. -->
    <servlet>
        <servlet-name>Status</servlet-name>
        <servlet-class>edu.internet2.middleware.shibboleth.idp.StatusServlet</servlet-class>
 
        <!-- Space separated list of CIDR blocks allowed to access the status page -->
        <init-param> 
            <param-name>AllowedIPs</param-name>
            <param-value>127.0.0.1/32 ::1/128 192.168.0.0/16</param-value>
        </init-param>
 
        <load-on-startup>2</load-on-startup>
    </servlet>

Instalace

V adresáři s rozbalenou distribuci Shibboleth IdP spustíme instalaci:

# cd /opt/tmp/shibboleth-identityprovider-2.x.x
# sh ./install.sh

Uvedeme, že jde o novou instalaci (v opačném případě nevytváří adresářovou strukturu, ale pouze zapíše novy idp.war soubor). Jako cílový adresář ponecháme výchozí možnost /opt/shibboleth-idp-2.x.x (pro účely tohoto návodu, jinak na umístění v podstatě nezáleží). Dále je potřeba zadat hostname IdP serveru - musí odpovídat CN položce certifikátu. Skript během instalace vygeneruje klíč a certifikát. Ty pak uloží do tzv. keystore chráněným heslem, který je potřeba zadat. Tento certifikát je určen hlavně pro testování a nemusí být vhodný pro nasazení do ostrého provozu.

V cílovém adresáři se vytvoří následující adresářová struktura:

  • bin/ - různé pomocné nástroje
  • conf/ - konfigurační soubory
  • credentials/ - klíče a certifikáty
  • lib/ - knihovny používané nástroji v adresáři bin/
  • logs/ - logy
  • metadata/ - doporučené místo na ukládání metadat
  • war/ - ukládá se tam soubor idp.war (obsahuje vlastní aplikaci), který je potřeba nainstalovat do servlet containeru Tomcat

Během instalace se vygeneruje self-signed certifikat, ktery se uloží do adresáře credentials/ a to jak v JKS (Java Keystore), tak i v PEM formátu. Vygenerují se také metadata na základě zadaných údajů a uloží se do adresáře metadata/. Metadata obsahují vygenerovaný self-signed certifikát a jsou prakticky hotova k použití, i když do produkčního režimu bude potřeba nejspiíš provést některé úpravy.

Umožníme, aby Tomcat mohl zapisovat do logovacího adresáře:

# chown tomcat6.root /opt/shibboleth-idp/logs

Po restartu Tomcat se aplikace Shibboleth IdP nastartuje a v logovacím adresáři by měly objevit log soubory.

Nastavení Apache

Virtuály

Podobně jako u verze 1.3 nastavíme příslušné SSL virtuály - jeden pro přímou komunikaci s uživateli (běžně port 443) a jeden pro tzv. backchannel komunikaci mezi SP a IdP (běžně port 8443). Backchannel používají SP a IdP k výměně atributů a případně dalších informací (např. v případě profilu Broswer/Artifact). Shibboleth 2.x používá implicitně nový profil, při kterém se atributy předávají najednou už během autentizace, ale pro zpětnou kompatibilitu se starší verzi SP je doporučitelné backchannel nastavit.

:!: Zatímco virtuál pro přímou komunikaci může používat libovolný certifikát, virtuál pro backchannel komunikaci (běžně na portu 8443) musí použít certifikát, který používá Shibboleth k podepisování SAML zpráv, tj. certifikát uvedený v metadatech. Tím si SP ověří, že komunikuje se správným IdP. Je potřeba také zadat do konfigurace virtuálu direktivy:

SSLVerifyClient   optional_no_ca
SSLVerifyDepth    10
SSLOptions        +StdEnvVars +ExportCertData

Propojení s Tomcat

Apache komunikuje s Tomcat backendem pomocí AJP protokolu. Je potřeba k tomu modul mod_proxy_ajp (a samozřejmě modul mod_proxy, na kterém závisí). V konfiguraci obou virtuálů zadáme:

  ProxyRequests Off
  ProxyPass /idp/ ajp://localhost:8009/idp/

Příklad konfigurace

<VirtualHost login.example.cz:443>
  ServerName login.example.cz
  ServerAdmin root@localhost

  [...]

  # IdP
  ProxyRequests Off
  ProxyPass /idp/ ajp://localhost:8009/idp/

  [...]
</VirtualHost>

<VirtualHost login.example.cz:8443>
  ServerName login.example.cz:8443
  ServerAdmin root@localhost

  [...]
  
  ProxyRequests Off
  ProxyPass /idp/ ajp://localhost:8009/idp/

  SSLVerifyClient optional_no_ca
  
  [...]
</VirtualHost>

Test instalace

Po úpravach v konfiguraci Apache a Tomcat je nezapomeneme restartovat. Pokud je vše v pořádku, tak následující URL zobrazí stavové informace o IdP:

https://HOSTNAME/idp/status

Kde HOSTNAME je jméno serveru, na kterém běži IdP.

:!: Pokud se zobrazuje chyba HTTP 401, ujistěte se, že máte správně nastavena přístupová práva.

Další kroky

Je dobré zakázat procházení virtuálních endpointů různými vyhledávácími roboty. Do rootu vašeho web serveru umístěte soubor robots.txt:

User-agent: *
Disallow: /idp/

Další konfigurace

Samotná konfigurace Shibboleth IdP 2.x je popsáná ve zvláštním návodě.

Last modified:: 2018/07/13 12:59