Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Info
titleSee also:

In English: Finna Authentication API (In English)


Table of Contents

Historia

20.3.2017 Ensimmäinen versio

Yleistä

Finnassa on rajapinta, jolla voidaan tarkistaa, ovatko asiakkaan antamat kirjautumistiedot oikein. Rajapinta palauttaa vain tiedon onnistumisesta, ei asiakkaan tietoja.

Rajapinta toimii niin, että Finna välittää kyselyn käyttäjän oikeuksista suoraan ao. kirjastojärjestelmälle ja palauttaa tiedon kyselyn tuloksesta.   Käyttäjällä ei siis tarvitse olla omaa tiliä Finnassa, jotta kirjautuminen onnistuisi.

Mahdollisia käyttötapoja:

  • Kirjaston asiakkaiden tunnistaminen esim. tulostuspalveluissa
  • E-kirjojen tarjoajat voivat esim. tarkistaa, onko tietty asiakas oikeutettu käyttämään tarjottua e-kirjaa.

Huom! Tämä rajapinta on toiminnallisuudeltaan hyvin suppea. Finna tukee myös OpenID Connect:ia, jossa on laajemmat toiminnot ja pääsy käyttäjän tietoihin.

Käyttöehdot

Rajapinta ei ole avoimesti käytettävissä, vaan sen käytöstä ja kattavuudesta sovitaan erikseenon sovittava erikseen ottamalla yhteyttä Finnan palvelupisteeseen (finna-posti [at] helsinki.fi). Rajapinnan hyödyntäminen sallitaan vain erikseen sovituista IP-osoitteista. Rajapinnan käyttäminen edellyttää, että rajapinnan hyödyntäjä jakaa Kansalliskirjastolle sellaiset yhteystiedot, joilla käyttöön liittyviä tärkeitä viestejä saadaan nopeasti välitettyä. Rajapinnan hyödyntäjän pitää myös päivittää muuttuvia yhteystietojaan.

libraryCardLogin -rajapintakutsujen pitää lähteä liikkeelle aina käyttäjän toimesta. Kirjautumiskohde, käyttäjätunnus ja salasana voivat olla vain ja ainoastaan käyttäjän valitsemia.  

Jos vääränlaista tai palvelua haittaavaa käyttöä havaitaan, Kansalliskirjastolla on oikeus sulkea rajapinnan hyödyntäjän pääsy rajapintaan. Asiasta tiedotetaan rajapinnan hyödyntäjälle.


Merkistönä on kaikissa tapauksissa UTF-8 (composed).

Toiminnot

getLoginTargets

https://api.finna.fi/api/v1/auth/getLoginTargets?<parametrit>

...

Code Block
languagejs
{
    "targets": [
        {
            "id": "muumilaakso",
            "name": "Muumilaakson kirjasto",
        },
        {
            "id": "testi",
            "name": "Testikirjasto",
            "secondary_login_field_label": "Sukunimi"
        }
    ]
}

...


libraryCardLogin

Palauttaa tiedon kirjautumisen onnistumisesta ja mahdollisista virheistä. Parametrit tulee lähettää POST-pyynnöllä (application/x-www-form-urlencoded; charset=utf-8).

ParametriTyyppiSeliteSallitut arvot
prettyPrintLukuTulostetaanko JSON rivinvaihtojen kera0 (oletus), 1
lngMerkkijonoKieliversio
  • fi (suomi, oletus)
  • sv (ruotsi)
  • en-gb (englanti)

targetMerkkijonoKirjautumiskohde eli kirjastogetLoginTargets-pyynnön palauttamat id:t
usernameMerkkijonoKäyttäjätunnus (kirjastokortin numero) 
passwordMerkkijonoSalasana (PIN-koodi) 
secondaryMerkkijonoToinen tunnistekenttä, mikäli getLoginTargets palautti secondary_login_field_label:n 

Esimerkkikysely (tässä GET-muodossa, käytä POST-pyyntöä):

...

Code Block
languagejs
{"status":"ERROR","statusMessage":"Backend unavailable"}

Dokumentaation muutoshistoria

20.3.2017 Ensimmäinen versio