Tento návod se zabývá instalací a konfigurací SimpleSAMLphp 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 12 s kódovým označením Bookworm. 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 a Social IdPs (GitHub, Google, LinkedIn, ORCID).

Před samotnou instalací zkontrolujeme, že máme v systému certifikát kořenové certifikační autority USERTrust RSA Certification Authority. HTTP server, ze kterého budeme stahovat metadata (metadata.eduid.cz), má TLS 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 -O/dev/null https://metadata.eduid.cz/entities/eduid

V případě, že je vše v pořádku, uvidíte úspěšný pokus o stažení metadat. V opačném případě v terminálu uvidíte následující:

--2019-12-16 08:25:54--  https://metadata.eduid.cz/entities/eduid
Resolving metadata.eduid.cz (metadata.eduid.cz)... 2001:718:ff05:202::23, 78.128.216.23
Connecting to metadata.eduid.cz (metadata.eduid.cz)|2001:718:ff05:202::23|:443... connected.
ERROR: The certificate of ‘metadata.eduid.cz’ is not trusted.
ERROR: The certificate of ‘metadata.eduid.cz’ doesn't have a known issuer.

Nemáme-li kořenový certifikát, doinstalujeme balíček ca-certificates:

# Instalace balíčku s certifikáty CA
apt install --no-install-recommends 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 PHP
apt install apache2 php php-xml php-curl php-sqlite3

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, fileinfo, filter, hash, intl, json, libxml, mbstring, openssl, pcre, session, simplexml, SPL a zlib,
• na Linuxu: posix,
• pro kontrolu aktualizací: cURL,
• 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, 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ů
cd /opt/
wget https://github.com/simplesamlphp/simplesamlphp/releases/download/v2.0.6/simplesamlphp-2.0.6.tar.gz
echo 'e609047a62886c5169cdf7a30920a25a5648720eb25753964799c2085d55f783  simplesamlphp-2.0.6.tar.gz' | sha256sum -c
tar -xzf simplesamlphp-2.0.6.tar.gz
ln -snf simplesamlphp-2.0.6 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ž https://HOSTNAME/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
systemctl reload apache2

Ze všeho nejdříve musíme vytvořit konfigurační soubory a to překopírováním šablon:

cd /opt/simplesamlphp
cp config/config.php{.dist,}
cp config/authsources.php{.dist,} 

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
mkdir metadata/{eduidcz,socialidps}
chown www-data:www-data metadata/{eduidcz,socialidps}

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
LC_ALL=C 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 náhodně vygenerovanou „sůl“, administrátorské heslo, technický kontakt, časovou zónu a další.

# Úpravy v konfiguračním souboru config/config.php
$config = array(
 
  'secretsalt'              => 'lhbogwzt0m32khnrh8d39p39tzxxyyhr',
  'auth.adminpassword'      => '20ff641165dadffcae2f62b97774e2c63531bc8f',
  'technicalcontact_name'   => 'Kryštof Šáteček',
  'technicalcontact_email'  => 'krystof.satecek@example.org',
  'timezone'                => 'Europe/Prague',
 
  'authproc.sp' => [
    51 => [ 'class' => 'core:AttributeMap',   'oid2name' ],
    52 => [ 'class' => 'core:AttributeMap',   'urn2name' ],
    60 => [ 'class' => 'core:GenerateGroups', 'eduPersonAffiliation' ],
    90 => 'core:LanguageAdaptor',
  ],
 
  'metadata.sources' => [
    [ 'type' => 'flatfile', 'directory' => 'metadata/eduidcz' ],
    [ 'type' => 'flatfile', 'directory' => 'metadata/socialidps' ],
  ],
 
);

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. Vygenerujte si self-sign certifikát (2048bitový klíč!) s platností 10 nebo klidně 20 let.

# Generování certifikátu s platností 20 let
openssl req -newkey rsa:2048 -new -x509 -days 7305 -nodes -out cert/saml.crt -keyout cert/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 zkonstruujeme následovně: https://service.example.org/simplesamlphp (entityID si můžeme téměř libovolně vymyslet, avšak nikdy bychom ho už následně neměli měnit).

Hodnota discoURL udává URL adresu DS (Discovery Service) nebo také 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 = [
 
  'default-sp' => [
    'entityID' => 'https://service.example.org/simplesamlphp',
    'discoURL' => 'https://ds.eduid.cz/wayf.php',
 
    // Certifikáty
    'privatekey'  => 'saml.pem',
    'certificate' => 'saml.crt',
 
    // UUInfo
    'UIInfo' => [
 
      // DisplayName
      'DisplayName' => [
        'cs' => 'Example Service',
        'en' => 'Example Service',
      ],
 
      // Description
      'Description' => [
        'cs' => 'Lorem ipsum dolor sit amet.',
        'en' => 'Suspendisse imperdiet nulla in nisi efficitur.',
      ],
 
      // InformationURL
      'InformationURL' => [
        'cs' => 'https://service.example.org/cs',
        'en' => 'https://service.example.org/en',
      ],
 
    ],
 
    // OrganizationName
    'OrganizationName' => [
      'cs' => 'EXAMPLE, z. s. p. o.',
      'en' => 'EXAMPLE, a. l. e',
    ],
 
    // OrganizationDisplayName
    'OrganizationDisplayName' => [
      'cs' => 'EXAMPLE',
      'en' => 'EXAMPLE',
    ],
 
    // OrganizationURL
    'OrganizationURL' => [
      'cs' => 'https://www.example.org/cs',
      'en' => 'https://www.example.org/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.

Nejprve si nainstalujeme balíčkovací systém Composer a následně z něj nainstalujeme modul metarefresh:

apt install composer
composer require simplesamlphp/simplesamlphp-module-metarefresh

Nyní modul metarefresh aktivujeme v konfiguračním souboru config/config.php:

'module.enable' => [
  // ...
  'metarefresh' => true,
  // ...
],

Zkopírujeme výchozí konfigurační soubor modulu do adresáře s konfiguračními soubory /opt/simplesamlphp/config.:

cp modules/metarefresh/config-templates/*.php config/

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

Přestože se metadata stahují pomocí protokolu HTTPS, důrazně doporučujeme stažená metadata kontrolovat! K tomu slouží certifikát, který si stáhněte do adresáře /opt/simplesamlphp/cert.

# Stažení certifikátu pro ověření metadat federace
wget -P /opt/simplesamlphp/cert/ \
     https://www.eduid.cz/docs/eduid/metadata/metadata.eduid.cz.crt.pem

# Úpravy v konfiguračním souboru config/config-metarefresh.php
$config = [
 
  'sets' => [
 
    # eduID.cz
    'eduidcz' => [
      'cron' => ['hourly'],
      'sources' => [
        [
          'src' => 'https://metadata.eduid.cz/entities/eduid+idp',
          'certificates' => [
            'metadata.eduid.cz.crt.pem',
          ],
        ],
      ],
      'expireAfter' => 60*60*24*4, // Maximum 4 days cache time.
      'outputDir' => 'metadata/eduidcz/',
      'outputFormat' => 'flatfile',
    ],
 
    # Social IdPs (Facebook, GitHub, Google, LinkedIn a ORCID)
    'socialidps' => [
      'cron' => ['hourly'],
      'sources' => [
        [
          'src' => 'https://metadata.eduid.cz/entities/socialidps',
          'certificates' => [
            'metadata.eduid.cz.crt.pem',
          ],
        ],
      ],
      'expireAfter' => 60*60*24*4, // Maximum 4 days cache time.
      'outputDir' => 'metadata/socialidps/',
      'outputFormat' => 'flatfile',
    ],
 
  ],
];

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

'module.enable' => [
  // ...
  'cron' => true,
  // ...
],

cp modules/cron/config/module_cron.php.dist config/module_cron.php

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

# Vygenerování hesla pro cron
LC_ALL=C 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 = [
  '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://server.example.org/simplesaml/module.php/cron/run/hourly/eobaqcjf" &> /dev/null

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

# SimpleSAMLphp metadata refresh
01 * * * *  curl --silent "https://server.example.org/simplesaml/module.php/cron/run/hourly/eobaqcjf" &> /dev/null

Nyní je již SimpleSAMLphp nakonfigurováno. Na adrese https://HOSTNAME/simplesaml/admin 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 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 datem jejich expirace. V nastavení výše (config/config-metarefresh.php) jsme zvolili 4 dny.