Recommendations for use of OpenID Connect for Multiple Seller systems

[nickevansuk]

Proposer

ODI

Why is this needed?

Although the specification currently recommends OAuth2 for API implementation, it does not give concrete recommendations around how this should be implemented.

Such recommendations would allow for convergence of authentication between booking systems, which would greatly simplify the broker's integration requirements and lower the barrier to entry for them: especially for Booking Systems that support multiple Sellers.

It is crucial that we provide just enough to cover which flows, scopes and claims should be used - to help implementers narrow down the range of possible options - rather than getting into the weeds of the implementation itself. The default settings of most OpenID Connect libraries will work for our usecase, when set up to use the flows, scopes and claims included in this proposal.

Proposal

This proposal suggests updates to the specification as follows, based on the prior work in this area within the .NET tutorial. The recommendation suggests use of OpenID Connect, which is a well established and widely used approach to the type of authentication.

11.7.1 API level authentication and data security

This specification does not mandate a particular authentication method, but its recommendation is that implementers should consider using [OAuth2] as it is well-defined, widely supported and can be used in a variety of different application flows (e.g. via a JavaScript web application or between servers). For Booking Systems that support multiple Sellers, OpenID Connect ([[OpenIdConnect]]) is recommended in addition to this for the Booking Partner to access a particular Seller.

11.7.4 OpenID Connect Booking Partner Authentication for Multiple Seller Systems

For Booking Systems that support multiple Sellers, OpenID Connect ([[OpenIdConnect]]) is recommended when providing the Booking Partner access to a particular Seller.

In order to support convergence amongst implementations, a number of recommendations are included below, which include recommended terms for names of Scopes and Claims.

This section requires a basic understanding of OpenID Connect.

OAuth Flows and Scopes

The objective of an OAuth flow is for the Booking Partner to acquire an Access Token, which is an Authentication Credential that provides access to a subset the Open Booking API endpoints of the Booking System for a particular Seller, or to the Orders feed for all authorised Sellers.

The Booking Partner SHOULD include the relevant Access Token in the Authorization header when accessing the Open Booking API endpoints.

An expiry duration of 15 minutes is RECOMMENDED for Access Token, to ensure the Seller has sufficient control.

The recommended flows are as following:

• Authorization Code Flow for Sellers to approve Booking Partners to interact with bookings on their behalf.

• Client Credentials Flow to provide access to a single Orders feed for all authorised Sellers.

An OAuth Scope defines access to a set of endpoints, and also expectations about Claims returned. An Access Token can be requested that includes a number of scopes, via the relevant OAuth flow.

The RECOMMENDED Scopes and flows are defined in the table below:

Scope	Endpoints	OAuth flow used to acquire Access Token
openactive-openbooking	OrderQuote Creation (C1) OrderQuote Creation (C2) OrderQuote Deletion Order Creation (B) Order Deletion Order Cancellation Order Status	Authorization Code Flow
openactive-ordersfeed	Orders RPDE Feed	Client Credentials Flow

In order to implement functionality to suspend bookings temporarily with a particular Seller, the Booking System SHOULD temporarily revoke access to the openactive-openbooking scope. The Seller's items SHOULD still be available in the Orders Feed, and hence Customers are still able to receive refunds and notifications, but cannot make new bookings or initiate cancellations.

Authorization Code Flow

To access any of the endpoints defined in this specification other than the Orders RPDE Feed, the Booking Partner SHOULD first acquire a valid Access Token with an openactive-openbooking Scope, by having a particular Seller complete the Authorization Code Flow.

This flow presents the Seller with an authentication and consent prompt, that they will be familiar from websites that offer "Login with my social media account" functionality:

A Refresh Token SHOULD also be also provided during this flow, which allows the Booking Partner to request another Access Token once it has expired, without the Seller needing to reauthenticate.

Additionally, a "one-time usage" ID Token SHOULD be provided during this flow which contains the SellerId and other details of the Seller. This allows the Booking Partner to store the Access Token and Refresh Token against the correct SellerId in their database, so they can use these when booking the Seller's opportunities.

The Authorization Request of this flow SHOULD include the openactive-openbooking, openid, and offline_access Scopes, to ensure that an Access Token, ID Token and Refresh Token are all returned for the authenticating Seller.

For this flow, it is RECOMMENDED that the OpenID Connect subject is not the end user who is following the OAuth flow, but is instead the Seller that they represent - such that if, for example, the end user no longer works for the Seller and deletes their account, their authentication grants remain unaffected. This recommendation conforms with OpenID Connect from a technical perspective, which is useful when utilising existing libraries.

Client Credentials Flow

The straightforward Client Credentials Flow SHOULD be used to retrieve an Access Token with an openactive-ordersfeed Scope, which grants access to the Orders Feed endpoint as above.

The Authorization Request of the flow SHOULD include only the openactive-ordersfeed Scope.

Custom Claims

Claims are simply key-value pairs that are included in Access Tokens and ID Tokens; each Claim is "claiming" a fact about the subject (in this case, the Seller). For example a token may include a "claim" that the Seller has a name of "Acme Leisure". The OpenActive namespace includes a number of terms for use as Custom Claims. ##### ID Token claims The ID Token is designed to be read by the Booking Partner to give them information about the Seller that has just authenticated. This allows the Booking Partner to store the Access Token and Refresh Token against the correct `SellerId` in their database, so they can use these when booking the Seller's opportunities. It is RECOMMENDED that the `openactive-openbooking` Scope includes an implicit request that Claims listed below are included in the ID Token. The following custom claims are for use by the Booking Partner, and must conform to the custom claim names specified below. The custom claim names are collision-resistant in accordance with [the OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.5.1.2). | Custom claim | Description | Exactly matches | | :--- | :--- | :--- | | `https://openactive.io/sellerName` | The seller name. | `name` of `seller` | | `https://openactive.io/sellerLogo` | A URL of the logo of the Seller. | `logo` of `seller` | | `https://openactive.io/sellerUrl` | The URL of the website of the Seller. | `url` of `seller` | | `https://openactive.io/sellerId` | The Seller ID as a JSON-LD ID. Also allows for compatibility with existing authentication implementations which might be using "sub" to include a different identifier. Booking partners will use this to determine which Seller ID the provided accessToken is intended for. | `id` of `seller` | | `https://openactive.io/bookingServiceName` | The `name` of the Booking System | `name` of `bookingService` | | `https://openactive.io/bookingServiceUrl` | The `url` of the website of the Booking System | `url` of `bookingService` | ##### Access Token claims To help simplify the implementation, it is recommended that Access Tokens include the following custom claims. The Access Token is only read internally by the Booking System, and so these claims are simply a recommendation. Hence the claim names do not need to be standardised as long as they are internally consistent.

Custom claim	Description	Scopes
https://openactive.io/clientId	The Booking Partner Client ID that requested the Access Token. Note that this claim is due to be featured in a future OAuth 2.0 specification, and it is RECOMMENDED that the newly specified claim is used in preference to this one, once ratified.	openactive-openbooking and openactive-ordersfeed
https://openactive.io/sellerId	Seller ID as a JSON-LD ID, which is useful to be provided to Open Booking API endpoints to determine which Seller the Access Token is intended for. It is consistent with the claim name used in the ID Token.	openactive-openbooking

[lukehesluke]

@nickevansuk could I suggest adding sellerEmail to the custom ID Token Claims.

Why? I think it would be useful for any OpenID clients of these Multiple Seller Systems to be able to contact a particular seller (e.g. if their access tokens became revoked for some reason). There is no way to get a Seller's email using the Seller ID from an Open Booking API implementation (short of downloading and scanning their entire Opportunity RPDE feeds!)

Custom claim	Description	Exactly matches
https://openactive.io/sellerEmail	The seller's email address.	email of seller

Edit(2022-04-27): Actually is this redundant because the email scope can be used instead?