search

openactive / open-booking-api

Repository for the Open Booking API specification
Other
2 stars 3 forks source link

Clarify the role of the authenticating party #128

Open nickevansuk opened 4 years ago

nickevansuk commented 4 years ago

Proposer

ODI

Why is this needed?

The role of the authenticating party, specifically as it relates to Middleware, has been the source of confusion for many discussions relating to the specification - see W3C Community Group call 29 Jan 2020 for an example.

The recent implementation guidance solved this problem by creating the term "Booking Partner" to explain the role of the authenticated party, and make it easier for Sellers to understand - especially in the context of "granting the [booking partner] access to my booking system". This term is used in the suggested booking system UI designs.

This proposal suggests including the term "Booking Partner" in the specification itself as a defined Actor, replacing the term "authenticating party" completely, to increase clarity overall. This also allows for the harmonisation of guidance, documentation and user experience for both technical and non-technical users, as "authenticating party" and "Authentication Credentials" are very technical terms.

This proposal does not include any functional or technical changes to the specification, it only updates and clarifies the terminology within it.

Proposal

1. Revise the actor definitions

Booking Partner

The organisation that is granted Authentication Credentials. This may be the same organisation as the Broker or may be a Middleware that represents more than one Broker. Middleware will be clients of the API defined in this specification, on behalf of its Brokers, however for simplicity the API client is referred to as the Broker throughout.

2. Update the actor diagram

actors

3. Use the "Booking Partner" in 11.7 to replace "authenticating party", and clarify

Authentication Credentials to facilitate access to the Open Booking API on behalf of one or many Brokers are uniquely and securely provisioned to the Booking Partner by the Booking System on behalf of a specific Seller. The Booking Partner may be the same organisation as the Broker or may be a Middleware that represents more than one Broker.

Where information regarding the Middleware or any other Booking Partner is required for audit, this should be captured by the Booking System at the point of provision of Authentication Credentials.

The Booking System may choose to produce usage reports against Booking Partners via their unique Authentication Credentials, as well as against Brokers

This specification permits trusted Middleware, as a Booking Partner, to use a single set of Authentication Credentials to interact with the Booking System for a particular Seller on behalf of multiple Brokers, with the Seller's explicit permission.

4. Update the data isolation diagram

authentication-credentials-data-isolation

Caption: Data is isolated between Authentication Credentials, with one set of Authentication Credentials being provisioned to a Booking Partner, and allowing access to many Brokers.

5. Update the authentication credentials diagram

authentication-credentials

nickevansuk commented 4 years ago

Though on reflection, perhaps this doesn't actually add clarity as we still need to reference Authentication Credentials in the spec? Perhaps this is better suited for guidance and UI rather than in the spec itself?