Skip to content
g10fPublic

About

OpenID Connect Identity Provider with user and organisation management

Topics

Resources

Stars

7 stars

Watchers

3 watching

Forks

Repository files navigation

SSO

SSO is an OpenID Connect Identity Provider with built-in user and organisation management. It implements OAuth2 / OpenID Connect (authorization code with PKCE, implicit, hybrid, client credentials and refresh token grants), multi-factor authentication (TOTP and WebAuthn / FIDO2), and exposes its user and organisation data through a JSON-LD / Hydra REST API.

It is a Django application and is distributed as a Docker image (ghcr.io/g10f/sso) and a Helm chart.

  • Version: 5.6.0
  • Runtime: Python 3.12+ (the official image is built on Python 3.14), Django 5.2, PostgreSQL with PostGIS
  • License: BSD-style, see LICENSE

Features

  • OpenID Connect Provider with discovery (/.well-known/openid-configuration), JWKS, UserInfo, token introspection (RFC 7662) and revocation (RFC 7009) endpoints.
  • OAuth2 grants: authorization code (with PKCE, RFC 7636), implicit, hybrid, client credentials and refresh token; device authorization grant (RFC 8628) behind the feature flag SSO_DEVICE_AUTHORIZATION_GRANT.
  • Signing key rotation – RSA signing keys are created and rotated automatically (manage.py rotate_signing_keys).
  • Multi-factor authentication: TOTP (authenticator apps) and WebAuthn / FIDO2 (security keys, fingerprint, Windows Hello). MFA can be required for admins.
  • Stateless sessions stored in signed JWT cookies.
  • User & organisation management: users, organisations, admin regions, countries, country groups and associations, including geo-coordinates (PostGIS).
  • JSON-LD / Hydra API (/api/) with v1 and v2 user endpoints, organisation, region, country and application-role resources.
  • Self-registration, access requests, e-mail confirmation and account recovery.
  • Internationalisation – ships with translations for ~15 languages.
  • Theming via a pluggable SSO_THEME app.

Application layout

The Django project lives under apps/. The main packages are:

Package Responsibility
sso.accounts User model, profiles, application roles, membership
sso.organisations Organisations, admin regions, countries, associations (PostGIS)
sso.oauth2 OAuth2 / OpenID Connect provider, tokens, signing keys
sso.auth Login, TOTP and WebAuthn devices, one-time-password middleware
sso.api JSON-LD / Hydra REST API (v1 and v2)
sso.registration Self-registration and admin registration workflow
sso.access_requests Requesting and extending access to organisations
sso.emails Managed e-mail addresses and forwarding
sso.impersonate Superuser "log in as" another user
l10n Countries, currencies and localisation data

Quick start with Docker

docker compose up

This starts the SSO app (http://localhost:8000), a PostGIS database and an nginx container serving uploaded media (http://localhost:8080). The compose file creates a superuser admin / admin and loads the initial fixtures.

The values in docker-compose.yml (SECRET_KEY=123, admin/admin, SSO_USE_HTTPS=False) are for local development only. Do not use them in production.

Run locally (development server)

All manage.py commands are run from the apps/ directory:

cd apps
./manage.py runserver

With SSL (via runserver_plus from django-extensions; requirements/dev.txt contains django-extensions, Werkzeug and pyOpenSSL):

# apps/sso/settings/local_settings.py
INSTALLED_APPS = INSTALLED_APPS + ['django_extensions']
SSO_USE_HTTPS = True
SSO_DOMAIN = "localhost:8443"
cd apps
./manage.py runserver_plus localhost:8443 --cert-file ../temp/cert

Kubernetes with Helm

Helm must be installed (see the Helm documentation).

helm repo add g10f https://g10f.github.io/helm-charts
helm repo update            # if the repo was already added earlier
helm install my-sso g10f/sso
helm delete my-sso          # to uninstall

Prepare a development environment

  1. Install Python 3.14.
  2. Create a virtualenv: python3 -m venv .venv
  3. Activate it: source .venv/bin/activate
  4. Install the requirements incl. the dev and test tools: pip install -r requirements/dev.txt
  5. Install PostgreSQL and PostGIS: sudo apt install postgresql postgis
  6. Enable the required extensions on template1:
    sudo -u postgres psql -c "CREATE EXTENSION IF NOT EXISTS citext;" template1
    sudo -u postgres psql -c "CREATE EXTENSION IF NOT EXISTS postgis;" template1
  7. Create the database user and database:
    sudo -u postgres psql -c "CREATE USER sso CREATEDB PASSWORD 'sso'"
    sudo -u postgres psql -c 'CREATE DATABASE sso OWNER sso'
  8. Change into the app directory: cd apps
  9. Create the tables: ./manage.py migrate
  10. Create a superuser: ./manage.py createsuperuser
  11. Start the development server: ./manage.py runserver

Python dependencies

The direct dependencies are listed in requirements/base.in. requirements/base.txt (installed in the Docker image) and requirements/dev.txt (the same versions plus the dev and test tools) are generated from it with pip-tools, with every package pinned. After changing base.in, or to update the packages, run from the repo root:

pip-compile requirements/base.in      # add --upgrade or --upgrade-package <name>
pip-compile requirements/dev.in
pip-sync requirements/dev.txt

Running the tests

The test tooling (Selenium, locust, etc.) is part of requirements/dev.txt. For the Selenium tests you also need a matching chromedriver on your PATH (see chrome-driver.sh). Run the suite with:

cd apps
./manage.py test

To run the Selenium tests without a visible browser window (e.g. in CI or over SSH), set SELENIUM_HEADLESS=True (or 1/t). Chrome then starts in headless mode with a 1920×1080 window:

SELENIUM_HEADLESS=1 ./manage.py test

Management commands

Command Description
rotate_signing_keys Create / rotate the OAuth2 signing keys
cleartokens Delete expired authorization codes, device codes and refresh tokens
cleanupregistration Remove expired self-registration profiles
clean_access_requests Remove obsolete access requests
cleanup_users Clean up inactive / unconfirmed users
clear_unconfirmed_emails Remove unconfirmed e-mail addresses
create_permissions Create the custom permissions
add_role Add an application role
update_user_language Bulk-update the users' language
migrate_pictures Re-process stored user pictures
user_count Print the number of users (used by the Docker entrypoint)
update_location / update_timezone Recompute organisation geo data

Configuration

Configuration is done through environment variables (see apps/sso/settings/defaults.py). A local_settings.py next to the settings module is loaded if present and can override anything.

Core

Name Default Description
SECRET_KEY (random per start) Django secret key – set this in production
DEBUG False Django debug mode
ALLOWED_HOSTS '' Comma-separated additional allowed hosts
FORWARDED_ALLOW_IPS * Peers gunicorn accepts X-Forwarded-Proto/-Ssl from, which determine whether request.is_secure() is true. Pin it to the proxy address or network wherever that is known.
SSO_DOMAIN localhost:8000 Public domain of the service
SSO_USE_HTTPS True Whether the service is served over HTTPS
SSO_SITE_NAME G10F Displayed site name
ROOT_URLCONF sso.urls Root URL configuration
SSO_THEME None Optional theme app prepended to INSTALLED_APPS
SSO_STYLE css/main.min.css Stylesheet
SSO_DEFAULT_THEME auto Default UI theme (auto/light/dark)

Database, cache & Celery

Name Default Description
DATABASE_NAME sso Database name
DATABASE_USER sso Database user
DATABASE_PASSWORD sso Database password
DATABASE_HOST localhost Database host
DATABASE_CONN_MAX_AGE 60 Persistent connection lifetime (without pooling)
DATABASE_CONN_POOL False Enable psycopg connection pooling
CACHES_LOCATION None Memcached location(s), comma-separated
CELERY_BROKER_URL None Celery broker URL
CELERY_BROKER_USE_SSL True Use SSL for the Celery broker
DATA_UPLOAD_MAX_MEMORY_SIZE 2621440 Max upload size in bytes (2.5 MB)

E-mail

Name Default Description
EMAIL_HOST localhost SMTP host
EMAIL_PORT 25 SMTP port
DEFAULT_FROM_EMAIL gunnar.scherf@gmail.com Default sender
SSO_NOREPLY_EMAIL gunnar.scherf@gmail.com No-reply sender
SERVER_EMAIL root@localhost Error-report sender
EMAIL_SUBJECT_PREFIX [SSO] Subject prefix
SSO_ASYNC_EMAILS False Send e-mails asynchronously via Celery

Authentication, MFA & security

Name Default Description
REGISTRATION_OPEN False Allow public self-registration
SSO_PASSWORD_MINIMUM_LENGTH 8 Minimum password length
SESSION_COOKIE_AGE 1209600 Session lifetime in seconds (2 weeks)
SSO_LOGIN_MAX_AGE 300 Max age of the signed login step (seconds)
SSO_ADMIN_MAX_AGE 1800 Re-auth interval for admin pages (30 min)
SSO_ADMIN_ONLY_MFA False Only admins may use MFA
SSO_ADMIN_MFA_REQUIRED False Require MFA for admins
SSO_TOTP_TOLERANCE 2 Accepted TOTP time-step window
SSO_WEBAUTHN_VERSION FIDO_2_0 WebAuthn version (U2F_V2 / FIDO_2_0)
SSO_WEBAUTHN_USER_VERIFICATION discouraged WebAuthn user verification requirement
SSO_WEBAUTHN_AUTHENTICATOR_ATTACHMENT '' WebAuthn authenticator attachment
SSO_WEBAUTHN_EXTENSIONS False Enable WebAuthn extensions
SSO_WEBAUTHN_CREDPROPS False Enable WebAuthn credProps extension
SSO_REFRESH_TOKEN_AGE 7776000 Refresh token lifetime (90 days)
SSO_THROTTLING_DURATION 30 Login throttling window (seconds)
SSO_THROTTLING_MAX_CALLS 5 Max login attempts per window
SSO_THROTTLE_PROXY_COUNT (unset) Number of trusted reverse proxies in front of the app. Used to derive the real client IP for throttling so X-Forwarded-For cannot be spoofed to get a fresh counter per request. Set it to match your proxy chain (e.g. 1 for a single nginx). Must be exact: too low lets clients behind one proxy share a counter, too high lets an attacker spoof the client IP. Unset falls back to ipware's default parsing.
SSO_THROTTLE_PROXY_DEBUG False Temporary diagnostic aid for choosing SSO_THROTTLE_PROXY_COUNT. When enabled, the throttle decorator logs the raw X-Forwarded-For, REMOTE_ADDR and the client IP ipware resolves for each candidate proxy count. Call a throttled endpoint from outside without sending your own X-Forwarded-For; the smallest proxy count whose resolved IP is your real public IP is the value to configure. Turn off in production.
SSO_LEGACY_USERINFO_ENDPOINT False Temporary, until all clients are adapted: when enabled, userinfo_endpoint in the OpenID Connect discovery document points to the v2 users API (/api/v2/users/me/, includes organisations) instead of the standard userinfo endpoint.
SSO_DEVICE_AUTHORIZATION_GRANT False Feature flag for the OAuth2 Device Authorization Grant (RFC 8628) for clients without a browser or keyboard (TVs, CLIs). In addition, each client must be allowed to use it ("device authorization grant" in the client admin, public native clients only). Work in progress: when disabled, the device_authorization and device endpoints return 404 and the token endpoint rejects the grant type.
SSO_RECAPTCHA_ENABLED True Enable reCAPTCHA on registration
RECAPTCHA_PUBLIC_KEY / RECAPTCHA_PRIVATE_KEY (Google test keys) reCAPTCHA keys – set your own
SSO_2FA_HELP_URL '' External 2FA help page

Media, storage & misc

Name Default Description
STATIC_ROOT ../htdocs/static Static files root
MEDIA_ROOT ../htdocs/media Uploaded media root
STATIC_URL /static/ Static URL prefix
MEDIA_URL /media/ Media URL prefix
SSO_USER_MAX_PICTURE_SIZE 1048576 Max user picture size in bytes (1 MB)
SSO_USER_PICTURE_REQUIRED False Require a profile picture
SSO_GOOGLE_GEO_API_KEY None Google Geocoding API key
SSO_ORGANISATION_EMAIL_DOMAIN '' Domain for managed organisation e-mails
SSO_ABOUT https://g10f.de/ "About" redirect target
SSO_DATA_PROTECTION_URI None Privacy policy URL
SSO_ENABLE_PLAUSIBLE False Enable Plausible analytics
ANALYTICS_CODE '' Analytics snippet
LOGGING_LEVEL_ROOT / LOGGING_LEVEL_SSO / LOGGING_LEVEL_DJANGO / LOGGING_LEVEL_DB INFO Log levels

API

The API entry point is /api/ and follows the JSON-LD / Hydra conventions. Highlights:

  • GET /api/v2/users/, GET /api/v2/users/me/, GET/PUT/DELETE /api/v2/users/{uuid}/
  • GET /api/v2/organisations/, /api/v2/regions/, /api/v2/countries/, /api/v2/country_groups/, /api/v2/associations/
  • GET /api/v2/apps/ and per-user application roles under /api/v2/users/{uuid}/apps/{app_uuid}/roles/
  • OpenID Connect endpoints under /oauth2/ (authorize, token, userinfo, jwks, introspect, revoke) plus discovery at /.well-known/openid-configuration.

Release

A release is a git tag X.Y.Z. It is created with git release (a small release script):

git release patch        # or minor, major, X.Y.Z

It writes the new version to apps/sso/__init__.py, commits it as release X.Y.Z, creates the tag and pushes both. The CI checks that the tag matches __version__, builds the image ghcr.io/g10f/sso:X.Y.Z (and latest) natively for amd64 and arm64 and starts the deploy: if the secret DEPLOY_WORKFLOW (owner/repo/workflow-file) is set, it starts that workflow with the inputs image and version, using the secret DEPLOY_TOKEN. Without it, e.g. in a fork, nothing is deployed. A push without a tag does not start the CI.

Afterwards git release runs ./post-release.sh X.Y.Z, which sets the new version in the checked out ../sso-*-theme repositories (not committed). Commit them once the CI has built the image.

Changelog

The entries below list the notable changes per minor release. See the git history for the full list of patch releases.

5.6 (current, 5.6.0)

  • OAuth2 Device Authorization Grant (RFC 8628) for clients without a browser or keyboard (TVs, CLIs), contributed in PR #32. Disabled by default: enable it with SSO_DEVICE_AUTHORIZATION_GRANT and per client with "device authorization grant" (admin and self-service, public native clients only). Expired device codes are deleted by cleartokens.
  • the format of the client_id a client sends (with or without dashes) is recorded per client and shown in the client admin, to find the clients that use the dashed notation
  • database migrations oauth2.0008_client_client_id_format and oauth2.0009_devicecode (new client fields and the device code table): before a rollback to 5.5 run manage.py migrate oauth2 0007

5.5 (5.5.1)

  • oauthlib 4.0.0
  • an unknown or inactive client_id now returns the error code invalid_client (previously "error": null); the token endpoint answers with HTTP 401 instead of 400, the same as for a wrong client secret
  • a client_id sent in another notation of the same UUID (e.g. with dashes) is still accepted, oauthlib 4 alone would reject it with server_error
  • 5.5.1: the aud claim of the id_token is again the client_id as sent by the client; 5.5.0 removed the dashes, so clients configured with a dashed client_id (e.g. kubelogin) rejected the id_token
  • a PKCE code_verifier or code_challenge with non-ASCII characters is rejected with invalid_grant instead of failing with HTTP 500

5.4

  • Django 5.2.18
  • accepting an organisation change extends the account validity: for organisations with an active validation period, valid_until is set to today plus SSO_VALIDATION_PERIOD_DAYS (365 days by default), because the admin of the new organisation has just verified the user
  • faster user list: the users list API counts distinct primary keys for pagination, and the filters of the user list are cached across workers and no longer load all organisations on every request
  • unknown client_id, invalid auth tokens, an invalid id_token_hint on logout and tampered WebAuthn state now return a proper error / redirect instead of HTTP 500
  • client and data conditions (e.g. client_credentials without a user) are logged at warning instead of error level, so they no longer trigger admin error e-mails
  • SSO_LEGACY_USERINFO_ENDPOINT to point the discovery userinfo_endpoint at the v2 users API while clients are migrated
  • SSO_THROTTLE_PROXY_COUNT documented, optional SSO_THROTTLE_PROXY_DEBUG logging
  • X-Content-Type-Options: nosniff and a Referrer-Policy header via Django's SecurityMiddleware
  • FORWARDED_ALLOW_IPS configurable; unused gunicorn config removed
  • security fix: the chained_filter endpoint is restricted to the chained fields, closing an unauthenticated data-exposure hole
  • security fix: refresh tokens are bound to the client they were issued to, and authorization codes expire after SSO_AUTHORIZATION_CODE_AGE
  • security fix: stored XSS in the admin through mark_safe on user-supplied data
  • security fix: the login throttle can no longer be bypassed with a spoofed X-Forwarded-For or a random query string, and accounts behind a shared IP no longer throttle each other
  • security fix: an OAuth2 error raised before the request was validated is no longer reported to an unregistered redirect_uri (open redirect)
  • standard-conform OpenID Connect UserInfo endpoint
  • is_primary flag for organisation membership when a user belongs to more than one
  • Instagram page for organisations (Google+ removed)

5.3

  • Django 5.2 LTS maintenance (up to 5.2.17), Python 3.14 base image
  • security hardening: constant-time secret comparison, client_secret_post support advertised in the discovery metadata, removed padding from the JWS header
  • resolved Django 6.0 deprecation warnings

5.1 – 5.2

  • oauthlib 3.3.1, Bootstrap 5.3.7, fido2 2.0
  • "Implicit flow" selectable in the client self-service, client state field raised to 4096 characters
  • info logging for TOTP

5.0

  • Django 5.2 compatibility

4.6 – 4.8

  • Django 5.0 and 5.1 compatibility
  • list of available apps added to the API

4.0 – 4.5

  • Django 4.0 – 4.2 compatibility, psycopg 3, Python 3.12
  • access-request workflow extended (app id / message, expiry cleanup command, e-mail on denial)
  • django-reversion integration and superuser impersonation
  • new (invisible) reCAPTCHA, get_random_secret_key fallback for SECRET_KEY
  • configurable TOTP tolerance, external 2FA help page, WebAuthn user-verification setting and default theme configurable via environment

3.3.23

  • fido2 version 1.1
  • switched to Fido2 only
  • fixed iOS compatibility

3.2.0

  • support for WebAuthn, allows usb-keys, fingerprint and windows hello

3.1.4

  • Docker support

3.0.1

  • django 3.1 compatibility
  • automatically create and change the signature keys with ./manage.py rotate_signing_keys
  • new settings with the following defaults:
    • SSO_ACCESS_TOKEN_AGE = 60 * 60 (1 hour)
    • SSO_ID_TOKEN_AGE = 60 * 5 (5 minutes)
    • SSO_SIGNING_KEYS_VALIDITY_PERIOD = 60 * 60 * 24 * 30 (30 days)

2.1.0

  • django 2.2 compatibility
  • oauthlib >= 3
  • new UserNote model
  • application specific scopes to restrict the clients which have access to user application roles
  • key/value table to store arbitrary user attributes (UI/forms overridable via settings)
  • new select box for administration of user application roles
  • support post_logout_redirect_uri of the OIDC spec

1.3.1

  • user organisations are stored through an explicit membership class/table

1.3.0

  • PKCE support

1.2.1

  • Django 2.0 compatibility

1.2.0

  • organisation data management

1.1.0

  • JSON-LD / Hydra API

1.0.0

  • OAuth2 and OpenID Connect support

About

OpenID Connect Identity Provider with user and organisation management

Topics

Resources

Stars

7 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages