Keystack Auth

OAuth 2.0 provider and user management service

Features

• OAuth 2.0 provider. Endpoints:
  • /authorize
  • /api/oauth/token
  • /api/oauth/token_info
• OpenID Connect compatible /api/oauth/userinfo endpoint
• User management
• OAuth client management
• JWT key management (public JWKS endpoint /api/keys)
• API spec in OpenAPI format
• Dockerfile and GitHub Actions CI pipeline

Configuration

Backend environment variables

• BIND_ADDRESS (optional) - server bind address (e.g. 0.0.0.0:8080, default value is 127.0.0.1:8080)
• DATABASE_URL (required) - database connection string (e.g. postgres://user:password@host:port/db)
• KEYS_SECRET (required) - arbitrary string which is used to encode keys stored in database. Keep this value same on all backend instances, change of this value after installation invalidates all keys
• BCRYPT_COST (optional) - integer value greater or equal to 4, if missing uses bcrypt Rust crate defaults (currently 12). Greater values cause longer password hashing/verification, but increase password hash brute-force protection in case of database data leakage
• DEFAULT_USER_EMAIL (optional) - if set, admin user will be initialized (if missing) on backend startup with provided email. Random password will be generated, stored in plain text in database and printed to logs. You HAVE TO change this password as soon as possible to store it in secure manner (frontend will show password change dialog on every page load when current user password is unencrypted). Intended ONLY for initial service setup.
• DEFAULT_KEY_ALGORITHM (optional) - defaults to RS256. Used to chose JWT key generation when no key is available (on startup or if all existing keys were revoked). You can choose any supported key algorithm when generating keys via Admin UI.
• OAUTH_CODE_TTL - defaults to 60. Expire time in seconds for OAuth 2.0 authorization codes issued by the service. Should be enough for user's browser to redirect back to the app and to call /api/oauth/token endpoint.
• SELF_OAUTH_CLIENT_ID (optional) - OAuth client id representing Keystack itself. Will be created if missing on startup. Please note that you need to set redirect uris in order to make it fully functional. Defaults to keystack.
• SELF_OAUTH_CLIENT_NAME (optional) - OAuth client name representing Keystack itself (see SELF_OAUTH_CLIENT_ID). Defaults to Keystack.

Tech stack

Backend

• Rust
• Axum
• Sqlx
• Postgres

Frontend

• TypeScript
• React
• React Router
• @hey-api/openapi-ts

Tips and tricks

Install frontend dependencies

npm install -g pnpm # If missing
pnpm install

Build frontend

pnpm openapi-ts # First time or if OpenAPI spec was changed
pnpm build

Format code

cargo fmt
pnpm format

Use shipped git hooks

git config --local core.hooksPath .githooks/

Pre-commit hook runs code formatting utilities before each commit

AI agent instructions

AI agents can find project instructions in AGENTS.md file