Re-aligning Authentication for OPDS with OAuth 2.1

[HadrienGardeur]

I've spent quite a bit of time looking into the state of OAuth 2.1 and while it's still a draft (this has been the case since 2020), it feels fairly stable in terms of scope.

Looking at the list of changes between OAuth 2.0 and 2.1 it's very obvious that this revision impacts our work very deeply:

The Implicit grant (response_type=token) is omitted from this specification
The Resource Owner Password Credentials grant is omitted from this specification

These are the two grants that we currently support and they're both being dropped from the specification. As a replacement, OAuth 2.1 recommends using the Authorization Code grant with PKCE:

The authorization code grant is extended with the functionality from PKCE (RFC7636) such that the default method of using the authorization code grant according to this specification requires the addition of the PKCE parameters

Several stakeholders have already expressed their interest in using Authorization Code with PKCE which has additional benefits in addition to being more secure (the client receives a Refresh Token in addition to an Access Token, unlike the Implicit grant).

We need to add this grant type and recommend using it over Implicit Grant and Resource Owner Password Credentials grant.

There are several redirect URI options available to native apps for receiving the authorization response from the browser, the availability and user experience of which varies by platform.

• Claimed "https" Scheme URI Redirection
• Loopback Interface Redirection
• Private-Use URI Scheme Redirection

Our usage of a shared client identifier and callback has always been a bit of a hack because by design, OAuth requires to register the client before any interaction. This doesn't fit with the open and decentralized nature of OPDS.

As we can see, the opds:// URI scheme doesn't fit with the security best practices of OAuth 2.1 but in real-word usage it has also been difficult to use it reliably.

On iOS/iPadOS/macOS, registering a URI scheme is quite unreliable, as the user has no control over which app will actually open the opds:// URI scheme. Depending on the version of the OS that's used, it will either open the first or the last app that registered this scheme.

We end up with OPDS clients that need to implement a webview to capture the opds:// URI scheme, which is frowned upon at best and even blocked by some Authorization Providers such as Google.

To work around this issue, we would need to move away from this shared redirect_uri, but I only see two options at our disposal:

• we could create a registry of well-known OPDS clients and document their client_id and redirect_uri (multiple values), which is aligned with best practices for OAuth but kind of goes against the principles of OPDS
• or we could require Authorization Servers to allow arbitrary values for redirect_uri, which is explicitly forbidden by the OAuth 2.1 specification but feels more closely aligned with OPDS

Both options have a major impact on the OPDS ecosystem:

• with a registry of well-known OPDS clients, we'd be closing the door to "public clients" with the risk of having Authorization Servers that are not up to date and only support a few clients officially listed in the registry
• but it's also doubtful that every Authorization Server will be capable of allowing arbitrary values for redirect_uri since this goes against the specification

It feels like we'll need to figure out a compromise somehow.

Specialized clients who only interact with a list of well-known Authorization Servers should register themselves to these servers and use their own client_id.

Public catalogs which are meant to interact with arbitrary OPDS clients could:

• register a list of well-known redirect_uri for our shared client_id that are in-use by popular OPDS clients, in addition to opds://
• but also allow arbitrary values for redirect_uri as long as they follow the recommendations expressed in the OPDS 2.1 spec

This way, OPDS clients could attempt to use their own redirect_uri but fallback to opds:// if they get rejected.

With this middle ground, we'll still need to maintain a list of well-known redirect_uri for the shared client identifier, but we'll minimize the risk of Authorization Servers that are not up-to-date by offering both a fallback (opds://) and potential support for arbitrary redirect_uri values.

We could also restrict the use of other values for redirect_uri strictly to the Authorization Code grant, while the Implicit grant would continue to use opds://.

[HadrienGardeur]

Let's go further and illustrate how this could work, for example using Thorium as a client.

While browsing in a catalog, Thorium receives a 401 with the following Authentication Document:

{
  "id": "http://example.com/auth.json",
  "title": "Catalog",
  "authentication": [
    {
      "type": "http://opds-spec.org/auth/oauth/implicit",
      "allowsWebview": false,
      "links": [
        {"rel": "authenticate", "href": "http://example.com/oauth/implicit", "type": "text/html"}
      ]
    },
    {
      "type": "http://opds-spec.org/auth/oauth/code",
      "allowsWebview": false,
      "links": [
        {"rel": "authenticate", "href": "http://example.com/oauth/authorize", "type": "text/html"},
        {"rel": "token", "href": "http://example.com/oauth/token", "type": "application/json"}
      ]
    }
  ]
}

You'll notice a new addition in this response: allowsWebview which indicates to OPDS clients whether a webview will be allowed to complete the Authentication Flow.

Since Thorium relies on a webview to intercept the redirect_uri with an Implicit Grant, it decides to rely on Authorization Code with PKCE instead.
Based on the recommendations for Private-Use URI Scheme Redirection, Thorium uses the following redirect-uri: org.edrlab.thorium:/
Since Thorium doesn't have a specific client_id for this Authentication Document's id, it fallbacks to the shared OPDS client identifier: http://opds-spec.org/auth/client

When calling the OAuth 2.1 Authorization Endpoint, the following parameters are sent to the Authorization Server: response_type set to code, client_id set to http://opds-spec.org/auth/client, redirect_uri set to org.edrlab.thorium:/, code_challenge based on the challenge that the client has generated and code_challenge_method set to S256.

You'll notice that while redirect_uri is optional in theory, it's very much required in the context of Authentication for OPDS where the client sets its client_id to the shared OPDS client identifier. Without it, the Authorization Server won't be able to validate and use the value for redirect_uri.

code_challenge and code_challenge_method can be optional too under specific conditions, but these conditions are not met by this use case:

To prevent injection of authorization codes into the client, using code_challenge and code_verifier is REQUIRED for clients, and authorization servers MUST enforce their use, unless both of the following criteria are met:

• The client is a confidential client.
• In the specific deployment and the specific request, there is reasonable assurance by the authorization server that the client implements the OpenID Connect nonce mechanism properly.

If we assume that the Authorization Server has properly registered the OPDS shared identifier, three different scenarios can happen based on this request:

• the Authorization Server has registered Thorium's preferred value for redirect_uri under the OPDS shared identifier
• the Authorization Server has only registered the opds:// URI scheme for the OPDS shared identifier, but allows arbitrary values for redirect_uri
• or the Authorization Server has only registered the opds:// URI scheme for the OPDS shared identifier and disallows arbitrary values for redirect_uri

For the first two scenarios, once the user has properly authenticated, Thorium will end up receiving a code and an iss containing the id of the Authentication Document. The rest of the flow goes as planned.

For the third scenario, an error response is returned by the Authorization Server.

Since the Authentication Document states that webviews are disallowed, Thorium could either:

• re-attempt to contact the Authorization Endpoint using the opds:// URI scheme, but only if it's confident that it can intercept its reponse without using a webview
• or indicate to the user that it cannot handle authentication for this catalog

[HadrienGardeur]

With this discussion, I'm also proposing the creation of a new registry that would identify well-known redirect_uri for OPDS clients.

Here are some additional thoughts:

• we could host this registry on https://registry.opds.io/
• we would only allow unique values that follow best practices either for Claimed "https" Scheme URI Redirection or Private-Use URI Scheme Redirection since Loopback Interface Redirection is potentially problematic when used on a shared client identifier
• we'll only allow clients that are targeting public catalogs with this registry, private client/server implementations are free to use whater client_id and redirect_uri they prefer, but there's no need to document them
• for a future list of OPDS catalogs, we'll need to test catalogs against that registry, to make sure that they're compatible with well-known values for redirect_uri

[mpdunlop]

but it's also doubtful that every Authorization Server will be capable of allowing arbitrary values for redirect_uri since this goes against the specification

Our server will not allow arbitrary values for redirect_uri, so I appreciate the effort being proposed in developing and maintaining a registry of known OPDS Clients and their redirect_uris.

For the first two scenarios, once the user has properly authenticated, Thorium will end up receiving a code and an iss containing the id of the Authentication Document. The rest of the flow goes as planned.

I understand why this is necessary, but I'm not sure we can do this in practice as the definition of iss is at odds with the Authentication Document's id:

• The id of the Authentication Document is a URL and contains the canonical location of the Authentication Document
  • e.g. https://example.com/auth.json
• Typically the iss is the root URL of the OAuth issuing server.
  • From RFC9207: "The iss parameter value is the issuer identifier of the authorization server which created the authorization response.
  • e.g. https://example.com

I'm not sure this is a problem at the moment - is the iss parameter necessary for validating something?

[HadrienGardeur]

I'm not sure this is a problem at the moment - is the iss parameter necessary for validating something?

When an OPDS client receives this callback, it needs to be able to tie it back to an Authentication Document's id. If a webview is used, this is very straightforward since the client controls the webview and know it's current state.

If the user is redirected to a browser, this becomes less straightforward. With the implicit grant, we required the opds:// callback to always include an id parameter that contains this value.

As an alternative, we could recommend the use of state since it's required in the callback if present in the authorization request:

"state":
REQUIRED if the state parameter was present in the client authorization request. The exact value received from the client.

[mpdunlop]

To prevent duplicating existing information across authentication documents, is there any chance that the OAuth methods supported by an OAuth Server could be communicated via their existing OIDC Discovery document?

    {
      "type": "http://opds-spec.org/auth/oidc/",
      "allowsWebview": false,
      "links": [
        {"rel": "openid-configuration", "href": "http://example.com/.well-known/openid-configuration", "type": "application/json"},
      ]
    }

The advantage of this for developers is that there exist many packages to set up OAuth automatically when pointed to an OIDC Discovery Document.

[HadrienGardeur]

I don't think that we can truly tie Authentication for OPDS to OpenID Connect.

While OIDC has gained a lot of adoption, we also have implementations in the OPDS ecosystem which do not use OIDC or even OAuth at all.

type values allow OPDS clients to select which Authorization Flow they would like to use. If this information was expressed only in an OIDC Discovery Document it would:

• force clients to fetch an additional document
• and allow OAuth grants that shouldn't really be allowed in an OPDS context

There is some duplication between the two documents for implementations that rely on an OIDC Discovery Document, but it's fairly minimal:

• discovery of the grant type (type in the Authentication Document vs response_types_supported in OIDC)
• Authorization endpoint
• Token endpoint

[mpdunlop]

Thanks for the clarification - makes sense!

[HadrienGardeur]

Since there's a lot to discuss for this re-alignment, I'll open separate discussions. Here are some of the topics that I've identified so far:

• should we remove support for Resource Owner Credentials grant from the spec?
• should we remove support for Implicit grant from the spec or label it as deprecated?
• if we drop legacy grants from the spec, should we also drop the shared identifier and its use of the opds:// URI scheme as a redirect_uri?

At this point, I don't think that dropping Basic Auth should be on the table. It's used by a large number of organizations and remains useful for simple use cases, such as self-hosted catalogs or private catalogs that do not require true user authentication.