Newer
Older
The single sign-on system consists of a few components:
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. `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/
Overview
--------
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
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
interfaces 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 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 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" described
in the Kratos documentation.
User settings
~~~~~~~~~~~~~
Although users can change their settings through the `Dashboard application
<https://open.greenhost.net/stackspin/dashboard>`__, the login application also
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
~~~~~~~~~~~~~~
The following is an adaptation of the sequence diagram provided in the `Hydra
documentation <https://www.ory.sh/docs/hydra/concepts/login>`__
.. mermaid::
sequenceDiagram
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
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->>OAuth 2 Client: Transmits authorization code/token`
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
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