Patron Authorisations Request

[bic-org-uk]

Patron Authorisations Request

[franciscave]

How will authorisations be represented in the response? Do we need to define a new Authorisation entity and associated XML binding?

[franciscave]

Do we need a new entity, or do we simply need a new code list?

Either way, the Patron entity will need to contain a new, repeatable property that either references an authorisation entity or contains an authorisation code.

If the list of possible authorisations is short and can be expressed as a code list, creating a new entity would appear to be overkill. If we want to allow libraries to define their own authorisation codes, or to be able to extend a short, standard code list, an authorisation entity makes sense.

In the interests of flexibility, I therefore feel inclined to create a new entity Authorisation, but also create a new code list for authorisations where there is a consensus on their meaning and use, possibly including 'Parental Consent / Internet' (issue #58).

[franciscave]

Done. Please review new text. If you're happy with what I've done, over to Matthew to implement the schema changes.

[mdovey]

In working on the schema, I note that this entity does not have an identifier property (unlike other entities). Is this deliberate?

[franciscave]

I'm not sure what you mean. E13D01 is 'Authorisation code/identifier'. Are you saying that these are two different things? I don't believe they need to be different. The Authorisation entity does not yet have an 'Authority identifier', if that is what you're referring to, because I have only just proposed that we add an Authority (or Institution) entity. If we add that entity, we can add an Authority reference element to the Authorisation entity, to point to the relevant authority. If we decide against adding an Authority entity, but we need some other way to identify the authority responsible for the authorisation, yes, we'll need to add something else, e.g. 'authority name'.

[mdovey]

For all the other entities ExxD01 uses the name "identifier" for the xml element. E13 is unique in that E13D01 uses the name "code" for the corresponding xml element according to the XML bindings spec.

My question is whether it is intentional for E13D01 to differ from the convention used for other entities, or whether we should call E13D01 "identity" in the XML schema (without changing same semantics as regards content)?

[franciscave]

Oh, I see! Doh! I hadn't looked at the XML binding. For consistency it should be 'identifier', not 'code'. I think the reason I had chosen code was because currently the identifier can be a code value from list AUT.

I think I was too hasty in designing the Authorisation entity. I think that an Authorisation record needs both a unique identifier and a code indicating the type of authorisation that is being granted. The code list AUT is really an enumeration of standard authorisation types. If two patrons are both given authorisation of the same type, that doesn't mean that they share the same authorisation record, We might need to add more information to an authorisation that, for the same type (e.g. parental consent), could vary from one patron to another, e.g. authorisation from/to date/times, or references to associated manifestations/items, or references to associated authority or locations.

Since this is a new feature that hasn't been added to the schema yet, I think we can change the way that Authorisation entities are defined in the documentation. I'd now suggest the following:

E13D01 Authorisation identifier (1)
E13D02 Authorisation type (0-1) code from list AUT
E13D03 Authorisation heading (0-1) mutually exclusive with E13D02
E13C04 Authorisation description/note (0-n)
E13D04.1 Note type (0-1)
E13D04.2 Note date/time (0-1)
E13D04.3 Note text (1)

To this we may need to add other elements to further describe the authorisation, but only when the use case has been made for doing so.

[franciscave]

I've updated the LCF Version 1.0.1 documentation and the XML binding.

[mdovey]

Can I suggest that E13D02 is called authorisation-type in the XML binding rather than just type (to be consistent with e.g. E01C03, E01D04.1, E01D13.1, E01D14.1, E01D21.1 etc.)

[franciscave]

Ouch! My fault for not checking. Done.

[franciscave]

I have also corrected the cardinality of E13D01 in the XML binding and added a note about this element being mandatory except when creating a new entity, for consistency with the XML bindings for other entity types. Thanks to Matthew for alerting me to this error, and a similar error in the cardinality of E09D01 in the XML binding, which I have also corrected and added the note.

[franciscave]

Sorry, I probably closed this issue prematurely. Does anything need to be added to the REST Web Service Specification by way of an example? I think what Anthony had suggested when opening this issue is right, i.e.:

GET /lcf/1.0/patrons/{unique-id}/authorisations

This is essentially the same as retrieving any kind of entity list, e.g.

GET /lcf/1.0/manifestations/12345678790/items

[franciscave]

As discussed at the Review Group meeting on 22 February 2018, we should implement patron verification as originally proposed by Anthony. As I understand it, HTTP basic access authentication involves the user agent adding an Authentication field to the HTTP request containing a Base-64 (or similar) encoding of user-id:pin, e.g.

Authentication: Basic {Base-64 encoded string}

Or are we saying this should be a query parameter on the end of the GET URI?

[franciscave]

Sorry, having scanned RFC 7617 (The 'Basic' HTTP Authentication Scheme), the correct request header field is:

Authorization: Basic {Base-64 encoded string)

But I think I have confused the use of the term "user" in this context. RFC 7617 uses the term "user-id" to mean the identifier of the user-agent, i.e. the terminal application, not the identifier of the human user, i.e. the Patron. In that case RFC 7617 would apply to terminal authentication, not Patron authentication. So, having been round the houses on this one, I think that Anthony is simply suggesting that Patron authentication should use the same method as RFC 7617 for communicating the Patron's ID and PIN as a Base-64 encoded string {patron-id}:{PIN}, but as a query parameter rather than as a header field.

As an aside, where we refer to Terminal application authentication in the REST Web Service specification, perhaps it would be clearer if, instead of using the informal phrase 'HTTP challenge-response authentication using status code 401', we actually state 'HTTP Basic Authentication in conformance with RFC 7617'. This requires that servers use status code 401 in challenges.

[franciscave]

Under Terminal application authentication in the REST Web Service specification I've added a reference to a new note [4] containing a link to RFC 7617. I think that is the least disruptive way of addressing that side-issue.

[mdovey]

When we first discussed this topic there was concern about passing authentication information as part of the query string as this might be recorded in web server logs etc.

Whilst a base64 encoded userid\pin is not quite as bad as cleartext userid\pin the same concerns would equally apply.

[franciscave]

Oh yes, that's right, it's coming back to me.

Is there a way of combining terminal and patron authentication, e.g.

patron-id+patron-PIN@terminal-id:terminal-pwd

so that all elements can be combined in the Base-64 encoded credentials in the Authorization header field? This would of course only work if neither patron-id nor patron-PIN contain the + sign, @ sign or colon character. Maybe there's a better choice of separator characters.

What does Anthony mean by "encoded with a pre-shared secret"?

[mdovey]

Err, "enciphered with a pre-shared secret"?

Seriously, a standard encryption algorithm where you need a key to encrypt and decrypt the message (the most simplest would be to shift the alphabet by a certain number of characters so that "abcd" becomes "cdef", and then the pre-shared secret is the number you shift by in this simple example 2).

The problem here is how the secret is pre-shared, and how often the secret is changed etc. One approach might be to have a new REST method for passing the shared secret (as the body of a POST) - however, at this point we start re-inventing the authentication wheel.

[franciscave]

I'm afraid that I know very little about encryption, so please pardon my excessive ignorance!

We don't want to re-invent the authentication wheel.

Is it not sufficient to use HTTP Basic Authentication, assuming that HTTPS is being used? The header fields won't be stored in the web server log, will they? If that is good enough to be going along with, all we need to agree is how to pass the patron ID and PIN along with the terminal ID and password in that single header field. Or am I still misunderstanding something about what is needed here?

[anthonywhitford]

The text referring to a pre-shared secret was in the notes from the plugfest. At the review meeting the intention was to keep things easy to implement at this stage, so Matthew's reference to using base64 would at least unblock the current issue, while not transferring in clear text. The intention was to pass the patron credential as a header expressly to avoid it being logged by default on the query string. Regarding HTTP Basic Auth, that's the mechanism for the terminal to authenticate making the web service call itself. The patron credentialbeing passed as a separate header means these two are not in conflict. On 23 Feb 2018 18:26, "franciscave" <[email protected]> wrote: I'm afraid that I know very little about encryption, so please pardon my excessive ignorance! We don't want to re-invent the authentication wheel. Is it not sufficient to use HTTP Basic Authentication, assuming that HTTPS is being used? The header fields won't be stored in the web server log, will they? If that is good enough to be going along with, all we need to agree is how to pass the patron ID and PIN along with the terminal ID and password in that single header field. Or am I still misunderstanding something about what is needed here? — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub <#55 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AGPhJUQKm66Oq1EiPMYFgMU6YaAnohj6ks5tXwLEgaJpZM4MlOTK> .

[franciscave]

So, for passing patron - or, more generally, terminal user - credentials to the server, we need an application-specific header field. Since message header fields are extensible, we are free to define our own as needed. Following Anthony's original suggestion that we mimic HTTP Basic Authentication, how about the following?

LCF-UserVerification: xxxxxxxxxxxxxxxx

Where 'xxxxxxxxxxxxxxxx' is the Base-64 encoding of the string concatenation of ID, colon and PIN.

I suggest 'Verification' so as to avoid confusion with the LCF term 'authorisation', which refers to a patron's privileges.

[franciscave]

Assuming that we go ahead with a new request header field, we need to decide what the possible responses are. If the patron verification succeeds, the response will be the normal HTTP 200 with XML payload. If the patron verification fails, the specification currently says that this exception condition is to be communicated either using exception condition code EXC02 (invalid user ID or password) or an HTTP 401 Unauthorized. But I think that 401 Unauthorized should only be used with terminal authentication, not with patron verification. I believe that, if patron verification fails, the response should be HTTP 403 Forbidden, to distinguish it from a regular client authentication failure.

So, my proposal is to alter the Note to EXC02 to indicate that this code is equivalent to HTTP response code 403.

[franciscave]

I have now revised Implementation Note 2 to reflect the outcome of discussion here and offline concerning a recommended method for patron authentication. Please review.

[franciscave]

I have now removed all the user-id and passwd parameters from the REST Web Service specification, in line with our recommendation to use the header field method for patron authentication.

[anthonywhitford]

Discussion in the Technical Panel meeting on 2018-05-02 agreed that the authentication and authorisation work was now correctly specified and this issue can be closed.