New link-level hint for authentication

[HadrienGardeur]

In our current Authentication for OPDS draft, we define two different ways that a server can trigger an Authentication Flow:

• when a client receives a 401 status code where the payload contains an Authentication Document
• when a client receives an Authentication Document in the Link header with the proper rel and type

Over the years, OPDS has struggled with two things related to authentication:

• how can we indicate that an OPDS feed or publication could return a different representation if the user is logged in?
• how can we avoid several round trips when the user actually needs to authenticate?

To cover both use cases, I'd like to propose the addition of a new link-level hint: authenticate.
This new property would provide two information to the client:

• that they might receive a different representation (for exemple with an alternate acquisition link) if they authenticate the user (this means sending a Bearer Token for OAuth or credentials for Basic Auth) when they fetch that link
• and which Access Token or credentials should be sent, thanks to a link to an Authentication Document

{
  "rel": "self",
  "href": "publication.json",
  "type": "application/opds-publication+json",
  "properties": {
    "authenticate": {
      "href": "https://example.com/authentication.json",
      "type": "application/opds-authentication+json"
    }
  }
}

This new hint would be added to an updated version of the Authentication for OPDS draft.

Any thoughts/feedback on this? cc @leonardr @llemeurfr @danielweck

[jce1028]

I am not sure how we would want to represent this but it may be prudent to consider this for OPDS item level auth. There is a function called WAYFless support. It is widely supported by various content hosts.

In SAML federations the SP (Service Provider) application needs to find out where to send the end-users for authentication. This is called discovery, there are two ways to achieve it, and doing both is recommended:

Use a discovery service such as OpenAthens Wayfinder
Support 'WAYFless' URLs

The term 'WAYFless' comes from the old Shibboleth term for discovery: Where Are You From, and how to avoid having the end user interact with it by supplying the federation identifier for the user's organization in the URL - e.g. https://sp.yourdomain.com/path?entity=https://idp.theirdomain.com/entity.

This allows the Client (that has likely already authenticated) to pass to the content host provider (SP) who may serve content to more than one library running a Shibboleth server IDP (identity provider)
The needed entityID in query parameter tells the SP what institution (IdP) to validate the user session.

[HadrienGardeur]

In SAML federations the SP (Service Provider) application needs to find out where to send the end-users for authentication.

In OPDS this would be handled by the Authentication Document.

[danielweck]

Adding @panaC to this discussion.

[HadrienGardeur]

Even with this approach, there's still one challenging use-case: the first feed in a catalog.

To overcome this issue, I think that we could also use the same hint on the self link (a requirement for both OPDS 1.x and 2.0) for the current feed.

This would look almost the same as my example above, just with a different media type:

{
  "rel": "self",
  "href": "feed.json",
  "type": "application/opds+json",
  "properties": {
    "authenticate": {
      "href": "https://example.com/authentication.json",
      "type": "application/opds-authentication+json"
    }
  }
}

A client would:

• fetch the feed and detect the hint on its self link
• and re-fetch the feed with the credentials if it has them

[mickael-menu]

I like this approach, it's more systematic for root feeds and also a nice fallback when:

• following a link missing the authenticate property
• opening directly a link outside of the "catalogs list", for example clicking on a notification to open the details of an OPDS publication

[HadrienGardeur]

I'd like to add this new property to a revision of the current Authentication for OPDS draft.

Based on experience, it solves a number of issues:

• avoiding unnecessary roundtrips (GET, 401, GET with proper headers) when authentication is required
• returning a different publication or feed for an authenticated user on public resources

The first one is fairly straightforward to understand.

For the second one, here are a few examples:

• when fetching a publication in a library's catalog, the public version might contain general availability information while the same publication may contain the position in the hold queue and estimated availability date for an authenticated user
• when fetching a feed in a catalog, the public version might return something generic while an authenticated user would get a customized feed with recommandations based on their activity

I'm tagging people who were not around at the time when this was first discussed cc @jonathangreen @tdilauro @barmintor @Apophenia

[barmintor]

I'm thinking about IIIF, which discusses in some ways the advertisement of degraded responses:
https://iiif.io/api/auth/2.0/#probe-service-response
https://iiif.io/api/auth/2.0/#tiered-access

[mpdunlop]

Is the authenticate property planned to be available for use outside of self links? If so, I think this would help us with edrlab/thorium-reader#2512

{
    "metadata": {
        "title": "Example listing publications"
    },
    "links": [
        {
            "rel": "self",
            "href": "publication.json",
            "type": "application/opds-publication+json"
        }
    ],
    "publications": [
        {
            "metadata": {
                "@type": "http://schema.org/Book",
                "title": "Moby-Dick",
                "author": "Herman Melville",
                "identifier": "urn:isbn:978031600000X",
                "language": "en",
                "modified": "2015-09-29T17:00:00Z"
            },
            "links": [
                {
                    "rel": "self",
                    "href": "http://foo.org/publication.json",
                    "type": "application/opds-publication+json"
                },
                {
                    "rel": "http://opds-spec.org/acquisition",
                    "href": "http://bar.org/license-epub.lcpl",
                    "type": "application/vnd.readium.lcp.license.v1.0+json",
                    "properties": {
                        "authenticate": {
                            "href": "https://foo.org/authentication.json",
                            "type": "application/opds-authentication+json"
                        }
                    }
                },
                {
                    "rel": "http://opds-spec.org/acquisition",
                    "href": "http://baz.org/license-pdf.lcpl",
                    "type": "application/vnd.readium.lcp.license.v1.0+json",
                    "properties": {
                        "authenticate": {
                            "href": "https://foo.org/authentication.json",
                            "type": "application/opds-authentication+json"
                        }
                    }
                }
            ]
        }
    ]
}

[mpdunlop]

I realise that listing the same authentication document here may look redundant, but having the ability to associate an authentication document with an acquisition link would allow for different endpoints to have different authentication methods.

The main thing I’d like to see is the ability to decouple a link’s location (href) from the OPDS feed or OPDS publication’s authentication document.

[HadrienGardeur]

Is the authenticate property planned to be available for use outside of self links? If so, I think this would help us with

Definitely. It's been successfuly used on:

• borrow links
• generic acquisition links
• along with APIs for adding a book to a wishlist or to sync the reading progression in a book

I realise that listing the same authentication document here may look redundant, but having the ability to associate an authentication document with an acquisition link would allow for different endpoints to have different authentication methods.

I think that this kind of redundancy is quite OK in the context of a RESTful service where you discover how to interact with a service using links.