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. 

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",

           }

        }

    }