This is an old revision of the document!
Single Sign On
This is a project driven by @samp20 to build an SSO system for all Hackspace services.
Architecture
The current proposed architecture is a Python Flask application with PostgreSQL as the backend database.
Authentication Methods
There will be a few methods supported:
- Email “magic link”
- Keyfob/card
- TOTP (e.g. Google Authenticator)
- Passkey
Password login won't be supported to begin with unless there is a strong demand for it.
Email login
Email login will send a “magic link” to your registered email address. When clicked this will log you in to the original page you were on, not the page opened when clicking the link. This will allow you to login on your phone while clicking the email on your desktop for example. This could also work on the Hackspace portal if desired.
In order to avoid mis-clicking a “magic link” triggered by a potential attacker, both the email and login page should display a code so the member can check they are clicking the correct link.
Keyfob/card login
This will be implemented by a service running only within the Hackspace network, similar to the old membership server. This service will forward that authentication to the SSO server.
Session management
Sessions will be referenced by long-lived cookies (e.g. 30 days) that get refreshed on use. The session data itself will be stored in a Session table. The currently planned data includes:
| Column | Type | Description |
|---|---|---|
| id | UUID | Session ID |
| secret | str | Rotated session cookie secret |
| member_id | FK | The member this session is for |
| created | DateTime | When the session was first created |
| last_active | DateTime | When the session was last used |
| last_email_auth | Optional[DateTime] | When an email authentication was performed |
| last_keyfob_auth | Optional[DateTime] | When a keyfob authentication was performed |
| last_totp_auth | Optional[DateTime] | When a TOTP authentication was performed |
| last_passkey_auth | Optional[DateTime] | When a passkey authentication was performed |
Authentication Level
The session's current authentication level will be calculated based on the fields in the Session table. The exact rules are still to be determined, however they will fit into the following levels:
- Plastic. The lowest authentication level when using a keyfob login.
- Bronze. Sessions that haven't authenticated in a while.
- Silver. Sessions that authenticated recently but didn't use 2fa.
- Gold. Sessions that authenticated recently with 2fa.
In OpenID terminology this is called the ACR.
Permissions model
Permissions shall be granted through OAuth scopes or other custom claims. As these claims can sometimes be application specific, a general purpose approach is proposed using Members, Roles and ClaimSets with the following relationships:
- Many-to-many between Members and Roles
- One-to-many between Roles and ClaimSets
A Role describes a high-level role a member has, for example “onboarding”. A ClaimSet describes the specific OAuth claims associated with that role. The reason for separating ClaimSets from Roles is to be able to limit a ClaimSet to a single OAuth client without requiring a member to join multiple Roles if that Role involves multiple clients.
An example ClaimSet for Grafana access to the “viewer” team may look like the following:
{
"scope": ["openid", "email"],
"groups": ["viewer"]
}
This ClaimSet would be restricted to the Grafana OAuth client in order to avoid granting the “openid” scope to other clients and inadvertently giving access to them.