NELLI-Tunnis Käyttäjän tunnistus NELLI-tiedonhakuportaalissa yleisissä kirjastoissa Versio 1.0 16.5.2006 Ere Maijala Kansalliskirjasto
Sisällysluettelo Johdanto...3 Tekniikka...3 Esimerkit...4 XML-Skeema...5 NELLI-Tunnis 2
Johdanto NELLI-portaali tarjoaa vapaiden aineistojen lisäksi pääsyn kirjastojen lisensioimiin aineistoihin. Käyttäjä pitää pystyä tunnistamaan kirjaston asiakkaaksi ennen kuin lisensioitujen aineistojen käyttö sallitaan. Tunnistautuneelle käyttäjälle voidaan myös tarjota ns. personoidut palvelut (uutuusvahdit, kirjahylly yms.). Yleisten kirjastojen NELLI-portaalit eroavat yliopistojen ja ammattikorkeakoulujen portaaleista sikäli, että niillä on käyttäjiä useista kirjastoista, eikä yhdellä portaalilla ole yhtä omaa kotiorganisaatiota. Tämä asettaa autentikoinnillekin uusia vaatimuksia. Yhden portaalin käyttäjien autentikointiin pitää voida käyttää kaikkien siihen kuuluvien kirjastojen asiakasrekistereitä. Tähän tarkoitukseen on suunniteltu NELLI-Tunnis -palvelu. Sitä käyttämällä käyttäjä voi valita kirjaston, jonka asiakasrekisteriin haluaa kirjautua, ja ko. kirjaston järjestelmä vahvistaa käyttäjän kirjautumisen ja palauttaa tarpeelliset tiedot. Tekniikka NELLI-Tunnis on suunniteltu mahdollisimman kevyeksi ja helpoksi toteuttaa. Tavoitteena on riittävä turvallisuus ilman liiallista mutkikkuutta järjestelmien tai käyttäjän kannalta. Käytännössä autentikointi tapahtuu näin: 1. Käyttäjä valitsee NELLI-portaalissa sisäänkirjautumisen 2. NELLI-Tunnis palauttaa asiakkaan täytettäväksi lomakkeen, jossa on seuraavat tiedot: a. Kirjaston valinta NELLI-Tunnis listaa tähän ko. portaalin jäsenkirjastot, joita autentikoinnissa voidaan käyttää b. Viivakoodi c. PIN-koodi (salasana) 3. Asiakas valitsee kirjaston ja syöttää viivakoodin ja salasanan 4. NELLI-Tunnis lähettää valitun kirjaston palvelimelle autentikointipyynnön suojatulla HTTPS-yhteydellä POST-metodia käyttäen 5. Palvelin palauttaa vastauksen XML-muodossa Palvelun käyttö edellyttää suojattua HTTPS-yhteyttä, jolla huolehditaan siitä, etteivät käyttäjän tiedot liiku salaamattomina Internetissä. Kustannusten minimoimiseksi palvelu ei edellytä yleisesti luotetun tahon allekirjoittamaa SSL-sertifikaattia, vaan myös ns. itse allekirjoitettu (selfsigned) sertifikaatti kelpaa. Suositeltava merkistö kaikessa liikenteessä on UTF-8, mutta tarvittaessa voidaan käyttää myös ISO-8859-1:tä tai ISO-8859-15:tä. Autentikointipyynnössä lähetetään seuraavat parametrit normaalilla application/x-www-formurlencoded enkoodauksella: id (käyttäjän syöttämä id, käytännössä siis viivakoodi) verification (PIN-koodi tai salasana) service (palvelun tunniste, esim. nelli) NELLI-Tunnis 3
mahdolliset järjestelmäkohtaiset lisäkentät (esim. formid=xyz) Vastauksena saadaan XML-tietue, jossa on seuraavat elementit auth-juurielementin (jossa pakollinen version= 1.0 attribuutti) alla: status (autentikointipyynnön status) id (käyttäjän id, käytännössä siis viivakoodi. HUOM! Tulee säilyä yksilöivänä vähintään vuoden) name (käyttäjän nimi) email (käyttäjän sähköpostiosoite) language (käyttäjän käyttökieli, ISO 639-2:n mukainen kolmekirjaiminen kielikoodi) Esimerkit Lähetettävä POST-pyyntö: id=698a0000001&verification=1324&service=nelli XML-vastaus: <status>success</status> <id>123a0000001</id> <name>testaaja, Taavi</name> <email>taavi.testaaja@helsinki.fi</email> <language>fin</language> Jos autentikointi epäonnistuu (id tai verification pielessä, tai niillä ei pääse service-attribuutin määrittelemään palveluun), palautetaan virhe: <status>failure</status> Jos autentikointipalvelu ei ole juuri nyt käytettävissä: <status>unprocessed</status> NELLI-Tunnis 4
XML-Skeema Simppeli XML-skeema kirjaston palvelimen palauttamasta vastauksesta. Skeema ei ole mitenkään täydellinen, mutta onpahan ainakin suuntaa-antava. <?xml version="1.0"?> <xsd:schema targetnamespace="http://www.nelliportaali.fi/nelli-tunnis" xmlns="http://www.nelliportaali.fi/nelli-tunnis" xmlns:xsd="http://www.w3.org/2001/xmlschema" elementformdefault="qualified" attributeformdefault="unqualified" version="1.0"> <xsd:element name="auth"> <xsd:complextype> <xsd:sequence> <xsd:element name="status" type="statustype" minoccurs="1" maxoccurs="1" /> <xsd:element name="id" type="xsd:string" minoccurs="0" maxoccurs="1" /> <xsd:element name="name" type="xsd:string" minoccurs="0" maxoccurs="1" /> <xsd:element name="email" type="xsd:string" minoccurs="0" maxoccurs="1" /> <xsd:element name="language" type="xsd:string" minoccurs="0" maxoccurs="1" /> </xsd:sequence> <xsd:attribute name="version" type="xsd:string" /> </xsd:complextype> </xsd:element> <xsd:simpletype name="statustype"> <xsd:restriction base="xsd:nmtoken"> <xsd:enumeration value="success"/> <xsd:enumeration value="failure"/> <xsd:enumeration value="unprocessed"/> </xsd:restriction> </xsd:simpletype> </xsd:schema> NELLI-Tunnis 5