User Authentication web service
Overview
The User Authentication web service is used internally in the Relais Portal to authenticate patrons (as well as staff and libraries). The web service can also be used by any Relais library, for example to pass into Relais patron credentials such as a barcode and surname.
- This web service can be used to authenticate patrons
- against patron records or skeletal patron records in Relais
- if NCIP is enabled, against your local library system using the Lookup User message
- There are multiple options as to what patron credentials, e.g., patron id and password, can be included in the web service.
- In many cases the values provided in the web service have already been authenticated against a local service such as LDAP (this is done outside of Relais)
- Once a patron is authenticated using this web service a unique ‘aid’ (authorization id) is assigned. The ‘aid’ is valid only until the patron logs out or is idle for the configured period of time.
- While authentication may be handled outside of Relais and an NCIP Lookup User may be done, a skeletal patron record also exists in Relais. If when calling the User Authentication web service, a patron record does not already exist, one is created on the fly using the patron information provided.
- Patron credential may be encrypted - please contact Relais support re encryption options.
- The User Authentication response returns
- The ‘aid’ – the authorization id.
- The patron's library symbol
- The patron's name and surname
- The authorization id (aid) can be used in other Relais web services such as Find Item and Request Item. When the aid is used no additional patron information need be included in these web services.
Authentication service URL
Use the following url. Check with your local Relais Administrator or Relais Support for the correct value for your hostname.
http://HOSTNAME/portal-service/user/authentication/patron
HTTP Protocol Headers
HTTP Method: POST
HTTP Header Content-Type: application/json
HTTP Header User-Agent: “Any value”
Request body
{
"AuthenticationInformation": {
"LibrarySymbol": "librarySymbol",
"PatronId": "patronId",
"PrefLang": "prefLang",
"Surname": "patronSurname",
"RecordKey": "recordKey",
"UserLogin": "userLogin",
"UserPassword": "userPassword"
},
"AddressInformation": {
"Address1": "address1",
"Address2": "address2",
"City": "city",
"Province": "province",
"Country": "country",
"PostCode": "postCode"
},
"Base64PI":"base64PI",
"Base64id":"base64id",
"Base64RK":"base64RK",
"Base64PS":"base64PS",
"Base64surname":"base64surname",
"Base64UL":"base64UL",
"Base64UP":"base64UP"
}
Note: The request body must include the Library Symbol and one combination of patron credentials. Examples of combinations of patron credentials are provided below.
Option 1. PatronId only (plain-text)
For example:
{
"AuthenticationInformation": {
"LibrarySymbol": "OORII",
"PatronId": "3159154101"
}
}
If you are using NCIP, the PatronId is used as the Barcode when the NCIP Lookup User message is sent.
If you are NOT using NCIP, what happens?
Option 2. PatronId only (encrypted)
For example:
{
"AuthenticationInformation": {
"LibrarySymbol": "OORII",
"PatronId": " oVtjzoh2D5A2r0OAkvxEbA"
},
"Base64PI":"1"
}
If you are using NCIP, the decrypted PatronId is used as the Barcode when the NCIP Lookup User message is sent.
If you are NOT using NCIP, what happens?
Option 3. User Login and User Password (plain text)
For example:
{
"AuthenticationInformation": {
"LibrarySymbol": "OORII",
"UserLogin": "333211",
"UserPassword": "password"
}
}
If you are using NCIP, the userLogin and userPassword are used as Barcode and PIN, respectively, when the Lookup User message is sent.
If you are not using NCIP, the userLogin and userPassword are used to look up the patron record in the Relais database.
Option 4. User Login and User Password (encrypted)
For example:
{
"AuthenticationInformation": {
"LibrarySymbol": "OORII",
"UserLogin": "????",
"UserPassword": "????"
}
}
If you are using NCIP, the decrypted userLogin and userPassword are used as Barcode and PIN, respectively, when the Lookup User message is sent.
If you are not using NCIP, the decrypted userLogin and userPassword are used to look up the patron record in the Relais database.
Request response
{
"Authentication": {
"AuthnUserInfo": {
"AId": "authorization id",
"LibrarySymbol": "librarySymbol",
"FirstName":"firstName",
"LastName": "lastName",
}
}
}
For example
{
"Authentication": {
"AuthnUserInfo": {
"AId": "12knsfd987234ldfd2",
"LibrarySymbol": "OORIIl",
"FirstName":"Clare",
"LastName": "MacKeigan",
}
}
}