auth.cr

Crystal/spider-gazelle replacement for the legacy Ruby/Rails auth service. Route-for-route compatible with the existing wire protocol so clients can flip over without changes.

What it does

• Local password sign-in — POST /auth/signin (bcrypt verify).
• OAuth2 client flows — /auth/oauth2, /auth/oauth2/callback — per-tenant provider configs loaded from the oauth_strat table via spider-gazelle/multi_auth (and its custom GenericOAuth2 provider).
• SAML SP — /auth/saml, /auth/saml/callback — backed by spider-gazelle/multi_auth_saml reading the adfs_strat table.
• OAuth2 / OIDC server — /auth/authorize, /auth/token, /auth/revoke, /auth/userinfo, /.well-known/openid-configuration. Backed by place-labs/authly. JWTs are RS256 with the legacy u: {n, e, p, r} claim block + aud=authority.domain so downstream PlaceOS services keep validating tokens issued before cutover.
• API key auth — X-API-Key header (HMAC-SHA512 secret format {id}.{secret}).
• Login event publisher — fires {user_id, provider} JSON on the placeos/auth/login Redis channel after every successful login.

What's intentionally out of scope

Dropped	Why
OAuth2 password grant	Deprecated by OAuth 2.1; security risk. Token endpoint returns unsupported_grant_type. Local logins still work via the cookie session on POST /auth/signin.
LDAP	All current tenants have migrated off.
POST /auth/signup	Unused in production. OAuth users are auto-created inline in the callback when no UserAuthLookup exists.
OmniAuth :developer strategy	Rails-dev convenience only.

Routes

Method	Path	Purpose
GET	/auth/healthz	Liveness
GET	/auth/authority	Authority info + session/token flags (?health= makes it a probe)
POST	/auth/signin	Local password login
GET	/auth/logout	Session teardown + Bearer revoke + logged_out_at stamp
GET	/auth/login	Inline login dispatcher
GET	/auth/failure	OAuth / SAML failure landing page
GET	/auth/oauth2	Kickoff OAuth2 client flow
GET/POST	/auth/oauth2/callback[/:strategy]	Consume OAuth2 callback
GET	/auth/saml	Kickoff SAML SP flow
GET/POST	/auth/saml/callback[/:strategy]	Consume SAMLResponse
GET	/auth/authorize	OAuth2 authorization endpoint (code flow)
POST	/auth/token	OAuth2 token endpoint (authorization_code, client_credentials, refresh_token)
POST	/auth/revoke	RFC 7009 token revocation
GET	/auth/userinfo	OIDC userinfo (Bearer-gated)
GET	/.well-known/openid-configuration	OIDC discovery

Environment

Required in production

Var	Purpose
JWT_SECRET	Base64-encoded RSA private PEM. Signs every issued JWT (RS256). Public key derived. Falls back to a hardcoded dev key if unset — DO NOT ship that to production.
COOKIE_SESSION_SECRET	≥32 bytes. Encrypts/signs the session cookie. Dev fallback generates an ephemeral key per boot.
PG_DATABASE_URL or PG_HOST / PG_PORT / PG_DB / PG_USER / PG_PASSWORD	PostgreSQL connection.
REDIS_URL	Used to publish login events. If unset, LoginEvents.publish is a no-op (logged at warn).

Optional / tunable

Var	Default	Purpose
SG_ENV	development	production flips secure-cookie + production logging.
JWT_ISSUER	POS	iss claim on issued JWTs. Match the legacy Ruby value or services that pin issuer will reject.
SESSION_TIMEOUT_MINUTES	1440	Session-cookie max age. Per-authority override available via authority.internals["session_timeout"].
LOGIN_EVENTS_CHANNEL	placeos/auth/login	Redis pub/sub channel for login events.
PLACE_URI	(unset)	Base URL used when a legacy X-API-Key validation needs to round-trip to the core engine.

Run

Locally (against a running Postgres + Redis)

shards install
crystal run src/app.cr -- -b 0.0.0.0 -p 3000

Useful flags

./placeos-auth --routes        # dump the route table
./placeos-auth --docs          # OpenAPI YAML on stdout
./placeos-auth --env           # list every ENV var the app touched
./placeos-auth --version
./placeos-auth -c http://127.0.0.1:3000/auth/healthz   # health-check (exit 0 on 2xx-4xx)

Container

docker build -t placeos/auth .
docker run --rm -p 3000:3000 -e JWT_SECRET=... -e COOKIE_SESSION_SECRET=... placeos/auth

The HEALTHCHECK probes /auth/healthz.

Test

./test spins up Postgres + Redis + a migrator container (clones placeos/models@<branch> and runs micrate up) and runs the spec suite end-to-end.

./test                                    # full suite
./test spec/controllers/oauth_spec.cr     # one file

Iterating on placeos-models migrations

The migrator's git clone is Docker-cached. After pushing new migrations to the placeos/models branch this project points at:

docker compose build --no-cache migrator
./test

Working on the codebase

• Code style: crystal tool format && ./bin/ameba — both must be clean before committing. CI rejects either.
• Plans + lessons live in tasks/todo.md and tasks/lessons.md (please update both as you go — lessons.md has caught at least five upstream library quirks already).
• PLAN.md is the high-level phase map.

Migration from the Ruby service

Aspect	Ruby	auth.cr
Session cookie	_coauth_session at path /auth, Rails AES encryption	Same name + path, but action-controller MessageEncryptor wire format. Users are forced to re-sign-in at cutover (acceptable for an auth-service rotation).
JWT issuer (iss)	POS	POS
JWT shape	{iss, iat, exp, jti, aud, scope, sub, u:{n,e,p,r}}	Same
Bcrypt password digest	Stored in user.password_digest	Same (placeos-models reused).
OmniAuth :generic_oauth	DB-driven oauth_strat	multi_auth factory under the oauth2 provider name; same oauth_strat rows.
OmniAuth :generic_adfs	DB-driven adfs_strat	multi_auth_saml factory under the saml provider name; same adfs_strat rows.
OAuth password grant	Allowed	Rejected with unsupported_grant_type.
POST /auth/signup	Manual signup endpoint	Removed; OAuth users are auto-created inline in the callback.
Redis login channel	placeos/auth/login	Same.
LDAP	Supported	Dropped.

Cutover steps

1. Ensure JWT_SECRET matches the Ruby deployment — downstream services validate by signature, so a key rotation breaks them.
2. Roll out placeos-models with the oauth_tokens migration first (or use the auth-replacement branch).
3. Set COOKIE_SESSION_SECRET to a real ≥32-byte value. Existing _coauth_session cookies will be invalid — users re-sign-in.
4. Switch the auth service container image to this build. The route table is wire-compatible.
5. Watch the placeos/auth/login Redis channel + /auth/healthz for regressions.