Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
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