Bibliotekutvikling Kunnskapsorganisering
ForumLogg inn

Dokumentasjon til den tekniske løsningen

Sist oppdatert: 04.04.2024

Beskrivelse og formål av nasjonalt lånerregister og Bibliotekkortet

Biblioteksystemer sin dokumentasjon til løsningene nasjonalt lånerregister og Bibliotekkortet.

SOAP-WSDL

https://fl.lanekortet.no/api/rest/wsdlv2

REST-dokumentasjon

https://fl.lanekortet.no/apidoc/index.php

Kryptering/Autentisering av leverandør for SOAP/REST

  • Alle tjenester krever HTTPS.
  • SOAP-tjenestene er beskyttet vha Basic Authentication.
    • Brukernavn er –.  Ex: “bibsyst-5070901”.  Leverandørkoden er hentet fra katalogsystemet i Base Bibliotek (små bokstaver).  Følgende er registrert per 2024 i bruk i NL:
      • aleph
      • bibsyst
      • axiell
      • bibsys
      • oslokommune
      • libriotech
      • systematic
      • bibits
      • reindex
      • bibservice
    • Passordet er bibliotekets autentiseringkode fra Base Bibliotek (NB) + “-” + en leverandørkode utlevert av Bibliotek-Systemer As.  Ex: fA4g-f89kXZ.  Dette passordet hashes med SHA-256. 
    • Brukernavnet og passordet Base64-enkodes så i henhold til Basic Authentication standarden.
    • Oversikten over brukernavn og passord oppdateres hver dag ca. 05:30 basert på eksport fra Base Bibliotek.

SOAP-kall

Dette er informasjon som ligger i WSDL-skjemaet og det er den som er den autorative kilden for SOAP-kallene.  Ved tvil, sjekk WSDL-skjema.

nyPost()

Denne har også et alias nyLaaner() som gjør det samme.  Det anbefales at man bruker nyPost().

Funksjonen legger inn ny låner.  Følgende elementer må opptre og være ikke-tomme: lnr, navn, fnr_hash.  Lånernummer (fra forhåndstildelt sekvens) må være satt fra klienten.  Disse blir IGNORERT, og hentet fra FFREG: p_adresse1 eller p_postnr eller p_sted, fdato.  Feltet kjonn blir ignorert for alle andre verdier enn ‘X’. Defaultverdi for p_land er no.  Defaultverdi for hjemmebibliotek er biblioteket som utfører funksjonskallet. Server sjekker at lånernummer og fnr_hash ikke forekommer fra før. Det opprettes implisitt en tilknytning mellom låner og biblioteket som utfører funksjonskallet.

endre()

Denne har også et alias endreLaaner() som gjør det samme.  Det anbefales at man bruker endre().

Funksjonen oppdaterer posten i databasen med lnr lik parameteren lnr.  Parameteren post inneholder de elementer som skal endres.  Disse blir IGNORERT, og hentet fra FFREG: p_adresse1 eller p_postnr eller p_sted, fdato.  Feltet kjonn blir ignorert for alle andre verdier enn ‘X’. Utelatte elementer beholder sin gamle verdi.  Verdien for sist_endret kan ikke endres, men må stemme overens med gammel verdi.  Elementer som opptrer uten innhold gir sletting av tilsvarende felt.  Nye verdier for sist_endret og sist_endret_av blir satt av server.  Ved endring av lnr blir gammelt_lnr satt av server. Det opprettes en tilknytning mellom låner og biblioteket som utfører funksjonskallet, hvis tilknytningen ikke finnes fra før.

hent()

COMPAT: Denne vil gi en feilmelding hvis låner ikke er tilknyttet biblioteket, forventet aktivering i løpet av 2024.

Funksjonen henter poster med gitt lånernummer (max 1) eller fnr_hash (max 2).  Lengden av parameteren (identifikator) bestemmer hvilket felt det søkes i.  KUN lånere som er tilknyttet biblioteket vil bli returnert.

soek()

COMPAT/DEPRECATED: Denne er forventet å bli fjernet i løpet av 2024.

soekEndret()

Funksjonen returnerer alle poster opprettet eller endret på eller senere enn «tidspunkt» og som er knyttet til biblioteket som utfører funksjonskallet.  start_indeks regnes fra 1. max_antall=0 tolkes som ubegrenset.

endre()

Funksjonen oppdaterer posten i databasen med lnr lik parameteren lnr.  Parameteren post inneholder de elementer som skal endres. Utelatte elementer beholder sin gamle verdi.  Verdien for sist_endret kan ikke endres, men må stemme overens med gammel verdi.  Elementer som opptrer uten innhold gir sletting av tilsvarende felt. Nye verdier for sist_endret og sist_endret_av blir satt av server.  Ved endring av lnr blir gammelt_lnr satt av server.  Det opprettes en tilknytning mellom låner og biblioteket som utfører funksjonskallet, hvis tilknytningen ikke finnes fra før.

slett()

Funksjonen sletter alle felt unntatt lnr, opprettet, opprettet_av, sist_endret og sist_endret_av. Biblioteket som utfører funksjonskallet må være tilknyttet brukeren.

nyttBibliotek()

Oppretter tilknytning mellom låner med gitt lnr og biblioteket som utfører funksjonskallet. Funksjonen brukes for å melde til lånerregisteret at biblioteket har etablert låneren lokalt.

fjernBibliotek()

Fjerner tilknytning mellom låner med gitt lnr og biblioteket som utfører funksjonskallet.

gyldigLnr()

Sjekker om lnr er ledig og reservert av biblioteket som utfører funksjonskallet.

hentKnytnger()

Funksjonen henter biblioteknumre som lånernummer er knyttet til. Returnerer ei liste med biblioteknummer og en verdi som forteller om biblioteket er hjemmebiblioteket(h) eller bare tilknyttet(t).

hentMinimert()

Funksjonen henter poster med gitt lånernummer (max 1) eller fnr_hash (max 2). Lengden av parameteren (identifikator) bestemmer hvilket felt det søkes i. Gir ut kun minimum med lånerdata.

soekMinimert()

Funksjonen har 3 argumenter, «navn», «fdato» og «fnr_hash». Minst ett av feltene må være utfylt. Navn kan søkes med maskeringstegn ‘%’. Gir ut kun minimum med lånerdata.

opprettBibKnytninger()

Oppretter tilknytning mellom låner med gitt lnr og ett eller flere biblioteksnummer er angitt i parameteret bibnr. Funksjonen brukes for å melde til lånerregisteret at biblioteket har etablert låneren lokalt. Mulige verdier for code: CONNECT_OK, CONNECT_FAIL_SYSTEM_MISMATCH, CONNECT_FAIL_ALREADY_CONNECTED, CONNECT_FAIL_INVALID_PATRON_ID, CONNECT_FAIL_PATRON_ID_NOT_FOUND, CONNECT_FAIL_LIBNO_NOT_FOUND, CONNECT_FAIL_GENERAL_ERROR.

fjernBibKnytninger()

Fjerner tilknytning mellom låner med gitt lnr og ett eller flere biblioteksnummer er angitt i parameteret bibnr. Mulige verdier for code: REMOVE_OK, REMOVE_FAIL_INVALID_PATRON_ID, REMOVE_FAIL_PATRON_ID_NOT_FOUND, REMOVE_FAIL_LIBNO_NOT_FOUND, REMOVE_FAIL_NOT_CONNECTED, REMOVE_FAIL_SYSTEM_MISMATCH, REMOVE_FAIL_GENERAL_ERROR 

Kryptering av persondata

Feltet “passord” krypteres med SHA-512/PBKDF2 med 100000 iterasjoner.  Feltet lagres i formatet: SHA-512/PBKDF2/100000#<HASH>#

Ex:  SHA-512/PBKDF2/100000#S6ncFUCHhvyY2FJ6#BBB1F657482B983FEDDDECF28796DED50D3D5B2C81C630B4D41FF82B559E899AE3A986C8291C66810F8D63458719CAA2DCAA32C7007F91E077A0E328DA161752#

Feltet “pin” krypteres med AES-128-ECB med en utvekslet krypteringsnøkkel.  “pin” paddes opp til 16 tegn før kryptering.  Den krypterte strengen lagres i hexadecimalt format (små bokstaver).

Ex (PHP):

$inputPIN=’2023′;

$pinKey     = «XXXXXXXXXXXXXXXXX»;

$algo       = ‘AES-128-ECB’;

$padByteVal = (16 – strlen($inputPIN));

if ($padByteVal > 0) {

  $inputPIN = iPadToLength($inputPIN, 16, $padByteVal);

}

$enc_INPUT_PIN_BIN = openssl_encrypt($inputPIN, $algo, $pinKey, (OPENSSL_RAW_DATA|OPENSSL_ZERO_PADDING));

$enc_INPUT_PIN_HEX = bin2hex($enc_INPUT_PIN_BIN);

$enc_INPUT_PIN_HEX inneholder den krypterte pinkoden (i hex) og kan utveksles med NL.  pinKey er krypteringsnøkkelen som hver systemleverandør har fått tilgang til.

Feltet “fnrhash” utveksles i klartekst, men krypteres i NL og det anbefales sterkt at man gjør tilsvarende i det lokale systemet. 

FLYT – Autentisering av låner – OpenID Connect

  1. Låner klikker på “Logg inn med Bibliotekkortet” (eller tilsvarende tekst) i lokalt biblioteksystem.
  2. Låner blir videresendt til OIDC-side hos Bibliotekkortet (NL).
  3. Låner velger autentiseringsmetoden (pin, passord, Feide, ID-Porten, m.fl.).
    1. Låner klikker avbryt under autentiseringen og blir sendt tilbake til “cancel-URL”.
    2. Låner fullfører autentiseringen og går videre til #4.
  4. Låner blir videresendt tilbake til lokalt biblioteksystem med authcode i URL.
  5. Lokalt biblioteksystem bruker authcode i et backchannel REST-kall for å hente ID token og access token.
    1. ID token inneholder “pid” som vil være fødselsnummeret til låneren.
    2. ID token inneholder feltet “isnl” som sier om låneren har nasjonalt lånekort (true) eller ikke (false).
  6. Lokalt biblioteksystem kan bruke access token for å hente ut persondata om låneren.
  7. Lokalt biblioteksystem autoriserer låneren.

FLYT – Opprett knytning

Ved søk på navn

  1. Biblioteket søker etter en låner vha soekMinimert().
  2. Biblioteket matcher låneren med trefflisten fra soekMinimert().
  3. Biblioteket knytter låneren til seg vha nyttBibliotek() eller opprettBibKnytninger().
  4. Biblioteket laster ned persondata for låneren vha hent().

Ved oppslag på lånerkortnummer eller fødselsnummer

  1. Biblioteket henter persondata vha hentMinimert().
  2. Biblioteket sjekker at persondata matcher låneren.
  3. Biblioteket knytter låneren til seg vha nyttBibliotek() eller opprettBibKnytninger().
  4. Biblioteket laster ned persondata for låneren vha hent().

nyttBibliotek() knytter låneren til biblioteknummeret som ligger i Basic Authentication autentiseringen.  Det er ikke mulig å knytte til andre biblioteknumre eller til flere.

opprettBibKnytninger() kan brukes for å knytte låneren til flere biblioteknumre i samme operasjon og er ikke begrenset til autentisert biblioteknummer.

FLYT – Ny låner

  1. Biblioteket søker eller slår opp låner og får ikke noen treff.
  2. Biblioteket sjekker om lånekortet (N-nummeret) tilhører biblioteket vha REST-servicen /nummersjekk.  Hvis biblioteknummeret ikke eier Bibliotekkortet må systemet gjøre en ekstra sjekk på at biblioteket har rett til å ta det i bruk.  Dette skjer vanligvis når låneren opprettes som lokal låner i lokalt biblioteksystem.  Det må gjøres før #3.
  3. Biblioteket laster opp ny låner vha nyPost().

FLYT – Oppdatering av persondata

  1. Biblioteket oppdaterer persondata på en nasjonal låner.  Persondata i dette tilfellet betyr data som skal synkroniseres med NL, så som e-postadresse, mobilnummer, pinkode og passord, m.fl.  Hvis låneren oppdateres på noen som helst måte som ikke inkluderer endring i NL data (lån, innlogging i biblioteksystemet, digitale tjenester, osv.) skal biblioteket i stedet kalle REST-servicen /sistaktiv for å registrere at låneren er aktiv slik at låneren ikke blir slettet fra NL etter 2 år uten aktivitet.  Det anbefales at man samler disse opp og oppdaterer dem nattlig eller ukentlig for å unngå unødvendig ressursbruk/treghet (i lokalt system) mens systemet brukes.
  2. Biblioteket oppdaterer persondata umiddelbart i NL vha endre().
  3. NL sender ut NCIP-kallet UserUpdated til alle biblioteknumrene låneren er tilknyttet.
  4. Bibliotekene som mottar NCIP-kallet
    1. oppdaterer låneren i sine lokale systemer.
    2. gjør kall mot NL jevnlig (hvert 5-15 minutt) og ber om endrede lånere som så oppdateres i deres lokale systemer.

Opprinnelig prosjektbeskrivelse (2005)

https://lanekortet.no/prosjektbeskrivelse.pdf