====== SimpleSAMLphp ======

Tento návod se zabývá instalací a konfigurací [[https://simplesamlphp.org|SimpleSAMLphp]] pouze v podobě poskytovatele služby (Service Provider, SP), nikoliv poskytovatele identity (Identity Provider, IdP). Pro IdP silně doporučujeme použít [[cs:tech:idp:shibboleth|Shibboleth IdP]].

V návodu budeme používat linuxovou distribuci [[https://www.debian.org|Debian]] v jeho poslední verzi 12 s kódovým označením [[https://www.debian.org/releases/bookworm/|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 [[cs:tech:summary|eduID.cz]] a [[cs:tech:socialidps]] (GitHub, Google, LinkedIn, ORCID).

===== Instalace =====

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:

<code bash>
# Pokusné stažení metadat federace eduID.cz
wget -O/dev/null https://metadata.eduid.cz/entities/eduid
</code>

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í:

<code text>
--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.
</code>

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

<code bash>
# Instalace balíčku s certifikáty CA
apt install --no-install-recommends ca-certificates
</code>

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

<code bash>
# Instalace Apache a PHP
apt install apache2 php php-xml php-curl php-sqlite3
</code>

SimpleSAMLphp [[https://simplesamlphp.org/docs/stable/simplesamlphp-install#section_1|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 [[https://simplesamlphp.org/download|projektu]] anebo "release" archiv z repozitáře na [[https://github.com/simplesamlphp/simplesamlphp/releases|GitHubu]]. Stahujeme-li archiv z Internetu, **nezapomeneme zkontrolovat kontrolní součet** archivu! (Kontrolní součet archivu nalezneme na [[https://simplesamlphp.org/download|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.

<code bash>
# 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
</code>

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

Jak nakonfigurovat [[https://httpd.apache.org|Apache]] a [[https://php.net|PHP]] je mimo rozsah tohoto návodu.

==== Apache ====

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.

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

//Poznámka:// Chceme-li, aby SimpleSAMLphp bylo dostupné na jiné adrese než //<nowiki>https://HOSTNAME/simplesaml</nowiki>// (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.

<code bash>
# Znovunačtení konfiguračních souborů Apache
systemctl reload apache2
</code>

==== SimpleSAMLphp ====

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

<code bash>
cd /opt/simplesamlphp
cp config/config.php{.dist,}
cp config/authsources.php{.dist,} 
</code>

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

<code bash>
# Vytvoření adresářů pro metadata
mkdir metadata/{eduidcz,socialidps}
chown www-data:www-data metadata/{eduidcz,socialidps}
</code>

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

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

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ší.

<code php>
# Ú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' ],
  ],

);
</code>

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.

<code bash>
# 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
</code>

=== Metadata služby ===

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ě: //<nowiki>https://service.example.org/simplesamlphp</nowiki>// (//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 [[https://www.eduid.cz/cs/tech/summary|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.

<code php>
# Ú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',
    ],

  ],
  
];
</code>

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//:

<code bash>
apt install composer
composer require simplesamlphp/simplesamlphp-module-metarefresh
</code>

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

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

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

<code bash>
cp modules/metarefresh/config-templates/*.php config/
</code>

Nyní nastavíme zdroje metadat ([[cs:tech:summary|eduID.cz]] a [[cs:tech:socialidps]] [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ží [[https://www.eduid.cz/docs/eduid/metadata/metadata.eduid.cz.crt.pem|certifikát]], který si stáhněte do adresáře ''/opt/simplesamlphp/cert''.

<code bash>
# 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
</code>

<code php>
# Ú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',
    ],

  ],
];
</code>

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

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

<code bash>
cp modules/cron/config/module_cron.php.dist config/module_cron.php
</code>

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

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

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

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

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".**

<code bash>
# SimpleSAMLphp metadata refresh
01 * * * *  wget --quiet "https://server.example.org/simplesaml/module.php/cron/run/hourly/eobaqcjf" &> /dev/null
</code>

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

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

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