add documentation on a few Kratos flows

docs/architecture.rst

+Architecture
+============
+
+The single sign on system consists of a few components:
+
+1. The *Oauth2* and *OpenID Connect (OIDC) provider*, `Hydra`_
+2. The *Identity provider*, `Kratos`_
+3. The `Login application`_ which serves as a login panel, consent application
+   and a settings screen for the Hydra settings (mostly used for password
+   reset).
+
+.. _Hydra: https://www.ory.sh/hydra/docs/
+.. _Kratos: https://www.ory.sh/kratos/docs/
+.. _Login application: https://open.greenhost.net/stackspin/single-sign-on/-/tree/main/login
+
+Overview
+--------
+
+The single sign on application as a whole stores your users and helps them
+authenticate to applications. Its users are stored inside Kratos's database.
+Kratos also serves an API that helps us generate interfaces for many
+user-related tasks, such as:
+
+1. Setting your name and username
+2. The whole password reset flow
+3. The login form
+4. 2FA (not implemented in the login application yet)
+
+The Login application is mostly a front-end that uses the Kratos API to generate
+the views for logging in, resetting the password and setting some user data.
+
+
+Flows
+-----
+
+Logging in
+~~~~~~~~~~
+
+The Kratos login flow is documented `in the Kratos documentation
+<https://www.ory.sh/kratos/docs/self-service/flows/user-login#login-for-client-side-ajax-browser-clients>`__.
+Our implementation is only slightly different from what you see there:
+
+.. mermaid::
+
+   sequenceDiagram
+      participant B as Browser
+      participant L as Login application
+      participant K as Kratos
+
+      B->>L: User clicks "Login with Stackspin"
+      L->L: Check if cookie for current session exists
+      alt Cookie does not exist
+        L-->>+K: Start `/self-service/login/browser` flow
+        K-->>-B: At end of login flow, sets session cookie
+      else Cookie exists
+        L->>B: Shows "you are already logged in" screen
+        B->B: If cookie has `flow_state == auth`, redirect to Cookie's `auth_url` and remove `flow_state`.
+      end
+
+User creation
+~~~~~~~~~~~~~
+
+We have not implemented Kratos's *Registration* flow, because users cannot
+self-register with a Stackspin cluster. An administrator always needs to make
+new users using the Dashboard application. When a user is created, an email
+address always needs to be provided.
+
+Once a user has been created, they can start the `Account Recovery and Password
+Reset flow
+<https://www.ory.sh/kratos/docs/self-service/flows/account-recovery>`__ in order
+to set or reset their password. We use the "Recovery ``link`` Method".
+
+User settings
+~~~~~~~~~~~~~
+
+Although users can change their settings through the `Dashboard application
+<https://open.greenhost.net/stackspin/dashboard>`__, the login application also
+has a version of the `user-settings Kratos flow
+<https://www.ory.sh/kratos/docs/next/self-service/flows/user-settings/>`__.
+
+Authentication
+~~~~~~~~~~~~~~
+
+TODO: Hydra authentication flow
+
+Configuring OIDC clients
+------------------------
+
+If you have installed the SSO system using the Helm chart, following this
+documentation, these are the settings that you usually need to for setting up
+new OIDC clients:
+
+- OAuth 2 server URL: ``https://sso.stackspin.example.org``
+- OAuth 2 Auth Endpoint: ``https://sso.stackspin.example.org/oauth2/auth``
+- OAuth 2 Userinfo endpoint: ``https://sso.stackspin.example.org/userinfo``
+- OAuth 2 Token endpoint: ``https://sso.stackspin.example.org/oauth2/token``
+
+In addition you'll need to add the client to Hydra. This happens with `Hydra
+Maester
+<https://www.ory.sh/hydra/docs/guides/kubernetes-helm-chart/#hydra-maester>`__,
+a helper application that reads ``oauth2clients.hydra.ory.sh`` Kubernetes
+objects and synchronises them with Hydra.
+
+An example ``oauth2client``:
+
+.. code:: yaml
+
+   apiVersion: hydra.ory.sh/v1alpha1
+   kind: OAuth2Client
+   metadata:
+     name: dashboard-oauth-client
+   spec:
+     grantTypes:
+       - authorization_code
+       - refresh_token
+       - client_credentials
+       - implicit
+     hydraAdmin: {}
+     metadata: null
+     redirectUris:
+     - https://dashboard.stackspin.example.org/login-callback
+     responseTypes:
+     - id_token
+     - code
+     scope: openid profile email stackspin_roles
+     secretName: stackspin-dashboard-oauth-variables
+     tokenEndpointAuthMethod: client_secret_post
+

docs/conf.py

@@ -32,6 +32,8 @@ with open('../VERSION') as version_file:
 # ones.
 extensions = [
     'recommonmark',
+    'sphinxcontrib.mermaid',
+    'sphinx.ext.autosectionlabel',
     'sphinx_markdown_tables',
 ]
 
@@ -41,7 +43,7 @@ templates_path = ['_templates']
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv']
 
 
 # -- Options for HTML output -------------------------------------------------

docs/index.rst

@@ -6,14 +6,17 @@
 Welcome to single-sign-on's documentation!
 ==========================================
 
-This project provides a single sign on solution based on
-[hydra](https://github.com/ory/hydra), [kratos](https://github.com/ory/kratos) 
-and in combination with a [login panel](https://open.greenhost.net/stackspin/single-sign-on).
+This project provides a single sign on solution based on `Hydra`_ and `Kratos`_.
+It also serves a small login and settings application.
+
+.. _Hydra: https://www.ory.sh/hydra/docs/
+.. _Kratos: https://www.ory.sh/kratos/docs/
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   architecture
    helmchart
    development
 

docs/requirements.txt

@@ -2,3 +2,4 @@ sphinx==4.4.0
 sphinx_rtd_theme==1.0.0
 recommonmark==0.7.1
 sphinx-markdown-tables==0.0.15
+sphinxcontrib-mermaid==0.7.1