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

add documentation on a few Kratos flows

parent 026d2708
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:
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
......@@ -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 -------------------------------------------------
......
......@@ -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
......@@ -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
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