Installation

This guide covers the detailed installation and configuration process for Authrim from the source repository. For a guided deployment, use the Setup Wizard.

System Requirements

Requirement	Minimum Version
Node.js	>= 22.0.0
pnpm	>= 9.0.0
Git	Latest
Cloudflare Account	Free tier or higher

Installation Steps

1. Clone and Install

# Clone the repository
git clone https://github.com/sgrastar/authrim.git
cd authrim

# Install dependencies
pnpm install

# Login to Cloudflare
wrangler login

2. Generate Cryptographic Keys

Generate the RSA keys used for JWT signing:

./scripts/setup-keys.sh

This creates:

File	Purpose
.keys/private.pem	RSA private key for JWT signing
.keys/public.jwk.json	Public key in JWK format
.keys/metadata.json	Key ID and metadata

3. Configure Environment Variables

# Create .dev.vars with environment variables
./scripts/setup-local-vars.sh

# Generate wrangler.toml for local development
./scripts/setup-local-wrangler.sh

4. Set Up Cloudflare Resources

KV Namespaces

./scripts/setup-kv.sh --env=dev

This creates environment-scoped KV namespaces for cache and configuration data. Current bindings include:

• CLIENTS_CACHE - OAuth client metadata cache
• INITIAL_ACCESS_TOKENS - Dynamic Client Registration initial access tokens
• SETTINGS - System settings
• REBAC_CACHE - RBAC/ReBAC claims cache
• USER_CACHE - User metadata cache
• AUTHRIM_CONFIG - Generated deployment configuration
• TENANT_RUNTIME_REGISTRY - Tenant runtime registry snapshots
• STATE_STORE - Compatibility/runtime state storage
• CONSENT_CACHE - Consent cache

Authorization codes, refresh token rotation, DPoP JTI replay checks, PAR request state, device codes, CIBA requests, SAML state, and rate limiting are handled by Durable Objects rather than KV.

D1 Database

./scripts/setup-d1.sh --env=dev

Creates the deployment-level D1 databases:

Binding	Database name pattern	Purpose
DB	{env}-authrim-core-db	Core OAuth/OIDC, policy, consent, passkey, custom-claim, and transient auth data
DB_PII	{env}-authrim-pii-db	Sensitive identity values, subject identifiers, linked identity records, PII tombstones, and PII audit data
DB_ADMIN	{env}-authrim-admin-db	Admin users, admin RBAC, runtime profiles, tenant database registry, audit/logging control data

Fresh installs apply SQL from:

• migrations/001_core_foundation.sql through the latest core migration
• migrations/pii/001_pii_schema.sql
• migrations/admin/001_admin_users_rbac_security.sql through the latest admin migration

Authrim uses runtime storage profiles to route logical sources and storage slices. The default profile is builtin:storage:shared-d1; larger or regulated deployments can use builtin:storage:tenant-d1 with generated tenant D1 bindings, or external database profiles where supported.

Durable Objects

./scripts/setup-durable-objects.sh

Deploys Durable Objects from @authrim/ar-lib-core. Key bindings include:

• SESSION_STORE / SESSION_CLIENT_STORE - session state and client session mirrors
• KEY_MANAGER - cryptographic key management
• AUTH_CODE_STORE - OAuth authorization code storage
• REFRESH_TOKEN_ROTATOR - refresh token rotation
• CHALLENGE_STORE - passkey and one-time challenge state
• RATE_LIMITER - atomic rate limiting
• PAR_REQUEST_STORE - PAR request URI state
• DPOP_JTI_STORE - DPoP replay protection
• DEVICE_CODE_STORE / CIBA_REQUEST_STORE - Device Flow and CIBA state
• TOKEN_REVOCATION_STORE - token revocation state
• SAML_REQUEST_STORE / SAML_AGGREGATE_METADATA_STORE - SAML request and metadata state
• FLOW_STATE_STORE - flow engine runtime state

5. Optional: Configure Email (Resend)

For Email Code authentication:

./scripts/setup-resend.sh --env=local

Without Resend, Email Code values will be logged to the console (useful for development).

Project Structure

authrim/
├── packages/
│   ├── ar-lib-core/      # Core services, schemas, Durable Objects, storage routing
│   ├── ar-discovery/     # Discovery & JWKS endpoints
│   ├── ar-auth/          # Authorization, login, consent, flow engine
│   ├── ar-token/         # Token, introspection, revocation, token exchange
│   ├── ar-userinfo/      # UserInfo endpoint
│   ├── ar-management/    # Admin API and management surfaces
│   ├── ar-async/         # Device Flow & CIBA
│   ├── ar-saml/          # SAML IdP/SP
│   ├── ar-bridge/        # External IdP bridge
│   ├── ar-policy/        # Policy service
│   ├── ar-vc/            # Verifiable Credentials
│   ├── ar-router/        # Service Bindings router
│   ├── ar-admin-ui/      # Admin UI worker
│   ├── ar-login-ui/      # Login UI worker
│   ├── setup/            # @authrim/setup CLI and Web UI
│   ├── ar-lib-scim/      # SCIM library
│   ├── ar-lib-logging/   # Logging/audit runtime
│   └── ar-lib-policy/    # Policy engine library
├── scripts/              # Setup & deployment scripts
├── migrations/           # Core, PII, and admin D1 migrations
├── conformance/          # OpenID conformance testing
└── test/                 # Environment validation and smoke tests

Worker Architecture

Worker	Purpose	Endpoints
ar-discovery	OIDC Discovery	/.well-known/*
ar-auth	Authorization, login, consent	/authorize, /login, /consent, flow routes
ar-token	Token issuance and token operations	/token, /introspect, /revoke, token exchange
ar-userinfo	UserInfo	/userinfo
ar-management	Admin API and management surfaces	/api/admin/*, /register
ar-async	Async flows	/device_authorization, /bc-authorize
ar-saml	SAML IdP/SP	SAML metadata, SSO, SLO, ACS routes
ar-bridge	External IdP bridge	Social login, linked identity, handoff routes
ar-policy	Policy evaluation	Policy check/evaluation routes
ar-vc	Verifiable Credentials	VC issuer/verifier routes
ar-router	Public routing via Service Bindings	Routes requests to the component workers

Available Scripts

Development

pnpm run dev              # Start all workers with hot reload
pnpm run build            # Build all packages
pnpm run build:api        # Build API workers only (exclude UI)

Testing

pnpm run test             # Run unit tests
pnpm run test:e2e         # Run E2E tests (Playwright)
pnpm run test:e2e:ui      # Run E2E tests with UI
pnpm run test:lighthouse  # Run Lighthouse performance tests

Code Quality

pnpm run lint             # Run ESLint
pnpm run typecheck        # TypeScript type checking
pnpm run format           # Format code with Prettier
pnpm run format:check     # Check code formatting

Deployment

pnpm run deploy           # Deploy workers with retry logic
pnpm run deploy:ui        # Deploy Admin UI and Login UI workers
pnpm run deploy:all       # Deploy everything

Setup CLI

pnpm run setup            # Start the setup Web UI from source
pnpm run setup:init       # Initialize a new environment
pnpm run setup:deploy     # Deploy a configured environment
pnpm run setup:status     # Show deployment status
pnpm run setup:info       # Show resource information

For tenant-D1 environments:

npx @authrim/setup tenant-db-pool-status --env prod
npx @authrim/setup tenant-db-pool-expand --env prod --add-slots 10
npx @authrim/setup tenant-db-migrate-all --env prod

Conformance Testing

pnpm run conformance:basic    # Run Basic OP tests
pnpm run conformance:config   # Run Config OP tests
pnpm run conformance:dynamic  # Run Dynamic OP tests
pnpm run conformance:fapi2    # Run FAPI 2.0 tests
pnpm run conformance:all      # Run all conformance tests

Troubleshooting

Port 8787 already in use

# Kill the process using the port
lsof -ti:8787 | xargs kill -9

# Or use a different port
wrangler dev --port 8788

KV namespace not found

wrangler kv namespace list
./scripts/setup-kv.sh --env=dev

Private key not found

./scripts/setup-keys.sh
./scripts/setup-local-vars.sh

TypeScript errors

pnpm run typecheck

View logs

# Development
wrangler dev --log-level debug

# Production
wrangler tail --env production

Next Steps

• OIDC Configuration - Configure OpenID Connect
• API Reference - Explore the API