Document Use of OAuth2 Clients

* docs/authentication_and_authorisation/oauth2_clients.md: New documentation
* gn3/auth/authentication/oauth2/server.py: Raise appropriate error if no
  client is found.
* gn3/auth/authentication/oauth2/views.py: Handle exception in the case where
  a UI should be presented to the user, rather than presenting the raw JSON
  response to the user.
* gn3/errors.py: Handle any authlib OAuth2Error at the application's top-level
* gn3/templates/oauth2/oauth2_error.html: Handle any authlib OAuth2Error at
  the application's top-level

1 files changed, 64 insertions, 0 deletions

diff --git a/docs/authentication_and_authorisation/oauth2_clients.md b/docs/authentication_and_authorisation/oauth2_clients.md
new file mode 100644
index 0000000..f9af8f9
--- /dev/null
+++ b/docs/authentication_and_authorisation/oauth2_clients.md
@@ -0,0 +1,64 @@
+# OAuth2
+
+The new authorisation system is made up of two layers:
+
+- Client authorisation
+- User authentication/authorisation
+
+This document will concern itself mostly with "Client Authorisation".
+
+## Client Authorisation
+
+The authentication/authorisation system will (probably) find use in the entire
+suite of applications that are under the Genenetwork umbrella.
+
+The relevant applications (as of 27 May 2023) are:
+
+- [Genenetwork 3](https://github.com/genenetwork/genenetwork3): Serves as both
+  the authorisation server and the API server.
+- [Genenetwork 2](https://github.com/genenetwork/genenetwork2): Will eventually
+  be the main user-facing UI making requests to GN3 for data and computational
+  requests.
+- [QC and Data Upload](https://gitlab.com/fredmanglis/gnqc_py): Provides a means
+  to upload new data into the Genenetwork database. It does perform some
+  quality-control on the data before upload. Currently, this application is not
+  available to the general public due to the potential to mess up the data. Once
+  the auth system has been running a while, and the major bugs quashed, this
+  will be integrated into the other system and allow users to upload their own
+  data.
+
+In this case, the GN2 and QC applications would be clients to GN3 (as the auth
+server), and will have specific scopes of access.
+
+As such, we need to register the clients that can access the authorisation
+server.
+
+If you try to access the authorisation server, or for that matter, the API
+server with a client that is not registered, you will receive an error message
+of the form:
+
+```json
+{
+    "error": "invalid_client",
+    "error_description": "No client found for the given CLIENT_ID and CLIENT_SECRET."
+}
+```
+
+### Registering a new OAuth2 Client
+
+- **TODO**: Implement client registration then provide docs here.
+
+**NOTES**:
+
+- Collect appropriate client data and register (provide means)
+- Get registered client's "CLIENT ID" and "CLIENT SECRET" values
+- Configure values on client
+
+## User Authentication/Authorisation
+
+A user will make use of (an) authorised client(s) (see 'Client Authorisation'
+section above) to access the authorisation and API servers.
+
+Once the user has authenticated (provided valid authentication credentials),
+they will be able to access the resources in the system according to the roles
+and privileges that they are authorised for.