# SimpleSAMLphp
# SimpleSAMLphp
Az alábbi lapon megkíséreljük összefoglalni a legfontosabb lépéseket, melyek általános esetben elegendőek ahhoz, hogy működő SimpleSAMLphp (SSP) alkalmazást állítsunk üzembe.
## Telepítés
A leírás a forrásból történő telepítés lépéseit írja le. Az itt részletezetten kívül a SimpleSAMLphp telepíthető Debian (vagy más) operációs rendszer csomagjából, de ebben az esetben ne telepítsunk composerrel third-party (pl. általunk készített) modulokat!
### Előkészületek
Ahhoz, hogy problémamentesen telepíthessük SSP alkalmazásunkat, az alábbi szoftverkomponenseknek kell működniük szerverünkön.
* PHP futtatására alkalmas webszerver
* PHP környezet (>=5.4)
* A következő PHP kiterjesztéseket engedélyezni kell
* `date`, `dom`, `hash`, `libxml`, `openssl`, `pcre`, `SPL`, `zlib`
* LDAP-ból történő autentikáció esetén: `ldap`
* Adatbázisból történő autentikáció esetén a megfelelő adatbázis-csatolót `mysql`, `pgsql`
* RADIUS szerveren keresztül történő autentikáció esetén: `radius`
* Assertion-ök titkosítása esetén: `mcrypt`
* Memcache használata esetén: `memcache`
* HEXAA integrációhoz (SP): `soap`
#### Debian 9 / Ubuntu 16.04 LTS csomagok
sudo apt install php php-dom mcrypt php-xml php-mbstring
#### RHEL / CentOS 7 csomagok
A **php-mcrypt** csomaghoz engedélyezni kell az "*epel-release*"-t.
sudo yum install epel-release
sudo yum update
sudo yum install php php-dom php-mcrypt php-xml php-mbstring php-common mod_ssl
#### Composer
A **[composer](https://getcomposer.org)** PHP csomagkezelőt is telepíteni kell (akár forrásból, akár csomagból), hogy telepíteni lehessen a SimpleSAMLphp futásához szükséges PHP library-ket.
### Letöltés
A GitHubról történő telepítés előnye, hogy a simplesamlphp könnyen frissíthető marad, csak a third party modulokat kell újratelepíteni. Az utolsó stabil verzió számát a [https://simplesamlphp.org/download](https://simplesamlphp.org/download) oldalról tudhatjuk meg.
cd /var
git clone [https://github.com/simplesamlphp/simplesamlphp.git](https://github.com/simplesamlphp/simplesamlphp.git)
cd simplesamlphp
git checkout tags/v1.16.2 -b v1.16.2
composer install --no-dev
### Apache konfigurálás
A webről csak a `/var/simplesamlphp/www` könyvtárat kell elérni. **Tilos** a teljes simplesamlphp könyvtárat a DocumentRoot alá tenni!
Alias /simplesaml /var/simplesamlphp/www
Require all granted
### Alapbeállítások
#### Konfigurációs fájlok másolása
Mielőtt aktiváljuk valamelyik főszolgáltatását (IdP,SP...) a telepített alkalmazásnak, néhány beállítást meg kell adnunk a `config/config.php` és `config/authsources.php` konfigurációs fájlokban.
* **config.php** másolása a **config-templates** mappából
cp config-templates/config.php config/
* **authsources.php** másolása a **config-templates** mappából
cp config-templates/authsources.php config/
A **config.php** és **authsources.php** fájlok másolása utána ellenőrizzük, hogy a SimpleSAMLphp működik-e, a [https://example.org/simplesaml](https://example.org/simplesaml) oldalon.
#### Konfigurációs fájlok szerkesztése
##### Adminisztrációs adatok beállítása
Amennyiben az SimpleSAMLphp kezdőlapja hiba nélkül megjelent, akkor nyissuk meg a **config/config.php** fájl szerkesztésre és végezzük el az alábbi beállításokat.
* **Az "admin" felhasználó jelszavát, mellyel webes felületen keresztül be tud lépni a települő SSP-be.**
'auth.adminpassword' => 'ujjelszotirdide',
* **Titkosítási feladatokhoz szükséges "salt", azaz véletlenszerűen összeálló karaktersorozat**
'secretsalt' => 'randombytesinsertedhere',
A karaktersorozat előállításában segíthet az alábbi parancs:
tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' /dev/null;echo
* **Elérhetőségeket, amely adatok bekerülnek majd a generált metaadatba**
'technicalcontact_name' => 'Gipsz Jakab',
'technicalcontact_email' => 'jakab.gipsz@example.org',
* **Nyelv és időzóna adatok**
'language.default' => 'hu',
'timezone' => 'Europe/Budapest',
Az alapadatok megadása után mentsük és zárjuk be a **config.php**-t.
##### Naplózás beállítása
Alapértelmezetten a SimpleSAMLphp a **syslog**-ba irányítja a naplózást.
Ha fájlba akarunk naplózni, akkor a megfelelő könyvtárhoz biztosítsunk írás jogot a webszerver felhasználónak, és ne felejtsünk el gondoskodni a naplófájlok rotálásáról!
* **log** mappa létrehozása és jogosultság beállítása
sudo mkdir log; sudo chown www-data:adm log; sudo chmod 755 log
* Naplózási szint beállítása a **config/config.php**-ban
'debug' => array(
'saml' => true,
'backtraces' => true,
'validatexml' => false,
),
'logging.level' => SimpleSAML\Logger::DEBUG,
'logging.handler' => 'file',
A "SimpleSAML\Logger::DEBUG" a legrészletesebb naplózási beállítás, éles rendszernél nem ajánlott csak hiba keresés esetén.
##### Tanúsítvány készítése
Nem ajánlott a SimpleSAMLphp-hoz és webszerverhez ugyanazt a tanúsítvány használni!
* A SimpleSAMLphp alapértelmezetten a tanúsítványt a **cert** mappában keresi.
mkdir cert
* Az alábbi paranccsal egy 10 éves [self-signed tanúsítvány](https://help.edu.hu/books/kiegeszito-tudnivalok/page/tanusitvanyok-a-foderacioban) generálunk a SimpleSMALphp számára.
openssl req -new -newkey rsa:2048 -x509 -days 3652 -nodes -out cert/saml-example-org.crt -keyout cert/saml-example-org.key
A fingerprint az alábbi módon kérdezhető le a legegyszerűbben
openssl x509 -fingerprint -noout -in cert/saml-example-org.crt
### Telepítés kész
Amennyiben elkészültünk a fenti lépésekkel, úgy a [https://service.example.org/simplesaml/](https://service.example.org/simplesaml/) címen elérjük a telepített SSP-nk webes adminfelületét, ahol megejthetjük a további beállítások nagy részét.
## Identity Provider (IdP) beállítás
### Alapbeállítások
**IdP** engedélyezése: a **config/config.php** fájlban kell a saml20 idp-t "true"-re állítani.
'enable.saml20-idp' => true,
### LDAP autentikáció
Meg kell adni, hogy az IdP milyen módon azonosítsa a felhasználót, amennyiben alapértelmezés szerint nem engedélyezett modult szeretnénk használni, úgy a megfelelő modult a `modules` könyvtár alatt engedélyezni kell. Az alábbi példában az LDAP alapú azonosítást mutatjuk be, amely külön modult nem igényel, alapértelmezés szerint része a telepített alkalmazásnak.
Javasolt az LDAP-ban egy olyan bejegyzést létrehozni az IdP számára, amely olvasni tudja a felhasználóknak a föderációban használt attribútumait. Az azonosítás alapértelmezett módon a felhasználó nevében történő újra bind-olással történik, így a jelszóhoz nem kell hozzáférést adni.
Ahhoz, hogy megadhassuk az LDAP-hoz tartozó beállításokat, a `config/authsources.php` fájlt kell szerkesztenünk. Az alábbi kódrészletet elegendő beszúrni, és az egyes változóknak a helyi LDAP-nak megfelelő adatokat értékül adni.
```php
'example-ldap' => array(
'ldap:LDAP',
/* The hostname of the LDAP server. */
'hostname' => 'ldap.example.org',
/* Whether SSL/TLS should be used when contacting the LDAP server. */
'enable_tls' => FALSE,
/*
* Which attributes should be retrieved from the LDAP server.
* This can be an array of attribute names, or NULL, in which case
* all attributes are fetched.
*/
'attributes' => NULL,
/*
* The pattern which should be used to create the users DN given the username.
* %username% in this pattern will be replaced with the users username.
*
* This option is not used if the search.enable option is set to TRUE.
'dnpattern' => 'uid=%username%,ou=people,dc=example,dc=org',
*/
/*
* As an alternative to specifying a pattern for the users DN, it is possible to
* search for the username in a set of attributes. This is enabled by this option.
*/
'search.enable' => TRUE,
/*
* The DN which will be used as a base for the search.
* This can be a single string, in which case only that DN is searched, or an
* array of strings, in which case they will be searched in the order given.
*/
'search.base' => 'ou=people,dc=example,dc=org',
/*
* The attribute(s) the username should match against.
*
* This is an array with one or more attribute names. Any of the attributes in
* the array may match the value the username.
*/
'search.attributes' => array('uid', 'mail'),
/*
* The username & password the simpleSAMLphp should bind to before searching. If
* this is left as NULL, no bind will be performed before searching.
*/
'search.username' => 'cn=simplesamlphp,dc=example,dc=org',
'search.password' => 'servicepassword',
'priv.read' => TRUE,
// The DN & password the SimpleSAMLphp should bind to before
// retrieving attributes. These options are required if
// 'priv.read' is set to TRUE.
'priv.username' => 'cn=simplesamlphp,dc=example,dc=org',
'priv.password' => 'servicepassword;,
),
```
### Metaadat alapok
A beállítandó IdP alapvető paraméterei a `metadata/saml20-idp-hosted.php` fájlban állíthatók. Az alábbi kódrészlet egy minimális, de már működő példát mutat.
```php
$metadata['__DYNAMIC:1__'] = array(
/*
* The hostname for this IdP. This makes it possible to run multiple
* IdPs from the same configuration. '__DEFAULT__' means that this one
* should be used by default.
*/
'host' => '__DEFAULT__',
/*
* The private key and certificate to use when signing responses.
* These are stored in the cert-directory.
*/
'privatekey' => 'saml-example-org.key',
'certificate' => 'saml-example-org.crt',
/*
* The authentication source which should be used to authenticate the
* user. This must match one of the entries in config/authsources.php.
*/
'auth' => 'example-ldap',
);
```
Megfelelő beállítások után a dinamikusan generált metadata a `/saml2/idp/metadata.php` útvonalon érhető el.
### Tesztelés
Legegyszerűbben a telepített SSP felületén tudjuk ellenőrizni, hogy a beállított autentikációs forrás működik-e. A felületen az Authentication fül alatt található egy 'Test authentication sources' link, amelyre kattintva látható minden beállított autentikációs forrás is, így a két alapértelmezett, teszt célokat szolgáló alatt a most beállított example-ldap névre hallgatónak is meg kell jelenni. (A közvetlen url erre az oldalra: simplesaml/module.php/core/authenticate.php) Ez utóbbira kattintva a beállított LDAP-ból autentikálva be kell tudnunk jelentkeznünk; siker esetén az LDAP-ból kinyerhető attribútumokat láthatjuk.
## Service Provider (SP) beállítás
### Alapbeállítások
A telepített alkalmazásunk által kezelt SP-ket a **config/authsources.php** fájlban tudjuk beállítani. Az *entityID, idp, discoURL* értékeket most hagyjuk *NULL* értéken és adjuk hozzá a **privatekey** / **certificate** részt.
A SimpleSAMLphp a tanúsítvány fájlokat a korábban létrehozott **cert** mappában fogja keresni, a fájlokat elég relatív elérési úttal megadni.
```php
'default-sp' => array(
'saml:SP',
// The entity ID of this SP.
// Can be NULL/unset, in which case an entity ID is generated based on the metadata URL.
'entityID' => NULL,
// The entity ID of the IdP this should SP should contact.
// Can be NULL/unset, in which case the user will be shown a list of available IdPs.
'idp' => NULL,
// The URL to the discovery service.
// Can be NULL/unset, in which case a builtin discovery service will be used.
'discoURL' => NULL,
'privatekey' => 'saml-example-org.key',
'certificate' => 'saml-example-org.crt',
),
```
A fenti beállítások alapján az SP entityID-ja megegyezik a metadata elérési útvonalával (szokásos megoldás SSP-nél), nem adunk meg alapértelmezett idp-t, ezáltal az SSP választási lehetőséget kínál fel számunkra, mikor az SP-re szeretnénk bejelentkezni, ill. most még Discovery Service URL-t sem adunk meg, hanem a beépítettet használjuk. Ez utóbbit majd a HREF-be történő integrációkor meg kell változtatni - lásd lejjebb.
Az SP készen áll arra, hogy összekössük egy IdP-vel (ez jellemzően szintén egy SimpleSAMLphp alkalmazás). Ehhez szükséges, hogy SP oldalon beállítsuk az IdP metadata-t és IdP oldalon is beállítsuk az SP metadata-t.
#### Metadata
#### Metadata fájlok
A különböző metadata template fájlok a **metadata-templates** mappában találhatóak. A nekünk szükséges template fájlt másoljuk át a metadata mappába.
* **SP** oldalon lennie kell egy **metadata/saml20-idp-remote.php** fájlnak. Ez a fájl tartalmazza az IdP eléréséhez szükséges adatokat.
cp metadata-templates/saml20-idp-remote.php metadata
* **IdP** oldalon lennie kell egy **metadata/saml20-sp-remote.php** fájlnak. Ez a fájl tartalmazza az SP eléréséhez szükséges adatokat.
cp metadata-templates/saml20-sp-remote.php metadata
#### Metadata letöltés
Ezen az oldalon megtaláljuk az SP vagy IdP-re vonatkozó **metadata**-t, **XML** és **PHP** formátumban: [https://example.org/simplesaml/module.php/saml/sp/metadata.php/default-sp?output=xhtml](https://example.org/simplesaml/module.php/saml/sp/metadata.php/default-sp?output=xhtml)
#### SP metadata beállítás IdP oldalon
A metadata **simplesaml** kezdőlapon, az alábbi helyen érhető el:
* Magyar nyelv esetén: "Föderáció" fül / "SAML 2.0 SP Metaadatok" pont alatt a "Mutasd a metaadatokat" linkre kattintva juthatunk el a fenti menüponthoz.
* Angol nyelv esetén: "Federation" fül / "SAML 2.0 SP Metadata" pont alatt a "Show metadata" linkre kattintva juthatunk el a fenti menüponthoz.
A "*SimpleSAMLphp fájl formátumban - akkor használható, ha a másik oldalon SimpleSAMLphp van*" mezőből tegyük a vágólapra az alábbi PHP kódot:
```php
$metadata['https://example.org/simplesaml/module.php/saml/sp/metadata.php/default-sp'] = array (
'SingleLogoutService' =>
array (
0 =>
array (
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
'Location' => 'https://example.org/simplesaml/module.php/saml/sp/saml2-logout.php/default-sp',
),
),
'AssertionConsumerService' =>
array (
0 =>
array (
'index' => 0,
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
'Location' => 'https://example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp',
),
1 =>
array (
'index' => 1,
'Binding' => 'urn:oasis:names:tc:SAML:1.0:profiles:browser-post',
'Location' => 'https://example.org/simplesaml/module.php/saml/sp/saml1-acs.php/default-sp',
),
2 =>
array (
'index' => 2,
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact',
'Location' => 'https://example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp',
),
3 =>
array (
'index' => 3,
'Binding' => 'urn:oasis:names:tc:SAML:1.0:profiles:artifact-01',
'Location' => 'https://example.org/simplesaml/module.php/saml/sp/saml1-acs.php/default-sp/artifact',
),
),
'contacts' =>
array (
0 =>
array (
'emailAddress' => 'admin@example.org',
'contactType' => 'technical',
'givenName' => 'Example Corp. IT Dept.',
),
),
'certData' => 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==',
);
```
A vágólapra másolt kódot IdP oldalon, a **metadata/saml20-sp-remote.php** fájl végére illesszük be.
#### IdP metadata beállítás SP oldalon
A metadata **simplesaml** kezdőlapon, az alábbi helyen érhető el:
* Magyar nyelv esetén: "Föderáció" fül / "SAML 2.0 IdP Metaadatok" pont alatt a "Mutasd a metaadatokat" linkre kattintva juthatunk el a fenti menüponthoz.
* Angol nyelv esetén: "Federation" fül / "SAML 2.0 IdP Metadata" pont alatt a "Show metadata" linkre kattintva juthatunk el a fenti menüponthoz.
A "*SimpleSAMLphp fájl formátumban - akkor használható, ha a másik oldalon SimpleSAMLphp van*" mezőből tegyük a vágólapra az alábbi PHP kódot:
```php
$metadata['https://idp.example.org/simplesaml/saml2/idp/metadata.php'] = array (
'metadata-set' => 'saml20-idp-remote',
'entityid' => 'https://idp.example.org/simplesaml/saml2/idp/metadata.php',
'SingleSignOnService' =>
array (
0 =>
array (
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
'Location' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
),
),
'SingleLogoutService' =>
array (
0 =>
array (
'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
'Location' => 'https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php',
),
),
'certData' => 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==',
'NameIDFormat' => 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient',
);
```
A vágólapra másolt kódot SP oldalon, a **metadata/saml20-idp-remote.php** fájl végére illesszük be.
### Tesztelés
A fent elvégzett alapbeállítások után már tudjuk tesztelni a, hogy a felépített IdP - SP kapcsolat működik-e.
SP oldalon nyissuk meg a **simplesaml** kezdőlapot:
* Magyar nyelv esetén: "Azonosítás (autentikáció)" fül / "Azonosítási (autentikációs) beállítások tesztelése" link / "default-sp" link-re kattintva tudjuk tesztelni az IdP - SP kapcsolatot.
* Angol nyelv esetén: "Authentication" fül / "Test configured authentication sources" link / "default-sp" link-re kattintva tudjuk tesztelni az IdP - SP kapcsolatot.
A legördülő menüben az IdP-nk "nevére" kattintva, be kell tudnunk jelentkezni (az IdP-n keresztül). Ha működik, akkor az IdP visszairányít az SP-re, kiírja az azonosított felhasználó attribútumait.
Az alapvető lépsekkel kész vagyunk, van egy működő SP-nk és egy működő IdP-nk.
## HREF-integráció
### Metadata beállítása (IdP és SP is)
Javasolt [dinamikus metaadatforrást (MDX)](https://help.edu.hu/books/hrefeduid-foderacio/page/mdx) használni, opcionálisan kiegészítve statikus állományokkal. Részletes leírás itt: [SimpleSAMLMixedMetadata](https://help.edu.hu/books/simplesamlphp/page/simplesamlmixedmetadata)
### IdP
Amennyiben van SSP alapú IdP-nk, melyet szeretnénk a föderáció részévé tenni, úgy a teendők a következők.
* (Az adminisztratív teendőktől itt most eltekintünk, a csatlakozás folyamata [itt van leírva](https://help.edu.hu/books/hrefeduid-foderacio/page/hrefjoin))
* Kell küldeni egy levelet a info@eduid.hu címre, benne néhány mondat mellett az IdP metaadatának URL-jével ([https://example.org/simplesamlphp/saml2/idp/metadata.php](https://example.org/simplesamlphp/saml2/idp/metadata.php))
* Ha minden rendben megy, akkor az IdP bekerül a [Resource_Registry](https://help.edu.hu/books/elavult-archiv/page/resource-registry)-be, ezáltal a föderációs metaadatba is.
* Az előző pontban leírt módon be kell állítani a központi metadata feldolgozását.
* Amennyiben a föderációs metaadatban már szerepel a mi IdP-nk is, úgy a föderáció valamelyik, tesztelési célokat szolgáló SP-jénél ki is próbálhatjuk a bejelentkezést.
* **Fontos**, hogy a föderációs Discovery Service óránként generálja újra az IdP-k listáját, így ennyi idő mindenképp szükséges, hogy az új IdP megjelenjen itt, az egyes SP-k pedig két óránként töltik újra a metaadatot, így előfordulhat, hogy azonnal nem fog minden működni, de néhány óra alatt várhatóan beindul. :)
* Tesztelésre használható oldal: [https://attributes.eduid.hu](https://attributes.eduid.hu)
* Ahhoz, hogy a Resource Registry-be is be tudjunk lépni és az IdP további, a föderációra vonatkozó beállításait meg tudjuk ejteni, ehhez az IdP-nek ki kell adnia az alábbi attribútumokat:
* [mail](https://help.edu.hu/books/hrefeduid-foderacio/page/href-attributum-specifikacio) - ez belépés után, manuálisan is beállítható
* [eduPersonPrincipalName](https://help.edu.hu/books/hrefeduid-foderacio/page/href-attributum-specifikacio)
* [schacHomeOrganizationType](https://help.edu.hu/books/hrefeduid-foderacio/page/href-attributum-specifikacio) (az attribútumot hamarosan kivezetjük a kötelező attribútumok közül)
* [eduPersonScopedAffiliation](https://help.edu.hu/books/hrefeduid-foderacio/page/href-attributum-specifikacio)
#### Attribútumok kezelése
Beállított IdP-nk alapértelmezés szerint azokat az attribútumokat adja ki, melyeket a metaadat alapján az SP kért (Lásd a metadatában a RequestedAttribute elemeket), és egyúttal alapból meg tudta szerezni a felhasználói adatbázisból, esetünkben az LDAP-ból. Mivel néhány attribútum nem szerepel az LDAP-ban, hanem az IdP-ben kell előállítani, így pár helyen módosítanunk kell az alapértelmezett konfiguráción.
A `metadata/saml20-idp-hosted.php` fájlba szerkesszük be az alábbi kódrészlet értelemszerűen módosított változatát. Az `'auth' => 'example-ldap',` sor alatt kezdjük. Fontos, hogy egyúttal a config.php `authproc.idp` részét kikommentezzük, nehogy az ottani sorszámokkal megadott default feladatok bekavarjanak.
```php
'AttributeNameFormat' => 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',
'userid.attribute' => 'uid', // Itt adjuk meg, hogy mely, az LDAPból származó attribútum alapján fogja az IdP kiszámítani az eduPersonTargetedID-t
'authproc' => array(
10 => array(
'class' => 'core:AttributeMap',
'uid' => 'eduPersonPrincipalName'
//Itt az 'uid' az az attribútum az LDAP-ban, amely a felhasználó azonosítóját tartalmazza, mert ebből képezzük az eduPersonPrincipalName-t.
),
# 20 => array(
# 'class' => 'core:AttributeAdd',
# 'schacHomeOrganizationType' => array('urn:schac:homeOrganizationType:hu:university')
# //Kötelező statikus attribútum az [[HREFAttributeSpec#schacHomeOrganizationType|intézmény jellegének]] megfelelően
# ),
30 => array(
'class' => 'core:AttributeAlter',
'subject' => 'eduPersonPrincipalName',
'pattern' => '/^.*$/',
'replacement' => '${0}@intezmenydomain.hu',
// Itt adjuk hozzá az intézményi scope-ot az eduPersonPrincipalName már meglévő értékéhez
),
40 => array(
'class' => 'core:AttributeAlter',
'subject' => 'eduPersonAffiliation',
'pattern' => '/^.*$/',
'replacement' => '${0}@intezmenydomain.hu',
// Itt adjuk hozzá az intézményi scope-ot az eduPersonAffiliation már meglévő értékéhez
),
50 => array(
'class' => 'core:AttributeMap',
'eduPersonAffiliation' => 'eduPersonScopedAffiliation'
// Az LDAP-ból eduPersonAffiliation-ként érkező attribútumból föderációs elvárásoknak megfelelően eduPersonScopedAffiliationt készítünk
),
60 => array(
'class' => 'core:AttributeAdd',
'eduPersonScopedAffiliation' => array('member@intezmenydomain.hu')
// Az eduPersonScopedAffiliation-ben tesztelés céljából kiadhatjuk member értéket,
// így ha LDAP-ból nem jön érték, akkor is láthatjuk, hogy működik az attribútum kiadás
),
61 => array(
'class' => 'core:TargetedID',
'nameId' => TRUE,
),
// Itt állítjuk be, hogy az IdP előállítson és kiadhasson állandóazonosítóként eduPersonTargetedID-t, ha kérik
70 => array('class' => 'core:AttributeMap',
'name2oid'
// Az LDAP-os attribútum nevekből itt kreálunk szabványos urn:oid formátumúakat
),
80 => 'core:AttributeLimit',
), // .authproc
'simplesaml.nameidattribute' => 'eduPersonPrincipalName',
'attributeencodings' => array(
'urn:oid:1.3.6.1.4.1.5923.1.1.1.10' => 'raw',
),
'sign.logout' => true
```
* További tudnivalók a [Resource Registry-ről](https://help.edu.hu/books/elavult-archiv/page/resource-registry), ill. a [Föderációs attribútum specifikációról](https://help.edu.hu/books/hrefeduid-foderacio/page/href-attributum-specifikacio).
* Ha minden rendben ment, akkor a Resource Registry-ben regisztrált IdP-hez tartozó adminisztrációs jogok átkerülnek az IdP technikai gazdájához, s ezzel a folyamat kész is.
### SP
Amennyiben IdP-t is beállítottunk, és be is tudunk lépni a Resource Registry-be, úgy nincs más dolgunk, mint az RR-ben új SP-t hozzáadni a föderációhoz, amely a megfelelő átfutási idő után a föderáció minden tagjánál látható is lesz.
Ellenkező esetben (nincs IdP, és nem is tervezünk beállítani), akkor az IdP hozzáadásánál részletezett pontokon kell végig menni a metaadat betöltéséig, s a továbbiakat az említett e-mail címen megbeszélni.
#### Attribútum scopeok használata
A HREF föderáció IdP-i ún. scopeolt attribútumokat is használnak. Ez a scopeolás azt jelenti, hogy minden egyes IdP csak a saját scopejában ad ki attribútumokat, és a Shibboleth SP-k ezt ellenőrzik is. A scope és az attribútum valódi értéke egy '@' karakterrel kerül elválasztásra (ilyen attribútumok jelenleg: [eduPersonScopedAffiliation](https://help.edu.hu/books/hrefeduid-foderacio/page/href-attributum-specifikacio) illetve [eduPersonPrincipalName](https://help.edu.hu/books/hrefeduid-foderacio/page/href-attributum-specifikacio)).
A SimpleSAMLphp alapértelmezett telepítése nem szűri a hibásan scopeolt értékeket. Kiegészítő modulként szűrésre használható az NIIF által fejlesztett [attributescope modul](https://github.com/NIIF/simplesamlphp-module-attributescope), ami reményeink szerint rövid távon a hivatalos SimpleSAMLphp kiadás része lehet.
A telepítésről és konfigurációról bővebben itt lehet olvasni: [https://github.com/NIIF/simplesamlphp-module-attributescope](https://github.com/NIIF/simplesamlphp-module-attributescope)
* Az `attributescope` modul használata esetén a következőképp kell módosítani a `config/config.php` fájlt:
```php
authproc.sp = array(
...
// 49 => array('class' => 'core:AttributeMap', 'oid2name'),
50 => array( 'class' => 'attributescope:FilterAttributes'
),
...
),
```
Figyeljünk arra, hogy mire a modulhoz ér a vezérlés, az attribútumok nevei *friendlyName* alakúak legyenek (ne pedig *oid*-ok). A példában erre utal a 49-es sor.
# SimpleSAMLphp proxy vidyo portálhoz
# Vidyo Portal Authentication Proxy
A vidyo portál utolsó fejlesztései lehetővé tették a SAML alapú authentikációt, és authorizációt.
Az implementáció nem teljesen fedi le a SAML feature-öket, az SP implementáció csak egy IdP-vel képes kapcsolatot létesíteni.
A portált a simpleSAMLphp proxy-ként való telepítésével tehetjük egy föderáció tagjává.
## simpleSAMLphp telepítése
A simplesamlphp telepítését elvégezzük a [dokumentáció](https://simplesamlphp.org/docs/stable/simplesamlphp-install) szerint.
## SSP IdP oldalának konfigurálása, illesztés a Vidyo portál felé
Legelőször is engedélyezni kell az IdP funkciót
*config/config.php*
'enable.saml20-idp' => true,
Gyártsuk le az IdP certificate-jét, és rakjuk a *cert* könyvtárba *idp.pem*, illetve *idp.crt* néven.
cd cert
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out idp.crt -keyout idp.pem
*metadata/saml20-idp-hosted.php*
'auth' => 'default-sp',
'privatekey' => 'idp.pem',
'certificate' => 'idp.crt',
),
A vidyo portál admin felületéről le kell tölteni a portál metaadatát, és el kell menteni a metadata könyvtárba.
metadata/vidyo-sp.xml
Erre hivatkozni kell a *config/config.php*-ben is:
'metadata.sources' => array(
...
array('type' # > 'xml', 'file' > 'metadata/vidyo-sp.xml'), // vidyo sp
... ),
### Vidyo admin portál
A portálon be kell állítani,
* hogy az azonosítás SAML alapú legyen, *Authentication Type*
* fel kell tölteni az IdP metaadatát, ezt az ssp telepítés *saml2/idp/metadata.php* oldaláról tölthetjük le. *Identity Provider (IdP) Metadata XML*
* be kell állítani az auto provisioninget, *SAML provision type*
Az előző fejezetben említett portál metaadatát ezen az oldalon érjük el. *View Service Provider (SP) metadata XML*
Össze kell illeszteni a SAML rétegből jövő attribútumokat a Vidyo portál által használt adatmodellel. *Edit IdP Attribute Mapping...*
A _SAML IdP Attribute Name_ oszlopokba az SSP-től kapott attribútum neveket kell írni. Ha a proxy IdP oldalán a példa szerint állítottuk be az *AttributeMap* szűrőt, akkor itt az attribútumok friendly nevét kell beírnunk. Tipp:
Bizonyos attribútumoknál lehetőség van érték mapping-re is, tipikusan csoport, vagy típus jellegű attribútumoknál, ahol a kapott attirbútumok értéke alapján
történik a megfeleltetés.
## SSP SP oldalának konfigurálása, illesztés a föderációba
A proxy egyik oldala a föderáció felé, mint SP viselkedik. Az authsource-ot 'default-sp'-nek nevezzük el, erre kell hivatkozni a későbbiekben az IdP konfigurációban.
A *config/config.php* file-ba
Hogy a vidyo portál, és egyé authentikációs szűrők futtatásakor az attribútum megfeleltetéseknél ne okozzanak gondot az oid formátumú attribútum nevek, mielőtt kiadjuk őket, az *AttributeMap* szűrő segítségével alakítsuk át az attribútum neveket.
*config/config.php*
'authproc.sp' => array(
...
200 # > array('class' > 'core:AttributeMap', 'oid2name'),
...
),
Ha még nem tettük meg, rakjunk ide is certificate-et.
cd cert
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out sp.crt -keyout sp.pem
és könyveljük be a *config/authsrouces.php* -ba
'default-sp' => array(
'saml:SP',
...
'privatekey' => 'sp.pem',
'certificate' => 'sp.crt',
...
### metadata
Az SP-t regisztráljuk be a kívánt föderációba a föderáció által megadott szabályok alapján.
### metarefresh
Hogy a metadadatok mindig napra készek legyenek, gondoskodjunk a metarefresh és cron modul beállításáról.
A konfigurációs file-okat a config könyvtárba kell elhelyezni a sablonokat a modulok config-templates alkönyvtáraiban találjuk meg.
A modulok bekapcsolásáról a rendszer konfigurációban rendelkezhetünk a legegyszerűbben.
*config/config.php*
'module.enable' => array(
'cron' => TRUE,
'metarefresh' => TRUE,
),
# Alkalmazások samlizálást segítő teszt IdP simplesamlPHP segítségével
1. Telepítünk egy SSP egyedet valamelyik szerverünkre.
2. Engedélyezzük a **userpass** auth forrás modult.
touch modules/exampleauth/enable
3. Elrendezzük a metadatákat.
4. Az authsources.php file-t valahogy így alakítjuk ki:
```php
array(
// The default is to use core:AdminPassword, but it can be replaced with
// any authentication source.
'core:AdminPassword',
),
'multi' => array(
'multiauth:MultiAuth',
/*
* The available authentication sources.
* They must be defined in this authsources.php file.
*/
'sources' => array('projekt1', 'projekt2'),
),
'projekt1' => array(
'exampleauth:UserPass',
'tesztuser1:tesztuser1' => array(
'eduPersonPrincipalName' => array('tesztuser1@example.com'),
'uid' => array('tesztuser1'),
'cn' => "Nemecsek Ernő",
'sn' => "Nemecsek",
'givenName' => "Ernő",
'mail' => "devnull@example.com",
'homePostalAddress' => "1234 Budapest, Nincsisilyen utca 2.",
'schacDateOfBirth' => "19751221",
'schacPlaceOfBirth' => "Budapest",
'niifPersonMothersName' => "Törőcsik Mari",
'niifPersonResidentalAddress' => "3456 Nagyabajom, Mitírjakide utca 2.",
),
'tesztuser2:tesztuser2' => array(
'eduPersonPrincipalName' => array('tesztuser2@example.com'),
'uid' => array('tesztuser2'),
'cn' => "Nemecsek Ernő 2",
'sn' => "Nemecsek",
'givenName' => "Ernő",
'mail' => "devnull@example.com",
'homePostalAddress' => "1234 Budapest, Nincsisilyen utca 2.",
'schacDateOfBirth' => "19751221",
'schacPlaceOfBirth' => "Budapest",
'niifPersonMothersName' => "Törőcsik Mari",
'niifPersonResidentalAddress' => "3456 Nagyabajom, Mitírjakide utca 2.",
),
),
'projekt2' => array(
'exampleauth:UserPass',
'tesztuser1:tesztuser1' => array(
'eduPersonPrincipalName' => array('tesztuser1@example.com'),
'uid' => array('tesztuser1'),
'cn' => "Nemecsek Ernő",
'sn' => "Nemecsek",
'givenName' => "Ernő",
'mail' => "devnull@example.com",
'homePostalAddress' => "1234 Budapest, Nincsisilyen utca 2.",
'schacDateOfBirth' => "19751221",
'schacPlaceOfBirth' => "Budapest",
'niifPersonMothersName' => "Törőcsik Mari",
'niifPersonResidentalAddress' => "3456 Nagyabajom, Mitírjakide utca 2.",
),
'tesztuser2:tesztuser2' => array(
'eduPersonPrincipalName' => array('tesztuser2@example.com'),
'uid' => array('tesztuser2'),
'cn' => "Nemecsek Ernő 2",
'sn' => "Nemecsek",
'givenName' => "Ernő",
'mail' => "devnull@example.com",
'homePostalAddress' => "1234 Budapest, Nincsisilyen utca 2.",
'schacDateOfBirth' => "19751221",
'schacPlaceOfBirth' => "Budapest",
'niifPersonMothersName' => "Törőcsik Mari",
'niifPersonResidentalAddress' => "3456 Nagyabajom, Mitírjakide utca 2.",
),
),
);
```
# SimpleSAMLphp NIIF ldap séma mapping
A simpleSAMLphp különböző attribútum mappinget használ az attribúmnevek átfordításaihoz. A href ldap sémához még nincs, ezt a két file tartalmazza az oid - name oda-vissza mapping-et. Az attributemap könyvtárban van a helyük. A config.php authproc szabályai között kell felvenni őket, amikor szükség van rá.
config/config.php
```php
...
'authproc.sp' => array(
...
11 => array(
'class' => 'core:AttributeMap', 'oid-href'
),
...
),
...
```
attributemap/href-oid.php
```php
*
*/
$attributemap = array(
'niifPersonCityOfBirth' => 'urn:oid:1.3.6.1.4.1.11914.0.1.155',
'niifPersonDateOfBirth' => 'urn:oid:1.3.6.1.4.1.11914.0.1.152',
'niifPersonActivityStatus' => 'urn:oid:1.3.6.1.4.1.11914.0.1.153',
'niifPersonJoinDate' => 'urn:oid:1.3.6.1.4.1.11914.0.1.169',
'niifPersonOrgID' => 'urn:oid:1.3.6.1.4.1.11914.0.1.154',
'niifCertificateSubjectDN' => 'urn:oid:1.3.6.1.4.1.11914.0.1.151',
'niifEduPersonFacultyDN' => 'urn:oid:1.3.6.1.4.1.11914.0.1.161',
'niifPersonPosition' => 'urn:oid:1.3.6.1.4.1.11914.0.1.167',
'niifStatus' => 'urn:oid:1.3.6.1.4.1.11914.0.1.1',
'niifPersonIdentityNumber' => 'urn:oid:1.3.6.1.4.1.11914.0.1.158',
'niifTitle' => 'urn:oid:1.3.6.1.4.1.11914.0.1.2',
'niifCertificateSHA1Fingerprint' => 'urn:oid:1.3.6.1.4.1.11914.0.1.173',
'niifEduPersonAttendedCourse' => 'urn:oid:1.3.6.1.4.1.11914.0.1.164',
'niifEduPersonArchiveCourse' => 'urn:oid:1.3.6.1.4.1.11914.0.1.171',
'niifEduPersonHeldCourse' => 'urn:oid:1.3.6.1.4.1.11914.0.1.172',
'niifPrefix' => 'urn:oid:1.3.6.1.4.1.11914.0.1.0',
'niifPersonDegree' => 'urn:oid:1.3.6.1.4.1.11914.0.1.166',
'niifEduPersonFaculty' => 'urn:oid:1.3.6.1.4.1.11914.0.1.160',
'niifEduPersonMajor' => 'urn:oid:1.3.6.1.4.1.11914.0.1.162',
'niifPersonQuitDate' => 'urn:oid:1.3.6.1.4.1.11914.0.1.170',
'niifPersonMothersName' => 'urn:oid:1.3.6.1.4.1.11914.0.1.157',
'niifEduPersonAcademicYear' => 'urn:oid:1.3.6.1.4.1.11914.0.1.163',
'niifPersonCountyOfBirth' => 'urn:oid:1.3.6.1.4.1.11914.0.1.156',
'niifUniqueId' => 'urn:oid:1.3.6.1.4.1.11914.0.1.3',
'niifPersonPrefix' => 'urn:oid:1.3.6.1.4.1.11914.0.1.165',
'niifActiveMemberOf' => 'urn:oid:1.3.6.1.4.1.11914.0.1.168',
'niifPersonResidentalAddress' => 'urn:oid:1.3.6.1.4.1.11914.0.1.159',
'niifIDPrefix' => 'urn:oid:1.3.6.1.4.1.11914.0.1.100',
);
?>
```
/attributemap/oid-href.php
```php
*
*/
$attributemap = array(
'urn:oid:1.3.6.1.4.1.11914.0.1.155' => 'niifPersonCityOfBirth',
'urn:oid:1.3.6.1.4.1.11914.0.1.152' => 'niifPersonDateOfBirth',
'urn:oid:1.3.6.1.4.1.11914.0.1.153' => 'niifPersonActivityStatus',
'urn:oid:1.3.6.1.4.1.11914.0.1.169' => 'niifPersonJoinDate' ,
'urn:oid:1.3.6.1.4.1.11914.0.1.154' => 'niifPersonOrgID',
'urn:oid:1.3.6.1.4.1.11914.0.1.151' => 'niifCertificateSubjectDN',
'urn:oid:1.3.6.1.4.1.11914.0.1.161' => 'niifEduPersonFacultyDN',
'urn:oid:1.3.6.1.4.1.11914.0.1.167' => 'niifPersonPosition' ,
'urn:oid:1.3.6.1.4.1.11914.0.1.1' => 'niifStatus',
'urn:oid:1.3.6.1.4.1.11914.0.1.158' => 'niifPersonIdentityNumber',
'urn:oid:1.3.6.1.4.1.11914.0.1.2' => 'niifTitle',
'urn:oid:1.3.6.1.4.1.11914.0.1.173' => 'niifCertificateSHA1Fingerprint',
'urn:oid:1.3.6.1.4.1.11914.0.1.164' => 'niifEduPersonAttendedCourse',
'urn:oid:1.3.6.1.4.1.11914.0.1.171' => 'niifEduPersonArchiveCourse',
'urn:oid:1.3.6.1.4.1.11914.0.1.172' => 'niifEduPersonHeldCourse',
'urn:oid:1.3.6.1.4.1.11914.0.1.0' => 'niifPrefix',
'urn:oid:1.3.6.1.4.1.11914.0.1.166' => 'niifPersonDegree' ,
'urn:oid:1.3.6.1.4.1.11914.0.1.160' => 'niifEduPersonFaculty',
'urn:oid:1.3.6.1.4.1.11914.0.1.162' => 'niifEduPersonMajor',
'urn:oid:1.3.6.1.4.1.11914.0.1.170' => 'niifPersonQuitDate' ,
'urn:oid:1.3.6.1.4.1.11914.0.1.157' => 'niifPersonMothersName',
'urn:oid:1.3.6.1.4.1.11914.0.1.163' => 'niifEduPersonAcademicYear',
'urn:oid:1.3.6.1.4.1.11914.0.1.156' => 'niifPersonCountyOfBirth',
'urn:oid:1.3.6.1.4.1.11914.0.1.3' => 'niifUniqueId',
'urn:oid:1.3.6.1.4.1.11914.0.1.165' => 'niifPersonPrefix' ,
'urn:oid:1.3.6.1.4.1.11914.0.1.168' => 'niifActiveMemberOf' ,
'urn:oid:1.3.6.1.4.1.11914.0.1.159' => 'niifPersonResidentalAddress',
'urn:oid:1.3.6.1.4.1.11914.0.1.100' => 'niifIDPrefix',
);
?>
```
# Single Logout in Shibboleth IdP
## Important notes on third party cookies
In some browsers, the IFrame-driven front-channel logout doesn't work due to the browser blocking [third party cookies](http://en.wikipedia.org/wiki/HTTP_cookie#Third-party_cookies).
Every cookie which is sent to a foreign domain via img, iframe, script, etc. tags is considered to be third party, so the session cookie of the SP software in a foreign domain is third party cookie when it is sent in an IFrame. By blocking these cookies, the SP doesn't receive the session cookie and thus it could stop processing the logout request at this point.
Additional links:
* [Shibboleth-dev thread on the issue](http://n2.nabble.com/Frames-cookies-question-td4127538.html#a4127538)
* [How to disable third party cookies in firefox](http://support.mozilla.com/en-US/kb/Disabling+third+party+cookies)
* [Additional explanation in Mozilla Bugzilla](https://bugzilla.mozilla.org/show_bug.cgi?id=417800#c11)
* [Same origin policy for cookies](http://code.google.com/p/browsersec/wiki/Part2#Same-origin_policy_for_cookies)
* [Further information on third party cookie handling](http://code.google.com/p/browsersec/wiki/Part2#Third-party_cookie_rules)
"Although any third-party cookie restrictions are not a sufficient method to prevent cross-domain user tracking, they prove to be rather efficient in disrupting or impacting the security of some legitimate web site features, most notably certain web gadgets and authentication mechanisms."
### Why service providers might need the session cookie
Most of the services do not need the session cookie itself, they only need the NameIdentifier, which is carried by the logout request, so back-channel logout requests are enough for them. But there might be service providers which do not implement back-channel bindings (eg. SimpleSAMLphp), or need front-channel application notification.
### Why not fully back-channel?
SAML profiles specification (section 4.4.3.1) clearly states that front-channel should be preferred when sending the logoutrequest to the session authority (IdP). If the user interface is generated by the IdP, it could inform the user about the whole logout process, and each SP response. If the SP would use back-channel logoutrequest, the IdP's response would only contain minimal information (ie. success or failure), and this is not desirable. Also, the IdP would need to execute back-channel requests in parallel and synchronize them with the originating request, so this would make the processing code much more complex.
### Technical solution
Our proposal is to prefer back-channel endpoints at the service provider side, unless your application needs to be notified via front-channel. For example,
* if your application behind your SP needs the session cookie with the notification, use only front-channel bindings in the SP metadata,
* otherwise use only back-channel binding in the SP metadata.
By these mutually exclusive endpoint sets, the SP can clearly advise the IdP which binding it should use when contanting this SP. Thus on the IdP side, both implementations need to be available.
### Non-technical solution
Another option would be to add a new requirement for your end users. You can claim that banning third-party cookies is unsupported (because it breaks SLO), just like disabling all cookies (which breaks SSO). Convincing your users (and the Shibboleth developers to accept this solution) might be dubious, though.
## Features
* Implements SAML2 Single Logout profile
* If initiated by an SP, user must confirm the single logout process: one can choose to logout only from the initiating SP and the IdP.
* Highly customizable front-channel logout interface which leverages javascript and asynchronous operations in order to provide a clean, simple UI.
* UI is usable with javascript disabled.
* Supports localized SP name lookup via Organization elements in SAML metadata .
* Fallback to back-channel logout if front-channel is not supported by the SP.
* Supports Shibboleth SSO sessions (if the SP initiates sessions using Shibboleth1.3 protocol, but supports SAML2 logout).
* Supports full back-channel operation.
* Supports IdP-initiated Single Logout.
## UI customization
The UI is located in two JSP files:
* `sloQuestion.jsp` the user chooses whether she wants to logout from all service providers or just from the provider where she came from.
* `sloController.jsp` is the logout UI where every session participant and their corresponding logout status is shown. At the end of the logout process, the user is notified if the single logout was completed.
### How it works
#### SLOServlet
The heart of the logout process is the `SLOServlet`. This servlet is responsible for these actions:
* rendering the logout question and controller page
* initiating front-channel or back-channel logout to one SP (`SLOServlet?action&entityID=...`)
* returning the logout status as a JSON string (`SLOServlet?status`)
#### With javascript
The controller renders a page where an iframe is placed for every active session participant. This iframe calls the `SLOServlet?action&entityID=...` URL where the logout request is issued for the given session participant. If the request is front-channel, the iframe will make a front-channel SAML message exchange with the peer (using HTTP-Redirect or POST bindings).
The status of the single logout process is queried via asynchronous requests. The status response from `SLOServlet` is a JSON array. This JSON array contains one object with the `entityID` and `logoutStatus` properties for each session participant.
The logout status can be one of the followings:
* `LOGGED_IN`: logout is not initiated for this participant yet.
* `LOGOUT_ATTEMPTED`: logout was initiated.
* `LOGOUT_FAILED`: logout failed.
* `LOGOUT_UNSUPPORTED`: SAML2 logout is not supported by the participant (the metadata does not contain the necessary endpoints).
* `LOGOUT_TIMED_OUT`: timed out waiting for a response.
* `LOGOUT_SUCCEEDED`: logout was successful.
Status queries are issued using exponential backoff timing, until the timeout is reached. Please see the `sloController.jsp` for the exact timing used.
#### Without javascript
Controller renders an HTML page with `