add Hydra flow to SSO docs

docs/_static/custom.css

+.wy-nav-content {
+    max-width: 1200px !important;
+}

docs/architecture.rst

@@ -6,7 +6,7 @@ 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
+   and a settings screen for the Kratos settings (mostly used for password
    reset).
 
 .. _Hydra: https://www.ory.sh/hydra/docs/
@@ -38,7 +38,7 @@ 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:
+Our implementation is slightly different from what you see there:
 
 .. mermaid::
 
@@ -61,14 +61,15 @@ 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.
+self-register with a Stackspin cluster. An administrator can 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".
+to set or reset their password. We use the "Recovery ``link`` Method" described
+in the Kratos documentation.
 
 User settings
 ~~~~~~~~~~~~~
@@ -81,7 +82,31 @@ has a version of the `user-settings Kratos flow
 Authentication
 ~~~~~~~~~~~~~~
 
-TODO: Hydra authentication flow
+The following is an adaptation of the sequence diagram provided in the `Hydra
+documentation <https://www.ory.sh/docs/hydra/concepts/login>`__
+
+.. mermaid::
+
+   sequenceDiagram
+      OAuth2 Client->>Ory Hydra: Initiates OAuth2 Authorize Code or Implicit Flow
+      Ory Hydra-->>Ory Hydra: No end user session available (not authenticated)
+      opt Login Application as Login Provider
+        Ory Hydra->>Login Application: Redirects end user with login challenge
+        Login Application-->Ory Hydra: Fetches login info
+        Login Application-->>Login Application: Authenticates user w/ Kratos
+        Login Application-->Ory Hydra: Transmits login info and receives redirect url with login verifier
+        Login Application->>Ory Hydra: Redirects end user to redirect url with login verifier
+      end
+      Ory Hydra-->>Ory Hydra: First time that client asks user for permissions
+      opt Login Application as Consent Provider
+        Ory Hydra->>Login Application: Redirects end user with consent challenge
+        Login Application-->Ory Hydra: Fetches consent info (which user, what app, what scopes)
+        Note over Ory Hydra, Login Application: Not implemented: user is asked to grant app access<br />default: access granted
+        Login Application-->Ory Hydra: Transmits consent result and receives redirect url with consent verifier
+        Login Application->>Ory Hydra: Redirects to redirect url with consent verifier
+      end
+      Ory Hydra-->>Ory Hydra: Verifies grant
+      Ory Hydra->>OAuth2 Client: Transmits authorization code/token`
 
 Configuring OIDC clients
 ------------------------

docs/conf.py

@@ -58,6 +58,10 @@ html_theme = 'sphinx_rtd_theme'
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# Add custom CSS to make the screen a bit wider so you can see all our pretty
+# diagrams
+html_css_files = ['custom.css']
+
 # Readthedocs.io needs us to tell it what the index file is. This defaults to
 # 'contents'
 master_doc = 'index'

docs/development.md

@@ -153,7 +153,7 @@ data:
    flux reconcile helmrelease -n stackspin single-sign-on
    ```
 
-## Development
+## Setting up the development environment
 
 1. Setup port redirects
 
@@ -275,7 +275,7 @@ And now it is time to start the app:
 
 If this starts smoothly, you should be ready to go.
 
-## Test you setup
+## Test your setup
 
 Hydra and kratos are now configured to redirect to localhost when they receive a
 request. So to test the setup, you can go to one of your applications (for