Installation af Nemlog-in gennem WAYF

Denne guide beskriver hvordan man forbinder et ding.TING-site til WAYF (Where Are You From) Nemlog-in løsningen. Dokumentet antager, at man allerede har et ding.TING-site kørende,  før man installerer den udvidelse, som pt. ikke er en del af ding.TING.core.

Før denne løsning kan benyttes, skal man indgå en aftale med WAYF og SKAT omkring Nemlog-in. Du kan læse mere om indgåelse af aftaler omkring WAYF servicen på deres hjemmeside under “Hvordan bliver min institution tilsluttet?”.

Ding.ting WAYF løsningen består af disse komponenter:

1. SimpleSAMLphp til at kommunikere med WAYF
2. Ding WAYF modulet (ding_wayf),
3. SSL certifikat til bibliotekets domæne.

1. SimpleSAMLphp

SimpleSAMLphp er en autentifikationsløsning skrevet i PHP, som kan kommunikere over SAML protokollen. Det er open source og kan hentes fra hjemmesiden http://simplesamlphp.org/.

Installation (Linux)

1. Download simple SAML php fra http://simplesamlphp.googlecode.com/files/simplesamlphp-1.8.0.tar.gz.
2. Pak den ud i /var/simplesamlphp.

Konfiguration

Første skridt er at lave et alias i webserver-konfigurationen til SimpleSAMLphp under https opsætning, så den kan tilgås sikret via en browser. Herunder er et eksempel på denne konfiguration til en Apache web-server.

Alias /simplesaml /var/simplesamlphp/www
<Directory /var/simplesaml/www/>
    Options Indexes FollowSymLinks MultiViews
    AllowOverride All
    Order allow,deny
    allow from all
</Directory>

Test at du kan tilgå simple SAML på https://<domain>/simplesaml. Hvis det lykkes er næste skridt at konfigurere simple SAML til at kommunikere med WAYF serverne.

SSL Certifikater

SimpleSAMLphp benytter dit domænes SSL certifikat til at kommunikere sikret med WAYF serverne. Du skal altså have adgang til dit certifikat for at kunne konfigurere SimpleSAMLphp. Dit certifikat skal være uden kodeord, hvilket er meget almindeligt for certifikater brugt sammen med Apache.

Kommunikations opsætning

For at kommunikere med WAYF’s servere er der nogle få ting der skal konfigureres i SimpleSAMLphp. Først skal config.php i /var/simplesamlphp/config tilpasses (se template), hvor de interessante variabler er følgende:

• auth.adminpassword: Denne kode skal bruges til at logge ind på selve SimpleSAMLphp’s administrations sider, hvor f.eks. metadata information findes. Man vil ikke kunne finde nogle ‘hemmelige’ informationer, så det behøver ikke være verdens længste kode.
• secretsalt: Bruges til at skabe sikre hash værdier.
• technicalcontact_email: Denne e-mail bliver brugt til at sende fejl-rappoter, hvis en bruger skulle løbe ind i problemer.
• timezone: Den sættes til vores timezone 'Europe/Copenhagen'. Vi skal sætte denne da PHP nogle gang ikke kan finde den rigtige timezone.
• language.default: sættes til dansk (da).

Næste skridt er at redigere authsources.php, som også ligger i var/simplesamlphp/config (se template). Følgende indstillinger ændres under ’default-sp’ array’et:

• entityID: sættes til jeres domænenavn f.eks. https://www.aakb.dk.
• idp: Der er 3 forskellige idp der skal bruges til forskellige situationer
  • Test: https://testbridge.wayf.dk.
  • QA: https://betawayf.wayf.dk.
  • Production: https://wayf.wayf.dk
• certificate: Filnavnet på dit SSL certifikat, som ligger il /var/simplesamlphp/cert.
• privatekey: Filnavnet på nøglen til dit certifikat.
• description: Beskrivelse af din installation f.eks. “Aarhus Kommunes Biblioteker WAYF login service”.
• name: Navnet på dit tilhørssted f.eks. “Aarhus Kommunes Biblioteker”.
• OrganizationName: Dit organisationsnavn, altså den afdeling der varetager løsningen f.eks. ITK Aarhus Kommune.
• OrganizationsURL: http adressen på din Ting hjemmside f.eks. https://www.aakb.dk.
• url: Link til information omkring jeres nemlog-in løsning. Dette kunne være en statisk side i selve CMS’et. Dette link vil dog kunne blive vist, hvis det opstår en fejl i login processen og brugeren ender på simpleSAMLphp siderne.

De sidste informationer skal være udfyldt med både en dansk og engelsk udgave af informationerne, som et array.

‘name’ => array(
  ‘en’ => ‘text’,
  ‘da’ => ‘tekst’,
);

Få file ‘saml20-idp-remote.php’ fra WAYF og placér den i mappen /var/simplesamlphp/metadata/. Filen indeholder metadata informationer omkring WAYF’s forskellige services.

Kopiering af meta-data til WAYF server

Login til WAYF administrations server (https://janus.wayf.dk) gøres ved hjælp af mail tokens, hvilket betyder at du udfylder din egen e-mail adresse og derefter modtager du en mail med et login link.

Hvis I ikke har en konto i forvejen, vil den blive oprettet automatisk. For at få adgang til jeres Service Provider (SP) data skal man dog have en person fra WAYF til at forbinde sin konto (e-mail) med jeres information på deres server. Første gang man skal logge på, skal man oprette en SP. Man skal  bruge det entityID, som man har angivet i authsources.php f.eks. https://www.aakb.dk. Dernæst skal man importere metadata fra SimpleSAMLphp installationen over på WAYF serveren.

Du kan indlæse dine metadata på janus ved at angive følgende URL på “Importer metadata” siden: https://<domæne>/simplesaml/module.php/saml/sp/metadata.php/default-sp. Metadata skal indlæses på janus hver gang man laver ændringer i konfigurationen f.eks. når man får nyt SSL certifikat mm.

PHP session handling

Både Drupal og SimpleSAMLphp benytter PHP’s session handler til at styre brugerautentifikation, hvilket giver en konflikt. Der findes to løsninger til denne problemstilling, nemlig at benytte en SQLite database eller Memcache til at håndtere SimpleSAMLphp’s sessions. Memcache er et opensource cache system som benyttes i forbindelse med mange Ding installationer for at forbedre performance. Vi starter med at kigge på Memcahce og derefter på database løsningen.

Memcache

Der findes to forskellige implementeringer, nemlig memcache og memcached. Den første er en ældre implementering til PHP. SimpleSAMLphp er implementeret med den ældre udgave af memcache. Så benytter man memcached skal man indføre følgende ændringer:

Link til fil på server, da det er nemmer at download en diff.

diff --git a/lib/SimpleSAML/Memcache.php b/lib/SimpleSAML/Memcache.php
index e83835e..c41c7c8 100644
--- a/lib/SimpleSAML/Memcache.php
+++ b/lib/SimpleSAML/Memcache.php
@@ -132,7 +132,8 @@ class SimpleSAML_Memcache {

            /* Store this object to all groups of memcache servers. */
                                           foreach(self::getMemcacheServers() as $server) {
-                                                               $server->set($key, $savedInfoSerialized, 0, $expire);
+                                                              $server->set($key, $savedInfoSerialized, 0);
                                          }
                }
@@ -237,7 +238,8 @@ class SimpleSAML_Memcache {
                                          }

                                           /* Add this server to the Memcache object. */
-                                          $memcache->addServer($hostname, $port, TRUE, $weight, $timeout);
+                                         $memcache->addServer($hostname, $port, TRUE);
                     }
@@ -250,7 +252,7 @@ class SimpleSAML_Memcache {
         */
        private static function loadMemcacheServerGroup(array $group) {
                                           /* Create the Memcache object. */
-                                          $memcache = new Memcache();
+                                         $memcache = new Memcached();
                                           if($memcache == NULL) {
                                                               throw new Exception('Unable to create an instance of a Memcache object.' .
                                                                     ' Is the memcache extension installed?');

Næste skridt er at rediger config.php i /var/simplesamlphp/config for at sætte Memcache op til håndtering af sessions.

• store.type:  sættes til memcache.
• memcache_store.servers: sæt hostname til hvor memcache serveren findes. I de fleste tilfælde vil det være localhost.

Database (SQLite)

SimpleSAMLphp bruger SQLite til at håndter sessions, hvis man vælger ikke at benytte memcache. SQLite er en “simpel” database løsning, der ikke kræver en extra installationer for at køre. Databasen bestående af en enklet file på serveren placeret et sted, hvor PHP har lov til at skrive til filen. Du skal lave følgende ændringer i /var/simplesamlphp/config/config.php.

• store.type:  sættes til sql.
• store.sql.dsn: f.eks. 'sqlite:/tmp/session_database.sq3'.
• store.sql.username: angive et brugernavn f.eks. ding_wayf.
• store.sql.password: angive en automatisk generate adgangskode, du har ikke bruge for at kan huske denne kode.

2. Drupal (Ding)

Der er flere måder, hvor på man kan få ding WAYF koden installeret til en Ting hjemmeside. Den nemmeste er at tilføje det til build-profilen, men man kan også hente koden fra http://github.com/dingproject/ding_wayf.

Modulet installeres på sitet, som alle andre moduler via /admin/build/modules. Efter aktivering af modulet skal man tilgå siden /admin/settings/ding/wayf. De fleste vil kunne benytte default settings, så de kan bare trykke “Gem instillinger”.

Før du kan logge ind med WAYF skal du tilføje en afgangskode til bibliotekssystemet i “settings.php”. Grunden til dette er at WAYF returnerer et CPR nummer og ikke nogen kode for brugeren. Så derfor skal man bruge en special kode eller hash til alle brugere, der logger ind via WAYF. Hvis man benytter DDElibra, som bibliotekssystem, skal man finde trim værdien ”SScr alma-secret-pincode” og indsætte denne værdi. Du skal tilføje denne linje $conf[‘ding_wayf_passwd’] = ‘<kode/hash>’; til settings.php.

Modulet laver en block, men et link til WAYF login. Du kan selv bestemme, hvor dette link skal placeres på dit site ved at gå til "/admin/build/block" og f.eks. indsætte den i regionen "account"

3. Ordliste

• SSL: Secure Sockets Layer (https)
• idp: Identity Provider (WAYF)
• sp: Service Provider (Ding)
• qa: Quality assurance
• WAYF: Where Are You From
• SAML: Security Assertion Markup Language
• SQLite: SQLite er et software bibliotek, som implementere en SQL database engine.

4. Referencer

Links til software der bliver brugt til denne løsning.

• http://wayf.dk/.
• http://simplesamlphp.org/.
• http://github.com/aakb/ding_wayf (http://github.com/dingproject/ding_wayf).