SSP QuickStart

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.

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 (legalább 5.2.0 verzió)
 * A következő PHP kiterjesztéseket engedélyezni kell
 * LDAP-ból történő autentikáció esetén:
 * Adatbázisból történő autentikáció esetén a megfelelő adatbázis-csatolót ,
 * RADIUS szerveren keresztül történő autentikáció esetén:
 * Assertion-ök titkosítása esetén:
 * Memcache használata esetén:
 * Memcache használata esetén:

Letöltés
A legfrissebb változat letölthető http://code.google.com/p/simplesamlphp/ címről

cd /var tar xzf simplesamlphp-1.x.y.tar.gz mv simplesamlphp-1.x.y simplesamlphp

Alapértelmezés szerint a  alatt szeretne majd működni, ez természetesen változtatható, de most maradunk az eredeti beállításoknál.

Apache konfigurálás
A webről csak a  könyvtárat kell elérni.

Alias /simplesaml /var/simplesamlphp/www

Alapbeállítások
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 konfigurációs fájlban. 'auth.adminpassword'       => 'ujjelszotirdide', 'secretsalt' => 'randombytesinsertedhere', A karaktersorozat előállításában segíthet az alábbi parancs: tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' /dev/null;echo 'technicalcontact_name'    => 'Gipsz Jakab', 'technicalcontact_email'   => 'jakab.gipsz@example.org', 'language.default'     => 'hu', 'timezone' => 'Europe/Budapest',
 * Az "admin" felhasználó jelszavát, mellyel webes felületen keresztül be tud lépni a települő SSP-be.
 * Titkosítási feladatokhoz szükséges "salt", azaz véletlenszerűen összeálló karaktersorozat
 * Elérhetőségeket, amely adatok bekerülnek majd a generált metaadatba
 * Nyelv és időzóna adatok

Telepítés kész
Amennyiben elkészültünk a fenti lépésekkel, úgy a 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.

IdP funkció engedélyezése
A  fájlt kell szerkesztenünk, s engedélyezni a saml20 idp lehetőséget. 'enable.saml20-idp' => true,

Autentikáció LDAP alapon
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  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.

Ahhoz, hogy megadhassuk az LDAP-hoz tartozó beállításokat, a  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. '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' => FALSE, /*    * 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' => NULL, 'search.password' => NULL, ),

Metaadat alapok
A beállítandó IdP alapvető paraméterei a  fájlban állíthatók. Az alábbi kódrészlet egy minimális, de már működő példát mutat.

$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' => 'idp.example.org.key',    'certificate' => 'idp.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', );

Teszteléshez is érdemes, éles használathoz pedig elengedhetetlen, hogy a csomagban érkezett tanúsítványt felülírjuk, ezt célszerű mihamarabb megtenni. Ehhez az alábbi parancs lehet segítségünkre. openssl req -new -x509 -days 3652 -nodes -out idp.example.org.crt -keyout idp.example.org.key A fingerprint az alábbi módon kérdezhető le a legegyszerűbben openssl x509 -fingerprint -noout -in idp.example.org.crt

Megfelelő beállítások után a dinamikusan generált metadata a  ú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.

Alapadatok
A telepített alkalmazásunk által kezelt SP-ket a  fájlban tudjuk beállítani.

'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.pem',        'certificate' => 'saml.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 IdP beállításához hasonlóan itt is szükség lesz egy tanúsítvány generálására a  könyvtárba. Ehhez segítség lehet az alábbi parancs.

openssl req -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem

Tesztelés
Amennyiben IdP is beállításra került, úgy a legcélszerűbb ezt összehangolni az SP-vel. Ehhez egyfelől a  fájlban meg kell adni az IdP adatait, amely esetünkben az alábbiak szerint fest.

$metadata['https://example.org/simplesaml/saml2/idp/metadata.php'] = array(       'name' => array( 'en' => 'TestSP' ),       'SingleSignOnService'  => 'https://example.org/simplesaml/saml2/idp/SSOService.php',        'SingleLogoutService'  => 'https://example.org/simplesaml/saml2/idp/SingleLogoutService.php',        'certFingerprint'      => 'afe71c28ef740bc87425be13a2263d37971da1f9' );

Ehhez hasonlóan a  fájlban meg kell adnunk az SP adatait. Teszteléshez az alábbiak elegendők:

$metadata['https://example.org/simplesaml/module.php/saml/sp/metadata.php/default-sp'] = array ( 'AssertionConsumerService' => 'https://example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp',  'SingleLogoutService' => 'https://example.org/simplesaml/module.php/saml/sp/saml2-logout.php/default-sp', );

Ezek után az IdP tesztelésénél már említett oldalon a default-sp opciót kiválasztva, majd a legördülő menüben a TestSP-re kattintva be kell tudnunk jelentkezni az IdP-n keresztül. Ha működik, akkor az alapvető lépsekkel kész vagyunk, van egy működő SP-nk és egy működő IdP-nk.

Metadata beállítása (IdP és SP is)

 * Az SSP-nél be kell állítani metaadat forrásként a központi metaadatot
 * Első lépésként engedélyezzük, hogy az SSP automatikusan frissíthesse a metaadatot, ill. az ezt elvégző két modult

touch modules/metarefresh/enable cp modules/metarefresh/config-templates/*.php config/ touch modules/cron/enable cp modules/cron/config-templates/*.php config/


 * Létrehozunk egy könyvtárat, ahová letöltésre kerül az központi metaadat XML fájlja

mkdir metadata/metarefresh-href chmod g+rw metadata/metarefresh-href
 * Ezek után be kell állítani a metaadat kokrét adatait a  fájlban

$config = array(   'sets' => array( 'hu' => array(           'cron'      => array('hourly'),            'sources'   => array( array(                   'src' => 'http://metadata.eduid.hu/2011/href.xml',                    'validateFingerprint' => 'FE:AE:0B:E8:FB:59:ED:F7:CB:7F:69:DF:19:4F:8B:6D:C7:F6:96:66',                    'template' => array( 'authproc' => array(                           51 => array('class' => 'core:AttributeMap', 'oid2name'),                        ), ),               ),            ),            'expireAfter'       => 60*60*24*4, // Maximum 4 days cache time.            'outputDir'     => 'metadata/metarefresh-href/',            'outputFormat' => 'flatfile',        ), ), );
 * Be kell állítani, hogy az SSP az automata által generált fájlokból dolgozzon. Ehhez a  fájlban keressük ki a   szakaszt, és az alábbiak szerint szerkesszük át. Amennyiben nem csak a központi metaadatból szeretnénk dolgozni, úgy további sorokat is megadhatunk itt bemutatott mintájára.

'metadata.sources' => array(   array('type' => 'flatfile', 'directory' => 'metadata/metarefresh-href'), ),


 * Végül le kell futtatni kézzel a cronjobot, amelyet az SSP webes felületén tudunk megtenni a Configuration fül alatt, a Cron module information page menüpontban. Ekkor létrejönnek a fájlok (majd óránként frissülnek is, ha beállítjuk cronjobként).

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.
 * (A jelenleg is formálódó adminisztratív teendőktől itt most eltekintünk)
 * Kell küldeni egy levelet a [mailto:aai@niif.hu aai@niif.hu] címre, benne néhány mondat mellett az IdP metaadatának URL-jével (https://example.org/simplesamlphp/saml2/idp/metadata.php)
 * Ha minden rendben megy, akkor az IdP bekerül a 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 egy-két óra alatt várhatóan beindul. :)


 * Tesztelésre használható oldal: https://wiki.aai.niif.hu/shibtest.php


 * 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 - ez belépés után, manuálisan is beállítható
 * eduPersonPrincipalName
 * schacHomeOrganizationType
 * eduPersonScopedAffiliation

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.


 * 1. Az  fájlba az 's'-betűhöz szúrjuk be az alábbi sort:

'schacHomeOrganizationType' => 'urn:oid:1.3.6.1.4.1.25178.1.2.10',
 * 2. A  fájlba szerkesszük be az alábbi kódrészlet értelemszerűen módosított változatát. Az   sor alatt kezdjük.

'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 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 ),       ),       'simplesaml.nameidattribute' => 'eduPersonPrincipalName', 'attributeencodings' => array(              'urn:oid:1.3.6.1.4.1.5923.1.1.1.10' => 'raw', ),


 * További tudnivalók a Resource Registry-ről, ill. a Föderációs attribútum specifikációról.


 * 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 illetve eduPersonPrincipalName).

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, ami reményeink szerint rövid távon a hivatalos SimpleSAMLphp kiadás része lehet.


 * Az  modul használata esetén a következőképp kell módosítani a   fájlt:

'template' => array(  'authproc' => array( 51 => array('class' => 'core:AttributeMap', 'oid2name'), 55 => array('class' => 'attributescope:FilterAttributes'), ),  'scopedattributes' => array('eduPersonScopedAffiliation', 'eduPersonPrincipalName'), ),