Overview

As part of integrating self service circulation terminals and FOLIO (edge-sip2), the requirement of a separate PIN field came up.

PIN authentication via SIP2 has already been implemented SIP2-61 - Getting issue details... STATUS , using the user password field. However, the user password field has been deemed unsuitable for various reasons. The idea here is to introduce and utilize a separate PIN field instead of the password field for SIP2 authentication.

A self service circulation terminal provides library services to patrons like checkin, checkout and renewal of items plus more.
A self service process may involve:

• A patron identifies itself (i.e. by presenting a library card to the terminal)
• The terminal asks to enter a PIN for verification
• Only if the PIN matches the one stored in FOLIO, the patron may proceed using the services

Currently there is no separate field in the user record to store information about the PIN.

Another module that has expressed a requirement for a PIN is mod-inn-reach.

Related Jira issues

UXPROD-1811 - Getting issue details... STATUS

UXPROD-3040 - Getting issue details... STATUS

SIP2-89 - Getting issue details... STATUS

MODUSERS-254 - Getting issue details... STATUS

SIP2-61 - Getting issue details... STATUS

Requirements for a PIN

So far, the following requirements have been gathered:

• The PIN has to be stored in a secure manner (i.e. in form of hash/salt)
• The PIN verification has to use state-of-the-art cryptography (i.e. PBKDF2 + SHA-256, see RFC 8018) that doesn't send the plaintext password to the server (required by GDPR if the patron is charged for the transaction); if explicitly enabled by the tenant administrator an additional API accepts a plaintext password from legacy terminals.
• The PIN should support alphanumeric and special characters and have at least 4 characters
• No further restrictions to the format, a 4-digit number is valid

Proposed approach

Storing the PIN securely as hash/salt prevents this information from being a direct part of a user record, as user records are public to a wider audience.

mod-login already provides functionality for hashing and hash storage, but seems bound to the login context, which patrons aren't a part of.

So one approach could be a new module that handles hashing, hash storage and hash validation for PINs, similar to what is done in mod-login for passwords.

Items for discussion

We need a place to securely store PIN information for patrons.

Is a separate PIN-related module a good approach and what are potential drawbacks?

If not, what existing module should the PIN functionality be part of?

Updated approach

The comments on this page and a discussion of this topic in the tech leads meeting on (2021-06-23) have been in favor of putting the PIN related functionality into the mod-users module. PIN related functions should be provided as part of a separate interface and the data kept in a separate table, so that queries to a user record do not return PIN related information.

In a first stage the interface will provide following endpoints and methods:

/patron-pin
  POST - to initially set a PIN for a patron/user
  DELETE - to delete a PIN record

/patron-pin/verify
  POST - verify whether a PIN matches the one stored for a user
    returns:
      - 200 Ok, if supplied PIN matches the stored record
      - 422 Unprocessable Entity, otherwise

Data thats beeing sent in POST requests could look like:

{
  "userId": "b90c78bb-1be2-45a3-ba47-1ec6a858002e",
  "pin": "1234"
}

The PIN being sent in cleartext as part of JSON data was considered OK, as communication happens on private networks and/or TLS is in place. Internally the PIN will be stored as a salted hash.

• To keep the consistency between the users table and the pin table
  • it should not be possible to store a PIN for a non-existing userId
  • also the PIN information should be removed once a user gets deleted
• PINs will not be created automatically
• Setting/updating of PINs will happen through:
  • the library's discovery system (mod-patron)
  • the user import process (mod-users-import)

The functionality for an email based PIN reset will be addressed later and should work similar to FOLIOs password reset mechanism.