SimpleSAMLphp

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).

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 /var, rozbalíme do /var a vytvoříme na něj symbolický odkaz /var/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 /var/
wget https://github.com/simplesamlphp/simplesamlphp/releases/download/v2.4.0/simplesamlphp-2.4.0-full.tar.gz
echo '5c333f6bf19ed67c27bb15d52145b54c94ee294b6594af0100e857e845b088f5  simplesamlphp-2.4.0-full.tar.gz' | sha256sum -c
tar -xzf simplesamlphp-2.4.0-full.tar.gz
ln -snf simplesamlphp-2.4.0 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 adresář public na námi vytvořeného symbolického odkazu /var/simplesamlphp směrující na odpovídající verzi SimpleSAMLphp.

# Konfigurace Apache pro SimpleSAMLphp
Alias /simplesaml    /var/simplesamlphp/public
 
<Directory /var/simplesamlphp/public>
  Require all granted
</Directory>

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 /var/simplesamlphp
cp config/config.php{.dist,}
cp config/authsources.php{.dist,} 

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

Základním konfiguračním souborem SimpleSAMLphp je config/config.php, kde nastavíme plnou URL adresu k SimpleSAMLphp, technický kontakt, časovou zónu, náhodně vygenerovanou sůl, administrátorské heslo, povolené moduly, mapování atributů a cesty k ukládání metadat.

Před samotnou úpravou config.php si vygenerujeme náhodnou sůl.

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

Nyní se můžeme pustit do úprav souboru config.php.

# Úpravy v konfiguračním souboru config/config.php
$config = [
 
  'baseurlpath' => 'https://service.example.org/simplesaml/',
 
  'technicalcontact_name' => 'Kryštof Šáteček',
  'technicalcontact_email' => 'krystof.satecek@example.org',
 
  'timezone' => 'Europe/Prague',
 
  'secretsalt' => 'secret salt generated here',
 
  'auth.adminpassword' => '20ff641165dadffcae2f62b97774e2c63531bc8f',
 
  'module.enable' => [
    'exampleauth' => false,
    'core' => true,
    'admin' => true,
    'cron' => true,
    'metarefresh' => true,
  ],
 
  'authproc.sp' => [
    51 => [ 'class' => 'core:AttributeMap',   'oid2name' ],
    52 => [ 'class' => 'core:AttributeMap',   'urn2name' ],
    60 => [ 'class' => 'core:GenerateGroups', 'eduPersonAffiliation' ],
    90 => 'core:LanguageAdaptor',
  ],
 
  'metadata.sources' => [
    ['type' => 'flatfile'],
    ['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 vymyslet, avšak nikdy bychom ho už následně neměli měnit. Doporučenou hodnotu zkonstruujeme následovně: https://FQDN/simplesaml.

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/simplesaml',
 
    'privatekey'  => 'saml.pem',
    'certificate' => 'saml.crt',
 
    'discoURL' => 'https://ds.eduid.cz/wayf.php',
 
    'UIInfo' => [
 
      'DisplayName' => [
        'cs' => 'Example Service',
        'en' => 'Example Service',
      ],
 
      'Description' => [
        'cs' => 'Lorem ipsum dolor sit amet.',
        'en' => 'Suspendisse imperdiet nulla in nisi efficitur.',
      ],
 
      'InformationURL' => [
        'cs' => 'https://service.example.org/cs',
        'en' => 'https://service.example.org/en',
      ],
 
    ],
 
    'OrganizationName' => [
      'cs' => 'EXAMPLE, z. s. p. o.',
      'en' => 'EXAMPLE, a. l. e',
    ],
 
    'OrganizationDisplayName' => [
      'cs' => 'EXAMPLE',
      'en' => 'EXAMPLE',
    ],
 
    '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.

Zkopírujeme výchozí konfigurační soubor modulu do adresáře s konfiguračními soubory /var/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 /var/simplesamlphp/cert.

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

# Úpravy v konfiguračním souboru config/module_metarefresh.php
$config = [
 
  'sets' => [
 
    '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',
    ],
 
    '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',
    ],
 
  ],
];

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}

Aby se metadata stahovala automaticky každou hodinu, musíme ještě nakonfigurovat modul cron. Zkopírujeme jeho výchozí konfigurační soubor do adresáře s ostatními konfiguračními soubory /var/simplesamlphp/config.

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' => false,
];

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://service.example.org/simplesaml/module.php/cron/run/hourly/eobaqcjf" &> /dev/null

Nyní je již SimpleSAMLphp nakonfigurováno. Na adrese https://FQDN/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.

<md:ContactPerson contactType="technical">
  <md:GivenName>Kryštof Šáteček</md:GivenName>
  <md:EmailAddress>mailto:krystof.satecek@example.org</md:EmailAddress>
</md:ContactPerson>

<md:ContactPerson contactType="technical">
  <md:GivenName>Kryštof</md:GivenName>
  <md:SurName>Šáteček</md:SurName>
  <md:EmailAddress>mailto:krystof.satecek@example.org</md:EmailAddress>
</md:ContactPerson>