diff --git a/docs/architecture.rst b/docs/architecture.rst
index 714533486372c370ec6afe098f844442626b07fd..3d6cf1bfcf1fef96a355e43fe1294265dba0cde2 100644
--- a/docs/architecture.rst
+++ b/docs/architecture.rst
@@ -1,25 +1,25 @@
Architecture
============
-The single sign on system consists of a few components:
+The single sign-on system consists of a few components:
-1. The *Oauth2* and *OpenID Connect (OIDC) provider*, `Hydra`_
+1. The *OAuth 2* 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 Kratos settings (mostly used for password
- reset).
+3. The Login application which serves as a login panel, consent application and
+ a settings screen for the Kratos settings. `The login application code can be
+ found here
+ <https://open.greenhost.net/stackspin/single-sign-on/-/tree/main/login>`__
.. _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:
+The single sign-on system is a combination of applications that serve as a
+central user database and authenticates them to other applications. 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
@@ -27,7 +27,7 @@ user-related tasks, such as:
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.
+interfaces for logging in, resetting the password and setting some user data.
Flows
@@ -76,8 +76,10 @@ 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
+implements the `user-settings Kratos flow
<https://www.ory.sh/kratos/docs/next/self-service/flows/user-settings/>`__.
+Users that receive a password recovery link use this flow to reset their
+passwords. It also allows them to change their username and full name.
Authentication
~~~~~~~~~~~~~~
@@ -88,7 +90,7 @@ documentation <https://www.ory.sh/docs/hydra/concepts/login>`__
.. mermaid::
sequenceDiagram
- OAuth2 Client->>Ory Hydra: Initiates OAuth2 Authorize Code or Implicit Flow
+ OAuth 2 Client->>Ory Hydra: Initiates OAuth 2 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
@@ -106,7 +108,7 @@ documentation <https://www.ory.sh/docs/hydra/concepts/login>`__
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`
+ Ory Hydra->>OAuth 2 Client: Transmits authorization code/token`
Configuring OIDC clients
------------------------
diff --git a/docs/conf.py b/docs/conf.py
index 610678eb27428224cbdc44c495a68071bbf879e3..a7639782363477146cd57e88115e33acdd73092a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -65,3 +65,13 @@ html_css_files = ['custom.css']
# Readthedocs.io needs us to tell it what the index file is. This defaults to
# 'contents'
master_doc = 'index'
+
+# https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html
+#
+# Suppress autosectionlabel extension warnings about duplicate labels, i.e.
+#
+# docs/usage.rst:105: WARNING: duplicate label wordpress, other instance in docs/testing.rst
+#
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 5
diff --git a/docs/helmchart.md b/docs/helmchart.md
index f74f35d66752224acc071a529b113d41f4e5cfc0..28ad7b7835f6ac86b3bfdbb205f3e7ace3d83354 100644
--- a/docs/helmchart.md
+++ b/docs/helmchart.md
@@ -35,7 +35,7 @@ This table lists the variables you are most likely to change. Take a look at the
| Parameter | Description | Default |
|--------------------------------------|---------------------------------------------------------|-----------------------------------------|
-| `singleSignOnHost` | **FQDN of the openID Connect / oAuth2 server** | **sso.stackspin.example.net** |
+| `singleSignOnHost` | **FQDN of the openID Connect / OAuth 2 server** | **sso.stackspin.example.net** |
| `login.image.repository` | Name of image repository to be used for login provider | open.greenhost.net:4567/stackspin/single-sign-on/login |
| `login.image.tag` | Release version of login provider image | main |
| `login.user` | Username of user to create during installation | admin@example.com |
@@ -57,7 +57,7 @@ This table lists the variables you are most likely to change. Take a look at the
| `kratos.kratos.secrets.session` | **Array of strings for session secrets** | See values.yaml |
| `kratos.kratos.courier.smtp.connection_uri` | **Config of SMTP server** | **smtps://username:password@smtp.example.net:456/** |
| `kratos.kratos.courier.smtp.from_address` | **From email address** | **no-reply@example.net** |
-| `hydra.hydra.config.urls.self.issuer`| **Base URI of the oAuth server** | **https://sso.stackspin.example.net** |
+| `hydra.hydra.config.urls.self.issuer`| **Base URI of the OAuth server** | **https://sso.stackspin.example.net** |
| `hydra.hydra.config.urls.login` | **URI that will be used for the login page** | **https://sso.stackspin.example.net/login** |
| `hydra.hydra.config.urls.consent` | **URI that will be used for permission checks** | **https://sso.stackspin.example.net/consent** |
| `hydra.hydra.config.dsn` | **Database endpoint for Hydra** | postgres://hydra:hydra@single-sign-on-postgresql:5432/hydra |
@@ -107,7 +107,7 @@ Commands:
### Registering clients
-To use OpenID Connect or oAuth you need to set up an oAuth Client for every
+To use OpenID Connect or OAuth you need to set up an OAuth Client for every
application that needs to authenticate it's users. Setting up a client happens
in two steps: registering the client with `single-sign-on`, and configuring the
client application.
@@ -126,7 +126,7 @@ metadata:
namespace: default
spec:
# Specifies the methods the client can use to retrieve access tokens from the
- # oAuth server
+ # OAuth server
grantTypes:
- authorization_code
- refresh_token
@@ -146,7 +146,7 @@ spec:
# process is completed
redirectUris:
- https://dashboard.${domain}/_oauth/oidc
- # Set the method that the oAUth client uses to authenticate agains the oAuth
+ # Set the method that the oAUth client uses to authenticate agains the OAuth
# server i.e. to retrieve tokens or userinfo
tokenEndpointAuthMethod: client_secret_post
```
diff --git a/docs/index.rst b/docs/index.rst
index 01ce552ff8e4beded04b3ef8a64210ef83dece16..be1cc977e6478a7853b2b3fb94c881827649d9bc 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,7 +6,7 @@
Welcome to single-sign-on's documentation!
==========================================
-This project provides a single sign on solution based on `Hydra`_ and `Kratos`_.
+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/