AuthForge user guide

Everything you need to run your own identity engine — written for two audiences. If you just want to understand what AuthForge does, start with the Overview. If you run a website and want login today, start with Set up for your website or the setup wizard.

Overview

AuthForge answers one question for your application: “who is this user, and what are they allowed to do?” — and it answers it without sending your users' data to anyone else.

Most teams reach for a hosted service like Auth0 or Clerk. Those work, but they bill per user, they keep your identity data on their servers, and every login check makes a round trip to their cloud. AuthForge is the opposite: it is a single program you run on your own server. Your users' accounts, passwords, and sessions stay inside your infrastructure, and verification happens locally — in well under a millisecond.

In one sentence: AuthForge is self-hosted login and access control that you own outright, with bank-grade cryptography built in and no per-user fees.

Set up for your website

This section is for anyone who runs a website and wants login — you do not need to write Rust or read source code.

1. Choose where AuthForge runs. The easiest path is Ratel (push the repo, attach a domain like auth.yourdomain.com). On your own server, run docker compose up --build.
2. Open the setup wizard. Type your domain names. Copy the generated environment variables into Ratel or your server.
3. Test login. Visit https://auth.yourdomain.com/login.html. Create an account or sign in with your workspace credentials.
4. Add sign-in to your site. Either link to AuthForge (<a href="https://auth.yourdomain.com/login.html">Sign in</a>) or paste the one-line SDK snippet from the wizard into your site header.
5. Done. Your users sign in through AuthForge; their data stays on your infrastructure. No Auth0 account, no per-user bill.

Key concepts

A short glossary so the rest of the guide makes sense — useful whether or not you have a security background.

Quickstart

You need Docker installed. One command starts Postgres, the identity engine, and the login UI on port 8080.

1. Start the stack.
   terminal

   git clone https://github.com/techmaster25/AuthForge
   cd AuthForge
   export AUTHFORGE_PASSWORD_PEPPER="$(openssl rand -base64 32)"
   docker compose up --build

2. Open the login page. Visit http://localhost:8080/login.html and sign in or create an account.
3. Confirm public keys.
   terminal

   curl http://localhost:8080/api/v1/jwks.json
   # → { "keys": [{ "kty": "OKP", "crv": "Ed25519", ... }] }

4. Configure for production. Use the setup wizard to generate env vars for your domain.

Configuration

Everything is configured with environment variables. Every value has a safe default, so you can start with none and tune later. The most common settings:

The full list ships in .env.example in the repository. Use the setup wizard to generate values for your domain.

Verify it works

Three quick checks confirm a healthy deployment:

• Liveness: curl http://localhost:8080/healthz returns ok.
• Readiness: curl http://localhost:8080/readyz returns ready.
• Keys: /api/v1/jwks.json returns one or more Ed25519 keys.

A successful AuthenticateUser call returns a session token plus the user's identity, organizations, and permissions. Passing that token to ValidateSession returns valid: true with the same identity — proof the round trip works end to end.

Integrate your app

The fastest path: add the zero-dependency SDK from your AuthForge host (same origin recommended):

<script src="https://auth.yourdomain.com/sdk/authforge.js"></script>
<script>
  AuthForge.init({ authority: 'https://auth.yourdomain.com' });
  AuthForge.login('user@example.com', 'password').then(function (s) {
    console.log('Signed in as', s.identity.email);
  });
</script>

See the full setup wizard for copy-paste env vars and verification steps.

React apps can wrap the provider when the npm package ships; until then, call the SDK directly:

import { AuthForgeProvider, useAuth } from '@authforge/react';

export function App() {
  return (
    <AuthForgeProvider authority="https://auth.authforge.dev">
      <Dashboard />
    </AuthForgeProvider>
  );
}

function Dashboard() {
  const { user, status } = useAuth();
  if (status === 'authenticating') return <Spinner />;
  return <p>Signed in as {user?.email}</p>;
}

On the back end, you do not need to call AuthForge to check a token — fetch the JWKS once, cache it, and verify the Ed25519 signature locally with any standard JWT library. That is what keeps verification under a millisecond with zero network round trips.

JavaScript SDK

Load /sdk/authforge.js from your AuthForge host. Zero dependencies, works in any HTML page, PHP site, WordPress theme, or SPA.

Ready-made login UI: copy login.html and signup.html from the repo, or link directly to them on your AuthForge host.

Deploy on Ratel

Ratel is the recommended way to put AuthForge online. Push the repo to GitHub, connect Ratel's GitHub App, and create a backend project with internal_port = 8080 and persistent = true.

The server ships the login UI, docs, and API from one process — after deploy, open /login.html on your domain for a live demo. Required secrets:

• AUTHFORGE_PASSWORD_PEPPER — generate once with openssl rand -base64 32
• AUTHFORGE_DATABASE_URL — Ratel managed Postgres + ?sslmode=disable
• AUTHFORGE_CORS_ORIGINS — your front-end domain(s)

Full checklist: Configure AuthForge or RATEL_DEPLOY.md in the repository.

API reference

HTTP — auth (browser-facing)

HTTP — public

HTTP — admin (superadmin only)

gRPC — trusted (local mesh)

Service authforge.auth.v1.AuthService exposes two routes:

• AuthenticateUser(email, password, organization_context) → a signed session token, a refresh token, expiry, and the resolved identity (user id, organizations, roles, permissions).
• ValidateSession(session_token) → valid, the resolved identity, and expiry. Pure cryptography — no database touch.

The full contract is the auth_service.proto file in the repository; generate a client in any language with your usual gRPC tooling.

Security & rotation

AuthForge is secure by default. Highlights:

• Passwords are hashed with Argon2id (tuned to OWASP) and an optional pepper, so a stolen database is not enough to recover them.
• Sessions are Ed25519-signed and carry expiry, not-before, issuer, and audience — all enforced on validation.
• Refresh tokens are 256-bit random secrets, stored only as digests and compared in constant time.
• Brute force is throttled per identity, and unknown-user and bad-password responses are identical to prevent account enumeration.

Key rotation is zero-downtime: drop a new key file into AUTHFORGE_KEY_DIR and point the primary marker at it. The previous key stays in the JWKS until its tokens expire, so nothing signed before the switch breaks.

Testing & hardening

Security claims are only worth what verifies them. AuthForge ships with an automated test suite and a continuous-integration gate:

• Cryptographic tests — sign/verify round trips, rejection of foreign keys, tampered tokens, expired tokens, wrong audience/issuer, and algorithm-confusion attempts.
• Credential tests — Argon2id round trips and pepper isolation.
• Handshake tests — end-to-end authenticate → validate, enumeration resistance, organization-scope enforcement, and brute-force lockout.
• Supply-chain gate — every change runs cargo‑deny (advisories, licenses, banned and duplicate dependencies, source provenance) and clippy with warnings treated as errors.

See SECURITY.md in the repository for the full threat model and the disclosure process. Found a vulnerability? Follow our responsible-disclosure policy.

FAQ

Do I need a database to try it?

No. The quickstart runs with an in-memory demo store so you can exercise the full flow immediately. For production, connect PostgreSQL.

Where do my users' passwords go?

They are hashed with Argon2id inside your deployment and never leave it. We never see them — there is no AuthForge cloud in the path.

What happens if AuthForge restarts?

Signing keys are persisted to the key volume, so the same keys load on restart and existing sessions keep validating.

Is it really free?

The self-hosted Community tier is free forever, with no per-user fees. Paid tiers add support and enterprise controls — see Pricing.

How do I configure AuthForge for my website?

Open the setup wizard, enter your domain names, and copy the generated settings. The plain-language guide is at Set up for your website.

Do I need a separate server for the login page?

No. AuthForge serves the login UI, docs, and API from one process on port 8080 — including on Ratel.