3SO — Shadow Single Sign-On

3SO (shadow-sso) is a Go-native OAuth 2.0 and OpenID Connect implementation, distributed both as a standalone server (ssso) with a companion CLI (ssoctl) and as a library you embed directly in your own Go services. It ships with multi-factor authentication, enterprise directory federation, and a high-performance distributed token store — the pieces most OAuth libraries leave for you to bolt on separately.

Key Features

Standards-Compliant Core

Full OAuth 2.0 (RFC 6749), OpenID Connect, PKCE (RFC 7636), Token Introspection (RFC 7662), and Token Revocation (RFC 7009) — with configurable JWT access and refresh tokens.

Six MFA Factors Built In

TOTP, HOTP, email OTP, SMS OTP (Twilio), and Firebase push notifications, backed by single-use recovery codes — no third-party MFA add-on required.

Full User Lifecycle

Self-service registration with email verification, password reset, account activation and locking, and profile/phone management out of the box.

Enterprise Federation

LDAP / Active Directory integration with attribute mapping, plus federation with external identity providers over OIDC and SAML.

Service Accounts & JWKS

Machine identities with downloadable JSON keys for server-to-server auth, plus OAuth client JWKS for public-key client authentication.

Distributed Token Store

An optional BBoltDB-backed gRPC microservice (DTS) handles ephemeral OAuth tokens with sub-millisecond operations, keeping short-lived artifacts off the primary MongoDB store.

Distributed Token Store (DTS)

OAuth artifacts like authorization codes and access tokens are short-lived and high-churn — a poor fit for a general-purpose document database under heavy load. 3SO can offload them to ssso-dts, a dedicated gRPC microservice backed by BBoltDB, while MongoDB continues to hold persistent data: user profiles, OAuth clients, and service accounts.

The result is a hybrid storage model — sub-millisecond key-value operations for ephemeral tokens, horizontal scaling of the DTS tier independent of MongoDB, and automatic expiration cleanup — deployable via Docker Compose or the included Helm chart.

3SO vs. Keycloak

An honest comparison — Keycloak is a mature, widely-deployed IdP with a much larger surface area. 3SO trades some of that breadth for a lighter deployment footprint and MFA that's built in rather than bolted on.

Capability	3SO	Keycloak
OAuth 2.0 core endpoints
PKCE support
Built-in MFA (TOTP/HOTP/SMS/push)		Via extensions
Deployment footprint	Single Go binary + MongoDB	JVM + admin console
Distributed token store	BBoltDB gRPC service (DTS)	Infinispan cache
Device Authorization Grant endpoint	Grant supported; dedicated endpoint in development
CIBA / Pushed Authorization Requests
Named FAPI 1/2 security profiles
License	MIT (open source)	Apache 2.0 (open source)

OAuth 2.0 Flows

OAuth 2.0 supports several different flows or methods for obtaining an access token. These flows are designed to cater to different use cases and security requirements.

Authorization Code Flow

The most commonly used flow for web applications with a backend server.

Implicit Flow

Used for single-page applications (SPAs) where the client cannot securely store credentials.

Client Credentials Flow

Used for server-to-server interactions that are not associated with a specific user.

Resource Owner Password

Direct authentication using username and password. Not recommended for most applications.

Device Flow

Used for devices that cannot easily input authorization codes.

Refresh Token Flow

Used to obtain new access tokens when the current one expires.

Passwordless Flow

Authentication without passwords using email or phone verification.

Multi-Factor Authentication

Enhanced security with multiple authentication factors.