Single sign-on Architecture

The single sign-on system consists of a few components:

The OAuth 2 and OpenID Connect (OIDC) provider, Hydra
The Identity provider, Kratos
The Login application which serves as a login panel, consent application and a settings screen for the Kratos settings. The login application code is part of the Dashboard Backend repository

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:

Setting your name and username
The whole password reset flow
The login form
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:

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

        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`

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