docs: Document clearly the available Authentication Strategies (#578)

--------- Co-authored-by: Nick Evans <2616208+nickevansuk@users.noreply.github.com>
openactive · Sep 20, 2023 · 5a292cc · 5a292cc
1 parent 8fb5565
commit 5a292cc
Show file tree

Hide file tree

Showing 10 changed files with 156 additions and 192 deletions.
diff --git a/README.md b/README.md
@@ -4,14 +4,16 @@ To join the conversation, we're on the [OpenActive Slack](https://slack.openacti
 
 The general aim of this project is to allow end to end testing of the various flows and failure states of the Open Booking API.
 
-Running `npm start` in the root will run the OpenActive Test Suite, which is actually comprised of three packages:
-* [OpenID Test Client](./packages/openactive-openid-test-client): this connects to the target Open Booking API's OpenID Provider. This allows the Broker and Integration tests to authorize with the implementation
-* [Broker Microservice](./packages/openactive-broker-microservice/): this sits in between the test suite and the target Open Booking API implementation. This allows the integration tests to watch for changes to the various RPDE feeds.
+Running `npm start` in the root will run the OpenActive Test Suite, which is actually comprised of these packages:
+
 * [Integration Tests](./packages/openactive-integration-tests): this performs automated tests against the API.
+* [Broker Microservice](./packages/openactive-broker-microservice/): this sits in between the test suite and the target Open Booking API implementation. This allows the integration tests to watch for changes to the various RPDE feeds.
+* [OpenID Test Client](./packages/openactive-openid-test-client): this connects to the target Open Booking API's OpenID Provider. This allows the Broker and Integration tests to authorize with the implementation
+* [Test Interface Criteria](./packages/test-interface-criteria/): this allows test suite to tailor specific opportunities to specific tests by implementing the [OpenActive Test Interface](https://openactive.io/test-interface/) Criteria.
 
 # Usage
 
-Running `npm start` will orchestrate running the [OpenID Test Client](./packages/openactive-openid-test-client/), [Broker Microservice](./packages/openactive-broker-microservice/) and the [Integration Tests](./packages/openactive-integration-tests/) in order to test your Open Booking API implementation.
+Running `npm start` will orchestrate running the [Broker Microservice](./packages/openactive-broker-microservice/) and the [Integration Tests](./packages/openactive-integration-tests/) in order to test your Open Booking API implementation.
 
 Note that the implementation under test will need to implement the [OpenActive Test Interface](https://openactive.io/test-interface/) to run in controlled mode, and for selected tests.
 
@@ -42,6 +44,121 @@ For more information about this use of `NODE_ENV` see this [documentation](https
 
 By convention, much of the documentation assumes you to have created a `config/dev.json` file, which Test Suite will use when env var `NODE_ENV=dev`. But you can use any name you like, and have multiple configuration files for different environments.
 
+### Configuration for `sellers` within `./config/{NODE_ENV}`
+
+The `primary` Seller is used for all tests, and random opportunities used when `"useRandomOpportunities": true` are selected from this Seller. The `secondary` Seller is used only for [multiple-sellers](./test/features/core/multiple-sellers/README.md) tests.
+
+An example, using OpenID Connect Authentication:
+
+```json
+  "sellers": {
+    "primary": {
+      "@type": "Organization",
+      "@id": "https://reference-implementation.openactive.io/api/identifiers/sellers/0",
+      "authentication": {
+        "loginCredentials": {
+          "username": "test1",
+          "password": "test1"
+        }
+      },
+      "taxMode": "https://openactive.io/TaxGross",
+      "paymentReconciliationDetails": {
+        "name": "AcmeBroker Points",
+        "accountId": "SN1593",
+        "paymentProviderId": "STRIPE"
+      }
+    },
+    "secondary": {
+      "@type": "Person",
+      "@id": "https://reference-implementation.openactive.io/api/identifiers/sellers/1",
+      "authentication": {
+        "loginCredentials": {
+          "username": "test2",
+          "password": "test2"
+        }
+      },
+      "taxMode": "https://openactive.io/TaxNet"
+    }
+  }
+```
+
+Description of each field:
+
+* `authentication`: Check out the [**Configuration for Seller Authentication**](#configuration-for-seller-authentication) section.
+* `taxMode`: Which [Tax Mode](https://openactive.io/open-booking-api/EditorsDraft/1.0CR3/#tax-mode) is used for this Seller.
+
+  **Note: If testing both Tax Modes, make sure that there is at least one Seller with each**. Alternatively, if not supporting multiple Sellers, you can run the Test Suite once with `"taxMode": "https://openactive.io/TaxNet"` and once with `"taxMode": "https://openactive.io/TaxGross"`. However, it is not currently possible to generate a certificate that covers both configurations unless multiple Sellers are supported.
+* `paymentReconciliationDetails`: If testing [Payment Reconciliation Detail Validation](https://openactive.io/open-booking-api/EditorsDraft/1.0CR3/#payment-reconciliation-detail-validation), include the required payment reconciliation details here.
+
+### Configuration for Seller Authentication
+
+In order to make bookings for a specific Seller's Opportunity data, some kind of authentication is required to ensure that the caller is authorized to make bookings for that Seller.
+
+Test Suite allows for a few different options for Seller Authentication. This determines the data to put in the `authentication` field for each Seller:
+
+#### OpenID Connect
+
+[View Spec](https://openactive.io/open-booking-api/EditorsDraft/#openid-connect-booking-partner-authentication-for-multiple-seller-systems)
+
+You'll need the username/password that the Seller can use to log in to your OpenID Connect Provider.
+
+Example:
+
+```json
+  "sellers": {
+    "primary": {
+      // ...
+      "authentication": {
+        "loginCredentials": {
+          "username": "test1",
+          "password": "test1"
+        }
+      }
+    },
+```
+
+#### Request Headers
+
+Just a set of request HTTP headers which will be used to make booking requests. There are no restrictions on the `requestHeaders` that can be specified.
+
+Example:
+
+```json
+  "sellers": {
+    "primary": {
+      // ...
+      "authentication": {
+        "loginCredentials": null,
+        "requestHeaders": {
+          "X-OpenActive-Test-Client-Id": "booking-partner-1",
+          "X-OpenActive-Test-Seller-Id": "https://localhost:5001/api/identifiers/sellers/1"
+        }
+      }
+    },
+```
+
+#### Client Credentials
+
+[OAuth Client Credentials](https://oauth.net/2/grant-types/client-credentials/) are used to make booking requests.
+
+Example:
+
+```json
+  "sellers": {
+    "primary": {
+      // ...
+      "authentication": {
+        "loginCredentials": null,
+        "clientCredentials": {
+          "clientId": "clientid_XXX",
+          "clientSecret": "example"
+        }
+      }
+    },
+```
+
+This is different from the behaviour in the Client Credentials sub-section mentioned within the [OpenID Connect Booking Partner Authentication for Multiple Seller Systems](https://openactive.io/open-booking-api/EditorsDraft/#openid-connect-booking-partner-authentication-for-multiple-seller-systems) section in the spec as, in this case, Client Credentials are used to make booking requests for this Seller, rather than just to view the Booking Partner's Orders Feed.
+
 ## Installation
 
 Node.js version 14 or above is required.
@@ -52,7 +169,7 @@ npm install
 
 This will install the dependencies needed for all packages in the test suite.
 
-For developers that are customising the installation, for use in e.g. Docker, the directory `./packages/test-interface-criteria` is a dependency, and so must be present during `npm install`.
+For developers that are customising the installation, for use in e.g. Docker, the directories `./packages/test-interface-criteria` and `./packages/openactive-openid-test-client` are dependencies, and so must be present during `npm install`.
 
 ## Running
 
@@ -143,3 +260,23 @@ In order to run the tests in random mode, the target Open Booking API implementa
 # Contributing
 
 - [Contributing to the project](./CONTRIBUTING.md)
+
+# Concepts
+
+## Booking Partner Authentication Strategy
+
+The method by which a [Booking Partner](https://openactive.io/open-booking-api/EditorsDraft/#dfn-booking-partner) authenticates with the Open Booking API implementation. There are a number of supported strategies, including OpenID Connect, HTTP Header, etc.
+
+Your impementation will need to support at least one Authentication Strategy for each of [**Orders Feed Authentication**](#orders-feed-authentication) and [**Booking Authentication**](#booking-authentication).
+
+### Orders Feed Authentication
+
+How a Booking Partner accesses the [Orders Feed](https://openactive.io/open-booking-api/EditorsDraft/#dfn-orders-feed) containing updates to Orders that they have created.
+
+For Test Suite, the selected Orders Feed Authentication Strategy is configured with the [`broker.bookingPartners` configuration property](./packages/openactive-broker-microservice/README.md#bookingpartners) and documentation on the supported strategies can be found there.
+
+### Booking Authentication
+
+How a Booking Partner accesses the booking endpoints (C1, C2, B, etc) for a specific Seller's data. This differs from [Orders Feed Authentication](#orders-feed-authentication) as it can be specified at the per-Seller level for Multiple Seller Systems (relevant feature: [`multiple-sellers`](packages/openactive-integration-tests/test/features/core/multiple-sellers/)).
+
+For Test Suite, the selected Booking Authentication Strategy is configured with the [`sellers` configuration property](#configuration-for-seller-authentication) and documentation on the supported strategies can be found there.
diff --git a/packages/openactive-broker-microservice/README.md b/packages/openactive-broker-microservice/README.md
@@ -235,87 +235,6 @@ Use this authentication strategy when using [Client Credentials Flow](https://op
   "initialAccessToken": "openactive_test_suite_client_12345xaq"
 ```
 
-### `sellers`
-Config for [Sellers](https://openactive.io/open-booking-api/EditorsDraft/1.0CR3/#dfn-seller) whose opportunities are booked are booked through the Booking System when Test Suite is run.
-
-#### Multi-Seller systems
-In multi-seller systems, Broker can book opportunities from two Sellers, named `primary` and `secondary`.
-
-```json
-   "sellers": {
-    "primary": {
-      "@type": "Organization",
-      "@id": "https://reference-implementation.openactive.io/api/identifiers/sellers/1",
-      "authentication": {
-        "loginCredentials": {
-          "username": "test1",
-          "password": "test1"
-        }
-      },
-      "taxMode": "https://openactive.io/TaxGross",
-      "paymentReconciliationDetails": {
-        "name": "AcmeBroker Points",
-        "accountId": "SN1593",
-        "paymentProviderId": "STRIPE"
-      }
-    },
-    "secondary": {
-      "@type": "Organization",
-      "@id": "https://reference-implementation.openactive.io/api/identifiers/sellers/2",
-      "authentication": {
-        "loginCredentials": {
-          "username": "test2",
-          "password": "test2"
-        }
-      },
-      "taxMode": "https://openactive.io/TaxNet"
-    }
-  }
-```
-
-The `authentication` field can contain various authentication strategies: [Auth Code Flow](https://openactive.io/open-booking-api/EditorsDraft/1.0CR3/#dfn-authorization-code-flow), Bearer credentials, or API headers. Auth Code Flow is [recommended](https://openactive.io/open-booking-api/EditorsDraft/1.0CR3/#openid-connect-booking-partner-authentication-for-multiple-seller-systems) for Multi-Seller systems.
-Examples of how to define Auth Code flow credentials for Multi-Seller systems are shown above.
-
-#### Single-seller systems
-For single-seller systems, Broker can book opportunities from the only seller.
-
-```json
-"sellers": {
-    "primary": {
-      "@type": "Organization",
-      "@id": "https://localhost:5001/api/identifiers/seller",
-      "authentication": {
-        "loginCredentials": null,
-        "requestHeaders": {
-          "X-OpenActive-Test-Client-Id": "booking-partner-1",
-          "X-OpenActive-Test-Seller-Id": "https://localhost:5001/api/identifiers/seller"
-        }
-      }
-    },
-    "secondary": null
-  }
-```
-
-The `authentication` field can contain various authentication strategies: [Client Credentials](https://openactive.io/open-booking-api/EditorsDraft/1.0CR3/#dfn-client-credentials-flow), Bearer credentials, or API headers. 
-
-Clients credentials can be defined as follows:
-```json
-"sellers": {
-    "primary": {
-      "@type": "Organization",
-      "@id": "https://localhost:5001/api/identifiers/seller",
-      "authentication": {
-        "loginCredentials": null,
-          "clientCredentials": {
-            "clientId": "clientid_XXX",
-            "clientSecret": "example"
-          }
-      }
-    },
-    "secondary": null
-  }
-```
-
 ## Broker Microservice API
 
 Broker Microservice exposes an API which is used by [Integration Tests](../openactive-integration-tests/) and can be used by users to debug potential issues with the [Booking System](#booking-system-under-test).

diff --git a/packages/openactive-integration-tests/README.md b/packages/openactive-integration-tests/README.md
@@ -122,99 +122,6 @@ The value can be any string, such as `uat-ci`, or `alex-dev`.
 Test results are written to `*.md` within the directory specified by `outputPath` in Markdown format.
 
 
-## Configuration for `sellers` within `./config/{NODE_ENV}.json`
-
-The `primary` Seller is used for all tests, and random opportunities used when `"useRandomOpportunities": true` are selected from this Seller. The `secondary` Seller is used only for [multiple-sellers](./test/features/core/multiple-sellers/README.md) tests.
-
-An example, using OpenID Connect Authentication:
-
-```json
-  "sellers": {
-    "primary": {
-      "@type": "Organization",
-      "@id": "https://reference-implementation.openactive.io/api/identifiers/sellers/0",
-      "authentication": {
-        "loginCredentials": {
-          "username": "test1",
-          "password": "test1"
-        }
-      },
-      "taxMode": "https://openactive.io/TaxGross",
-      "paymentReconciliationDetails": {
-        "name": "AcmeBroker Points",
-        "accountId": "SN1593",
-        "paymentProviderId": "STRIPE"
-      }
-    },
-    "secondary": {
-      "@type": "Person",
-      "@id": "https://reference-implementation.openactive.io/api/identifiers/sellers/1",
-      "authentication": {
-        "loginCredentials": {
-          "username": "test2",
-          "password": "test2"
-        }
-      },
-      "taxMode": "https://openactive.io/TaxNet"
-    }
-  }
-```
-
-Description of each field:
-
-* `authentication`: Check out the **Configuration for Seller Authentication** section.
-* `taxMode`: Which [Tax Mode](https://openactive.io/open-booking-api/EditorsDraft/1.0CR3/#tax-mode) is used for this Seller.
-
-  **Note: If testing both Tax Modes, make sure that there is at least one Seller with each**. Alternatively, if not supporting multiple Sellers, you can run the Test Suite once with `"taxMode": "https://openactive.io/TaxNet"` and once with `"taxMode": "https://openactive.io/TaxGross"`.
-* `paymentReconciliationDetails`: If testing [Payment Reconciliation Detail Validation](https://openactive.io/open-booking-api/EditorsDraft/1.0CR3/#payment-reconciliation-detail-validation), include the required payment reconciliation details here.
-
-### Configuration for Seller Authentication
-
-In order to make bookings for a specific Seller's Opportunity data, some kind of authentication is required to ensure that the caller is authorized to make bookings for that Seller.
-
-Test Suite allows for a few different options for Seller Authentication. This determines the data to put in the `authentication` field for each Seller:
-
-**OpenID Connect**
-
-[View Spec](https://openactive.io/open-booking-api/EditorsDraft/1.0CR3/#openid-connect-booking-partner-authentication-for-multiple-seller-systems)
-
-You'll need the username/password that the Seller can use to log in to your OpenID Connect Provider.
-
-Example:
-
-```json
-  "sellers": {
-    "primary": {
-      // ...
-      "authentication": {
-        "loginCredentials": {
-          "username": "test1",
-          "password": "test1"
-        }
-      }
-    },
-```
-
-**Request Headers**
-
-Just a set of request HTTP headers which will be used to make booking requests.
-
-Example:
-
-```json
-  "sellers": {
-    "primary": {
-      // ...
-      "authentication": {
-        "loginCredentials": null,
-        "requestHeaders": {
-          "X-OpenActive-Test-Client-Id": "booking-partner-1",
-          "X-OpenActive-Test-Seller-Id": "https://localhost:5001/api/identifiers/sellers/1"
-        }
-      }
-    },
-```
-
 ## Reading test results
 
 To read the markdown files that are written to the directory specified by `outputPath`, the [Markdown Viewer Chrome Extension](https://chrome.google.com/webstore/detail/markdown-viewer/ckkdlimhmcjmikdlpkmbgfkaikojcbjk) is recommended, with the following settings: