architecture.rst

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).

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. Our implementation is only slightly different from what you see there:

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 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, the login application also has a version of the user-settings Kratos flow.

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, a helper application that reads oauth2clients.hydra.ory.sh Kubernetes objects and synchronises them with Hydra.

An example oauth2client:

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