Skip to content
Snippets Groups Projects
Verified Commit 71504834 authored by Maarten de Waard's avatar Maarten de Waard :angel:
Browse files

several improvements to documentation

parent 09d5caaf
Branches master
No related tags found
1 merge request!91Resolve "Document SSO design and implementation in OAS docs"
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
------------------------
......
......@@ -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
......@@ -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
```
......
......@@ -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/
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment