From 58f306a38cdc1ffa0d2b79efaf8682f5663ac1d2 Mon Sep 17 00:00:00 2001 From: David Mehren Date: Sun, 12 Mar 2023 21:20:47 +0100 Subject: [PATCH] docs: Merge API Authentication docs Signed-off-by: David Mehren --- docs/content/dev/api_auth.md | 5 ---- docs/content/dev/design_docs/api_auth.md | 29 ++++++++++++++++++++++++ docs/content/dev/private-api-auth.md | 18 --------------- docs/mkdocs.yml | 1 + 4 files changed, 30 insertions(+), 23 deletions(-) delete mode 100644 docs/content/dev/api_auth.md create mode 100644 docs/content/dev/design_docs/api_auth.md delete mode 100644 docs/content/dev/private-api-auth.md diff --git a/docs/content/dev/api_auth.md b/docs/content/dev/api_auth.md deleted file mode 100644 index 81095c7ec..000000000 --- a/docs/content/dev/api_auth.md +++ /dev/null @@ -1,5 +0,0 @@ -# API Authentication -## Public API -All requests to the public API require authentication using a [bearer token](https://datatracker.ietf.org/doc/html/rfc6750). - -This token can be generated diff --git a/docs/content/dev/design_docs/api_auth.md b/docs/content/dev/design_docs/api_auth.md new file mode 100644 index 000000000..34dab132c --- /dev/null +++ b/docs/content/dev/design_docs/api_auth.md @@ -0,0 +1,29 @@ +# API Authentication + +## Public API +All requests to the public API require authentication using a [bearer token](https://datatracker.ietf.org/doc/html/rfc6750). + +This token can be generated using the profile page in the frontend +(which in turn uses the private API to generate the token). + +## Private API + +The private API uses a session cookie to authenticate the user. +Sessions are handled using passport.js. + +The backend hands out a new session token after the user has successfully authenticated +using one of the supported authentication methods: + +- Username & Password (`local`) +- LDAP +- SAML +- OAuth2 +- GitLab +- GitHub +- Facebook +- Twitter +- Dropbox +- Google + +The `SessionGuard`, which is added to each (appropriate) controller method of the private API, +checks if the provided session is still valid and provides the controller method with the correct user. diff --git a/docs/content/dev/private-api-auth.md b/docs/content/dev/private-api-auth.md deleted file mode 100644 index 7db5f0087..000000000 --- a/docs/content/dev/private-api-auth.md +++ /dev/null @@ -1,18 +0,0 @@ -# Private API Auth - -## Supported kinds of authentication - -- Username & Password (`local`) -- LDAP -- SAML -- OAuth2 -- GitLab -- GitHub -- Facebook -- Twitter -- Dropbox -- Google - -## How the authentication works - -The backend is called directly from the frontend. The different routes that handle different kinds of authentication perform any kind of verification needed and then create a session cookie. This session cookie is than provided with each subsequent call to the private api by the frontend (until it expires or the user logs out). The SessionGuard, which is added to each other (appropriate) controller method of the private api, checks if the provided session is still valid and provides the controller method with the correct user. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 46295df74..c87d6bb83 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -22,6 +22,7 @@ nav: - Development: - '2.0 Development': dev/2.0.md - Design Documents: + - API Authentication: dev/design_docs/api_auth.md - Notes: dev/design_docs/notes.md - 'User Profiles & Authentication': dev/design_docs/user_profiles.md - Configuration: dev/design_docs/config.md