: Aktualizovat na verzi 1.18.3.

Tento návod se zabývá instalací a konfigurací SimpleSAMLphp verze 1.15.4 pouze v podobě poskytovatele služby (Service Provider, SP), nikoliv poskytovatele identity (Identity Provider, IdP). Pro IdP silně doporučujeme použít Shibboleth IdP.

V návodu budeme používat linuxovou distribuci Debian v jeho poslední verzi 9 s kódovým označením Stretch. Používáte-li jinou distribuci, některé kroky (např. instalace balíčků) se u vás budou odpovídajícím způsobem lišit.

Návod provází kompletní instalací a konfigurací SimpleSAMLphp včetně zdrojů metadat federace eduID.cz, Hostel IdP a Social IdPs (Facebook, GitHub, Google, LinkedIn, ORCID).

Před samotnou instalací zkontrolujeme, že máme v systému certifikát kořenové certifikační autority DigiCert (DigiCert Assured ID Root CA). HTTP server, ze kterého budeme stahovat metadata (metadata.eduid.cz), má HTTPS certifikát vydaný touto autoritou a bez její znalosti aplikace jako wget, curl aj. při pokusu o stažení metadat zahlásí chybu a odmítnou se na server připojit. Vyzkoušíme, zda dokážeme stáhnout metadata federace eduID.cz:

# Pokusné stažení metadat federace eduID.cz
wget https://metadata.eduid.cz/entities/eduid

V případě, že dojde ke stažení souboru eduid, je vše v pořádku. Pokud se však soubor nestáhne a v terminálu uvidíme následující:

--2016-03-29 14:35:32--  https://metadata.eduid.cz/entities/eduid
Resolving metadata.eduid.cz (metadata.eduid.cz)... 195.113.205.140
Connecting to metadata.eduid.cz (metadata.eduid.cz)|195.113.205.140|:443... connected.
ERROR: The certificate of ‘metadata.eduid.cz’ is not trusted.
ERROR: The certificate of ‘metadata.eduid.cz’ hasn't got a known issuer.

Doinstalujeme balíček ca-certificates:

# Instalace balíčku s certifikáty CA
apt-get install ca-certificates

Pro provoz SimpleSAMLphp je třeba HTTP server (v tomto návodu předpokládáme Apache) a interpret jazyka PHP. Instalaci obou komponent provedeme z balíčků distribuce. V případě Debianu následujícím příkazem:

# Instalace Apache a PHP5
apt-get install apache2 php5

SimpleSAMLphp vyžaduje některá rozšíření interpretru PHP. Většina z nich je však zakompilovaná přímo v distribučním balíčku PHP anebo lze v případě potřeby snadno doinstalovat odpovídající balíček z distribuce. Seznam rozšíření:

• vždy: date, dom, hash, libxml, openssl, pcre, SPL, zlib,
• při použití šifrování anebo digitálních podpisů: mcrypt,
• při ukládání informací o sezení do memcache: memcache,
• při použití databáze:
  • vždy: PDO,
  • závislosti na použité databázi: mysql, pgsql, …

(V případě nejistoty můžeme použít známé <?php PHPInfo(); ?> pro zjištění, co náš interpret aktuálně podporuje.)

Doporučený způsob instalace je instalace ze zdrojových kódů, nikoliv z balíčkovacího systému, kde je SimpleSAMLphp téměř vždy velice zastaralé. Musíme však nejprve stáhnout archiv se zdrojovými kódy ze stránek projektu anebo „release“ archiv z repozitáře na GitHubu. Stahujeme-li archiv z Internetu, nezapomeneme zkontrolovat kontrolní součet archivu! (Kontrolní součet archivu nalezneme na stránce projektu SimpleSAMLphp, kde je archiv k dispozici ke stažení.)

Stažený archiv umístíme do adresáře /opt/src, rozbalíme do /opt a vytvoříme na něj symbolický odkaz /opt/simplesamlphp. S tímto přístupem můžeme v případě potřeby velmi snadno přepnout na jinou verzi v budoucnu – např. při aktualizaci na novou verzi.

# Instalace SimpleSAMLphp ze zdrojových kódů
mkdir -p /opt/src
cd /opt/src
wget https://github.com/simplesamlphp/simplesamlphp/releases/download/v1.15.4/simplesamlphp-1.15.4.tar.gz
echo '349cf5d9f9ecbbced0e6f6794d26d5242fc9dafbd34268aeeb200182c24f88a5  simplesamlphp-1.15.4.tar.gz' | sha256sum -c
cd ..
tar -xzf src/simplesamlphp-1.15.4.tar.gz
ln -snf simplesamlphp-1.15.4 simplesamlphp

Tímto je instalace hotova a můžeme se pustit do konfigurace.

Jak nakonfigurovat Apache a PHP je mimo rozsah tohoto návodu.

Pro SimpleSAMLphp vytvoříme v konfiguraci Apache alias simplesaml, který odkazuje na námi vytvořený symbolický odkaz /opt/simplesamlphp směrující na odpovídající verzi SimpleSAMLphp.

# Konfigurace Apache pro SimpleSAMLphp
Alias /simplesaml    /opt/simplesamlphp/www
<Directory /opt/simplesamlphp>
  Require all granted
</Directory>

Poznámka: Chceme-li, aby SimpleSAMLphp bylo dostupné na jiné adrese než URL_SERVERU/simplesaml (např. /simplesamlphp), musíme změnit baseurlpath v config/config.php, protože to je standardně nastaveno na /simplesaml.

Po úpravě konfigurace nezapomeneme znovu nahrát konfiguraci Apache.

# Znovunačtení konfiguračních souborů Apache
service apache2 reload

Všechny níže uvedené cesty jsou relativní k adresáři /opt/simplesamlphp.

Před samotnou konfigurací vytvoříme adresáře, do nichž se budou stahovat příslušná metadata. Tyto adresáře musí být přístupné pro zápis uživateli, pod kterým na serveru běží HTTP démon. V případě Apache na distribuci Debian je to uživatel www-data ze skupiny www-data.

# Vytvoření adresářů pro metadata
cd /opt/simplesamlphp/metadata
mkdir eduid hostel socialidp
chown www-data:www-data eduid hostel socialidp

Budeme také muset definovat bezpečnou „sůl“, kterou si vygenerujeme a poté vložíme do konfiguračního souboru config/config.php.

# Vygenerování náhodné soli
tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null; echo

Základním konfiguračním souborem SimpleSAMLphp je config/config.php, kde nastavíme administrátorské heslo, náhodně vygenerovanou „sůl“, technický kontakt, časovou zónu a další.

# Úpravy v konfiguračním souboru config/config.php
$config = array(
 
  'auth.adminpassword'      => 'N2jak0_Siln0-Heslo',
  'secretsalt'              => 'lhbogwzt0m32khnrh8d39p39tzxxyyhr',
  'technicalcontact_name'   => 'Jan Oppolzer',
  'technicalcontact_email'  => 'jan.oppolzer@cesnet.cz',
  'timezone'                => 'Europe/Prague',
 
  'authproc.sp' => array(
    51 => array('class' => 'core:AttributeMap',   'oid2name'),
    52 => array('class' => 'core:AttributeMap',   'urn2name'),
    60 => array('class' => 'core:GenerateGroups', 'eduPersonAffiliation'),
    90 => 'core:LanguageAdaptor',
  ),
 
  'metadata.sources' => array(
    array ('type' => 'flatfile', 'directory' => 'metadata/eduid'),
    array ('type' => 'flatfile', 'directory' => 'metadata/hostel'),
    array ('type' => 'flatfile', 'directory' => 'metadata/socialidp'),
  ),
 
);

Při provozu SimpleSAMLphp je potřeba mít vygenerovaný pár certifikát-klíč pro šifrování XML assertions mezi entitami federace (SP a IdP). Vytvoříme si tedy self-sign certifikát.

Poznámka: Narozdíl od certifikátu pro HTTP server, zde self-sign certifikát nejen bohatě stačí, ale je i doporučen. Nepoužívejte v metadatech certifikát od důvěryhodné certifikační autority. Takový certifikát má platnost maximálně 3 roky a poté je třeba ho vyměnit a aktualizovat tedy metadata SP ve federaci. Vygenerujete-li si self-sign certifikát (2048bitový klíč!) s platností 10 nebo klidně 20 let, nemusíte po 3 letech metadata aktualizovat a ušetříte si práci.

# Generování certifikátu s platností 20 let
cd /opt/simplesamlphp/cert/
openssl req -newkey rsa:2048 -new -x509 -days 7305 -nodes -out saml.crt -keyout saml.pem

Aby mohla být služba zařazena do federace, je potřeba, aby byla správně popsána pomocí metadat (mj. musíme právě vygenerovaný pár certifikát-klíč nakonfigurovat v SimpleSAMLphp, aby se používal). Pokud metadata služby nebudou splňovat požadavky, nebudou přijata do federace, proto budeme věnovat následující konfiguraci pozornost.

Hodnotu entityID si můžeme částečně vymyslet. Doporučenou hodnotu zkontruujeme následovně: https://hostname/sp (část za názvem serveru – /sp – si můžeme téměř libovolně vymyslet, avšak nikdy bychom ji už následně neměli měnit), tedy https://super-service.cesnet.cz/sp pro fiktivní server super-service.cesnet.cz.

Hodnota discoURL udává URL adresu tzv. „discovery service“ anebo WAYF (Where Are You From). Je zde uvedena URL adresa pro WAYF federace eduID.cz.

Hodnoty DisplayName, Description, InformationURL spadající pod UIInfo a dále OrganizationName, OrganizationDisplayName a OrganizationURL je nutno uvést v českém a anglickém jazyce. Jejich význam je zřetelný z jejich názvu. Uvádějí o službě doplňující avšak důležité informace potřebné např. různými rozcestníky na služby apod.

# Úpravy v konfiguračním souboru config/authsources.php
$config = array(
 
  'default-sp' => array(
    'entityID' => 'https://super-service.cesnet.cz/sp',
    'discoURL' => 'https://ds.eduid.cz/wayf.php',
 
    // Certifikáty
    'privatekey'  => 'saml.pem',
    'certificate' => 'saml.crt',
 
    // UUInfo
    'UIInfo' => array(
 
      // DisplayName
      'DisplayName' => array(
        'cs' => 'Super Service',
        'en' => 'Super Service',
      ),
 
      // Description
      'Description' => array(
        'cs' => 'Nástroj, který za vás vyřeší spoustu práce.',
        'en' => 'A tool helping you get your work done.',
      ),
 
      // InformationURL
      'InformationURL' => array(
        'cs' => 'https://super-service.cesnet.cz/?language=cs',
        'en' => 'https://super-service.cesnet.cz/?language=en',
      ),
 
    ),
 
    // OrganizationName
    'OrganizationName' => array(
      'cs' => 'CESNET, z. s. p. o.',
      'en' => 'CESNET, a. l. e',
    ),
 
    // OrganizationDisplayName
    'OrganizationDisplayName' => array(
      'cs' => 'CESNET',
      'en' => 'CESNET',
    ),
 
    // OrganizationURL
    'OrganizationURL' => array(
      'cs' => 'http://www.cesnet.cz/?lang=cs',
      'en' => 'http://www.cesnet.cz/?lang=en',
    ),
 
  ),
 
);

Metadata se ve federacích zpravidla mění podle toho, jak se přidávají anebo upravují poskytovatelé identit (IdP) nebo poskytovatelé služeb (SP). Platnost metadat je navíc časově omezena. Proto je vhodné metadata aktualizovat pravidelně. Toho lze nejjednodušeji dosáhnout jejich automatickou aktualizací za pomoci modulů metarefresh a cron.

Modul metarefresh aktivujeme vytvořením souboru enable v jeho adresáři. Následně zkopírujeme výchozí konfigurační soubor modulu do adresáře s konfiguračními soubory /opt/simplesamlphp/config.

# Aktivace modulu metarefresh
cd /opt/simplesamlphp/modules/metarefresh/
touch enable
cp config-templates/config-metarefresh.php /opt/simplesamlphp/config

Nyní nastavíme zdroje metadat (federace eduID.cz, Hostel IdP a Social IdPs [Facebook, GitHub, Google, LinkedIn a ORCID].

Hodnota validateFingerprint obsahuje otisk veřejného klíče, který patří certifikátu, jímž jsou metadata podepisována. Přestože se metadata stahují pomocí protokolu HTTPS, důrazně doporučujeme stažená metadata kontrolovat! Otisk si pro jistotu ověříme.

# Ověření otisku veřejného klíče
wget https://www.eduid.cz/docs/eduid/metadata/metadata.eduid.cz.crt.pem
openssl x509 -fingerprint -in metadata.eduid.cz.crt.pem

Předchozí příkaz vypíše otisk veřejného klíče:

# SHA1 Fingerprint=2E:51:FC:08:CF:15:C5:15:48:28:AF:64:A7:97:50:80:B4:AB:5D:24
# -----BEGIN CERTIFICATE-----
# MIIDCjCCAfICCQDeyJjos8lOlTANBgkqhkiG9w0BAQUFADBHMRIwEAYKCZImiZPy
# LGQBGRYCY3oxFTATBgoJkiaJk/IsZAEZFgVlZHVJRDEaMBgGA1UEAxMRbWV0YWRh
# dGEuZWR1SUQuY3owHhcNMTEwMjE3MjAyMDAwWhcNMjEwMjE0MjAyMDAwWjBHMRIw
# EAYKCZImiZPyLGQBGRYCY3oxFTATBgoJkiaJk/IsZAEZFgVlZHVJRDEaMBgGA1UE
# AxMRbWV0YWRhdGEuZWR1SUQuY3owggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEK
# AoIBAQD9Wg8jPOecHmHtpCEsNqJnQHXZr6bAKIXUFDZheKRqAi4PvMo6clWkl3sj
# MHbqmc+K4HnkGm1445CdxwJnmHsKHcnYrP/Zq0TiP5bydhRpna3c+YCX0alFlwop
# Dm3Pl9Nd/fBqMHXjihCsHYZOcM5UY2xW/x+wlhTX3jVSUO/WKhq3Ljae0m9f39R7
# DOAwMcaDY+2+9BlIx/Dz78z/LNOVEbzhxLaxt25PzA7Tw1cMfZ07LeER6w2OoQBS
# 8kZY5aORLOiv3VRsF9LH4n0OGHx4Gxb8QsL8/H1xccfV+aweo4E9sZRGLF506O/+
# A567dQWdi4b5Oodtnd+hzEfn2cI1AgMBAAEwDQYJKoZIhvcNAQEFBQADggEBAGHU
# 6daImmTF7oPVakUtMTRJX+D1rUyw4UM4my6vLTQsm/qz5cq+rhglplCZCMOi/3Ll
# ncbrwwFudcn2lvda5KljVcZjoHS/eM8Q0mk0P77cOpAJUYOniUYLnRn84UiPYKTS
# 70FMq6nIO38rRdSbqROZTqdnzOupOKHJgxZI4FFGzRCSfDEqW5YhlTnUUVMyD2YB
# zonXReSFbrhofcMbEDlJj/B7RVnqcCmQJRy28bqS6wK7uJpYNt1HQwASbAnrzUgO
# FIbaiwkFIyMuxjzSuXeyl2UDTtTlINECv7Y9FMgifwq2Fyms/TskZzvDEHvAsZxV
# bqg7GKeCsFXAnGL79xM=
# -----END CERTIFICATE-----

# Úpravy v konfiguračním souboru config/config-metarefresh.php
$config = array(
 
  'sets' => array(
 
    # eduID.cz
    'eduidcz'   => array(
      'cron'    => array('hourly'),
      'sources' => array(
        array(
          'src'                 => 'https://metadata.eduid.cz/entities/eduid+idp',
          'validateFingerprint' => '2E:51:FC:08:CF:15:C5:15:48:28:AF:64:A7:97:50:80:B4:AB:5D:24',
        ),
      ),
      'expireAfter'   => 60*60*24*4, // Maximum 4 days cache time.
      'outputDir'     => 'metadata/eduid/',
      'outputFormat'  => 'flatfile',
    ),
 
    # Hostel IdP
    'hostel'    => array(
      'cron'    => array('hourly'),
      'sources' => array(
        array(
          'src'                 => 'https://metadata.eduid.cz/entities/hostel',
          'validateFingerprint' => '2E:51:FC:08:CF:15:C5:15:48:28:AF:64:A7:97:50:80:B4:AB:5D:24',
        ),
      ),
      'expireAfter'   => 60*60*24*4, // Maximum 4 days cache time.
      'outputDir'     => 'metadata/hostel/',
      'outputFormat'  => 'flatfile',
    ),
 
    # Social IdP (Facebook, GitHub, Google, LinkedIn, mojeID a ORCID)
    'socialidp' => array(
      'cron'    => array('hourly'),
      'sources' => array(
        array(
          'src'                 => 'https://metadata.eduid.cz/entities/extidp.cesnet.cz',
          'validateFingerprint' => '2E:51:FC:08:CF:15:C5:15:48:28:AF:64:A7:97:50:80:B4:AB:5D:24',
        ),
      ),
      'expireAfter'   => 60*60*24*4, // Maximum 4 days cache time.
      'outputDir'     => 'metadata/socialidp/',
      'outputFormat'  => 'flatfile',
    ),
 
  ),
);

Aby se metadata stahovala automaticky každou hodinu, musíme ještě zapnout a nakonfigurovat modul cron. Aktivace modulu se provede prostým vytvořením souboru enable v jeho adresáři. Poté ještě zkopírujeme jeho výchozí konfigurační soubor do adresáře s ostatními konfiguračními soubory /opt/simplesamlphp/config.

# Aktivace modulu cron
cd /opt/simplesamlphp/modules/cron/
touch enable
cp config-templates/module_cron.php /opt/simplesamlphp/config

Vygenerujeme si heslo, které zajistí ochranu, aby úlohu nemohl spustit nikdo nežádoucí.

# Vygenerování hesla pro cron
tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=8 count=1 2>/dev/null; echo

V konfiguračním souboru pro modul cron stačí nastavit heslo do parametru key.

# Úpravy v konfiguračním souboru config/module_cron.php
$config = array (
  'key'           => 'eobaqcjf',
  'allowed_tags'  => array('daily', 'hourly', 'frequent'),
  'debug_message' => TRUE,
  'sendemail'     => TRUE,
);

Posledním krokem konfigurace je přidání úlohy do systémového démona cron. Zadáme tedy příkaz crontab -e a vložíme do něj následující řádku (případně řádky, přidáme-li i komentář), který zajistí, že se každou první minutu v hodině spustí aktualizace metadat. Nezapomeňte uvést heslo do parametru „key“.

# SimpleSAMLphp metadata refresh
01 * * * *  wget --quiet "https://super-service.cesnet.cz/simplesaml/module.php/cron/cron.php?key=eobaqcjf&tag=hourly" &> /dev/null

Namísto příkazu wget je také možno použít např. curl, fetch apod.

# SimpleSAMLphp metadata refresh
01 * * * *  curl --silent "https://super-service.cesnet.cz/simplesaml/module.php/cron/cron.php?key=eobaqcjf&tag=hourly" &> /dev/null

Nyní je již SimpleSAMLphp nakonfigurováno. Na adrese https://hostname/simplesaml se můžeme přihlásit administrátorským heslem (soubor config/config.php) do webového rozhraní SimpleSAMLphp. V záložce Federation najdeme odkaz [ Show metadata ], pod nímž se schovávají metadata našeho SP, která můžeme použít pro registraci ve federaci. V této záložce zároveň najdeme všechna IdP, jejichž metadata máme stažena společně s dobou jejich platnosti. V nastavení výše (config/config-metarefresh.php) jsme zvolili 4 dny, tedy 96 hodin. Máme-li nastavenu aktualizaci metadat na každou hodinu, pak bychom nikdy neměli vidět platnost menší než 95 hodin. Metadata můžeme aktualizovat také ručně pomocí tlačítka Metarefresh: fetch metadata dole na stránce.