SIP2 over https
SIP2-automaten in OCLC Wise kunnen gebruik maken van communicatie over HTTPS. Voordeel van https is dat er geen configuratie nodig is in de routeringen en in vestigingen als scholen of kleine bibliotheken. Daarnaast is het ook niet afluisterbaar omdat de communicatie versleuteld wordt. SIP2 over https werkt gewoon out of the box zonder aanpassing aan het lokale netwerk.
Het wachtwoord moet minimaal 16 posities lang zijn en een zeer sterk wachtwoord zijn (zo random mogelijk, enkel speciale tekens als @#$%^&+=- zijn mogelijk). Er zit geen filtering op IP-nummer voor de SIP2 https requests wat betekent dat vanaf het gehele internet SIP2-requests kunnen worden uitgevoerd. Om deze reden is het belangrijk dat zorgvuldig wordt omgegaan met inloggegevens, inclusief de url waarmee wordt verbonden.
Het wachtwoord moet worden ingesteld via de Manager > Wise > Poort- en profielbeheer > Poorten > Sip Automaten.
Bij het aanmaken van een SIP automaat wordt een actor gemaakt. Die is terug te vinden in de Systeemwise > Toegangscodes en bevoegdheden > Bevoegdheden.
- Door te zoeken op ‘naam (met rol)’ is de 'Wise gebruiker' van de SIP2 poort te vinden (zet ‘Automaat-‘ of ‘actor-‘ als prefix voor de toegangscode van de poort, bijv. actor-PAY1234).
- De juiste poort gevonden? Klik aan, dan is in het deel erboven het wachtwoord in te stellen bij ‘Inlogcode Manager + https-client’.
- De url waarmee gecommuniceerd moet worden: https://[WISE-URL]/sip2https/services.
Open de url in een browser om te testen of de juiste url in gebruik is. Als de melding {"error":"Method not allowed"} verschijnt, is de juiste url in gebruik.
JSON request en response
De SIP2https-tool biedt een manier om clear-text SIP2-commando's en -antwoorden te tunnelen via beveiligde HTTPS. Elk SIP2-commando wordt verpakt in een JSON-object en vergezeld van een token. Dit token dient om de authenticiteit van het verzoek te identificeren.
Hieronder staat een voorbeeld van een request- en response. Let op: het token zal aanvankelijk leeg zal zijn (verzonden door de client samen met een 93-request). De server zal na een succesvolle login een token verstrekken. Vanaf dat moment moet de client bij elk volgend verzoek het laatst ontvangen token meesturen.
JSON Request voorbeeld:
{
"sip2request":"6300020071001AO|AA21234002896242|ACxyzzy|AD1234|AY3AZEF37",
"token":"rqYtfjBBMOqK+fK7yW0Z1TSyCJ8"
}
JSON Response voorbeeld:
{
"sip2response":"64Y83838383838AOWisecity|AA21234002896242|AE|BLN|CQY|BHEur|BV0.00|FB0.00|FC0.00|AY3AZBFDE"
"token":"rqYtfjBBMOqK+fK7yW0Z1TSyCJ8"
}
Aantekeningen voor bij (client side) implementatie
De SIP2https-service heeft een basis-URL in het volgende formaat:
https://<hostname>/sip2https/services en accepteert alleen POST-requests.
- Ge-POST-e gegevens moeten de Content-Type
application/jsonhebben. De codering is UTF-8. - Om veiligheidsredenen vereist de SIP-service een wachtwoord (CO-subveld van commando 93) met een minimale lengte van 16 tekens. Dit wachtwoord mag niet hetzelfde zijn als de gebruikersnaam (CN-subveld).
- De eerste dialoog moet altijd een 93 dialoog zijn om in te loggen (en een token te verkrijgen). Dit is de enige dialoog die geaccepteerd wordt zonder token.
- Volgens REST-stijl maakt de service gebruik van HTTP-statuscodes en foutmeldingen voor foutafhandeling:
- Status 200 geeft een geslaagd commando aan.
- Statuscodes in de 4XX-reeks worden gebruikt voor verschillende foutmeldingen.
- Wanneer een 409 statuscode retour komt, is het token niet (meer) geldig en moet er opnieuw ingelogd worden met een 93 dialoog alvorens de bedoelde dialoog alsnog uit te voeren, nu met het nieuw verkregen token.
- Omdat het token gekoppeld wordt aan de inlog en het IP is het niet mogelijk om inlogs te gebruiken op meer dan 1 client. Wanneer 2 automaten een inlog delen krijgen ze beide een verschillend token, en zal er steeds een nieuw token uitgedeeld worden (effectief een "klapperende" verbinding.
- Om dezelfde reden moet het IP adres "stabiel" zijn. Het is niet mogelijk de requests round-robin over 2 internet verbindingen te routeren, omdat dan het token steeds ongeldig zal zijn. Een van de verbindingen zal primair moeten zijn, en de andere kan als fallback dienen. Als de primaire verbinding down gaat zal via een 409 melding een nieuw token worden geforceerd over de backup verbinding.
Authenticatiefouten en IP-blokkering
Bij een authenticatiefout verhoogt de service een counter voor failures per (client) IP-adres.
- Wanneer deze counter een vooraf gedefinieerde limiet bereikt (meestal 10 pogingen), wordt het IP-adres geblokkeerd voor een bepaalde periode (meestal 1 uur) om misbruik te voorkomen.
- Een succesvolle login reset de counter.
Token-verloop en herauthenticatie
Het token dat wordt verstrekt na een succesvolle login verloopt na een bepaalde inactieve periode (meestal 2 uur).
- Als de client een verlopen token gebruikt, zal de server reageren met 409 Session expired of bij token clashes 401 Unauthorized
- Een serverreset kan ook leiden tot het verlopen van een token.
- Implementors moeten in dergelijke gevallen automatisch opnieuw inloggen (93-commando).
Configuratie
Het wordt aangeraden om sterke wachtwoorden aan de SIP2-clients toe te wijzen. De minimale lengte is 16 tekens. Het wordt aanbevolen om een random string generator te gebruiken om deze wachtwoorden te genereren.
Bijlage:
Voorbeeld dialogen:
|
CMD |
Betekenis |
Dialoog |
|---|---|---|
|
93 |
login |
93<0><0>|CN<inlog>|CO<ww>|AY0 |
|
99 |
Sc status |
99<0><080><2.00>|AY1 |
|
23 |
Patron status request |
23<001><transactiedatum>|AO<>|AA<lenernr>|AY1 |
|
63 |
Patron information |
63<001><transactiedatum><YYYYYYYYYY>|AO<>|AA<klantnr>|BP<000>|BQ<999>|AY1 |
|
09 |
checkin |
09<N><uitleendatum><inleverdatum>|AP<>|AO<>|AB<exemnr>|AY1 |
|
11 |
checkout |
11<Y><N><uitleendatum:18><inleverdatum:18>|AA<klantnr>|AB<exemnr>|BO<N>|BI<N>}AY1 |
|
29 |
Renew |
29<N><N><transactiedatum><inleverdatum>|AA<klantnr>|AB<exemnr>|BO<Y>|AY2 |
|
17 |
Item information |
17<YYYYMMDDzzzzHHMMSS>|AB<exemnr>|AY1 |
|
35 |
End patron session |
35<transactiedatum>|AA<klantnr>|AY1 |