architecture.rst

Architecture

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

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. Our implementation is 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 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 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, the login application also implements the user-settings Kratos flow. 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

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