One binary for SSO, MFA, and OpenID Connect.

00 Introduction

What IAM Server is

IAM Server is a self-hosted identity server. It ships as one Go binary with the admin UI built in.

The server does five jobs:

• It acts as an OIDC / OAuth 2.0 provider for your apps.
• It acts as a CAS server for older apps.
• It lets users sign in with Google, GitHub, or any OIDC provider (Microsoft, Okta, GitLab, or Keycloak).
• It enforces MFA (authenticator apps and passkeys).
• It protects other apps behind Caddy or Traefik with forward-auth.

01 Installation

Install & run

Choose one path. Use local development to work on the code. Use production to run the server for real.

Requirements

02 Local development

Run it locally

Postgres runs in Docker. The server runs on your machine. The make targets drive the whole loop.

Prerequisites

• Go 1.26 or later
• Node 22 or later (only to build the web UI)
• Docker (it provides PostgreSQL 16 or later)

1. Start Postgres

   This command starts a local PostgreSQL in Docker.

   make compose-dev-up

2. Generate a signing key

   This command writes an RSA key to ./signing.pem. The server signs id_tokens with this key.

   make keygen

3. Create a .env file in the project root

   This is the minimum needed to start. SESSION_SECRET must be at least 32 bytes.

   cat > .env <<ENV
   DATABASE_URL=postgres://iam:iam@localhost:5432/iam?sslmode=disable
   BASE_URL=http://localhost:8080
   SESSION_SECRET=$(openssl rand -hex 32)
   SIGNING_KEY_PATH=$PWD/signing.pem
   AUTO_MIGRATE=true
   LOG_LEVEL=debug
   DOCS_ENABLED=true
   ENV

4. Load the .env and apply migrations

   Load the .env into your shell. Then create the database schema.

   set -a; source .env; set +a
   make migrate-up

5. Create your first admin user

   This command seeds a local account. You sign in with this account.

   make seed-user [email protected] password=devpass123 admin=1

6. Run the backend and the web UI

   Use two terminals. Port 8080 serves the embedded build. Port 5173 is the Vite dev server with hot reload. Both share the sign-in session. Use 5173 while you work on the UI. Use 8080 to test the real build. To reset all data, run make compose-dev-clear.

   make dev-server   # Terminal A -> http://localhost:8080
   make web-dev      # Terminal B -> http://localhost:5173
   
   # Or build the UI once, then run only the backend:
   make web-build
   make dev-server

03 Database

Database & migrations

The server stores all state in PostgreSQL 16 or later. It applies schema changes with versioned migrations.

How migrations run

The migration files live in internal/store/migrations. Each change has an up file and a down file. The server applies pending migrations on start when AUTO_MIGRATE=true. To run them by hand, use the make targets.

make migrate-up            # apply all pending migrations
make migrate-down          # roll back the most recent migration
make migrate-new name=add_foo   # create a new up/down pair

Schema conventions

• Every table uses a UUID v7 primary key. These keys sort by time.
• Every timestamp is TIMESTAMPTZ in UTC.
• A soft delete sets deleted_at; it does not remove the row.
• Every migration has an up file and a down file.
• Migration files use the name NNNN_description.up.sql and .down.sql.

Core tables

Reset the database

To delete all local data, remove the Docker volume. Then start again from the development steps.

make compose-dev-clear   # stop Postgres and delete the volume

04 Scripts & tests

Make targets & tests

The Makefile drives every task. Run make help to list all targets.

Build & run

Test

The tests use a real Postgres through testcontainers-go. Docker must be running.

# run the full suite
make test

# smoke-test a running server on another port
BASE_URL=http://localhost:9000 make smoke-test

Web UI

Keys & users

Security scans

05 Environment variables

Configuration

You configure the server with environment variables. An optional YAML overlay (CONFIG_FILE) sets non-secret fields. Secrets must come from the environment or mounted files, never from committed YAML.

No variable matches your filter.

06 Contribution

Contribution rules

Follow these rules for every change. They keep the codebase small, safe, and consistent.

The development loop

Set up your machine with the Local development steps. Then use this loop for each change:

1. Create a branch. Use a prefix: feat/, fix/, chore/, or docs/.
2. Write the code and a test for it.
3. Run make test and make lint.
4. Commit with a Conventional Commit message (for example, feat: add WebAuthn enrollment).
5. Open a pull request.

Pull request rules

• The CI must pass.
• One reviewer must approve.
• The code must have no lint warnings.

Git conventions

Add a dependency

Keep the runtime section of go.mod short. Before you add a dependency, answer these questions. If a pull request adds a require entry, justify it in the commit message.

Code style

• The dependency flow is api → auth → store. It never runs the other way.
• internal/ packages are private. pkg/ packages are public.
• Define sentinel errors in each package. Wrap errors with context.
• HTTP handlers return RFC 7807 Problem JSON on error.
• Put unit tests next to the source file (foo_test.go).

07 Production deploy

Deploy to production

Everything runs in Docker on your server: PostgreSQL and the single IAM binary. Terminate TLS in front of the server.

Prerequisites

• Docker on the host
• A domain and TLS in front (a reverse proxy or a tunnel)
• A backup plan for two things: the pgdata volume and signing/signing.pem

1. Configure the environment

   Copy the compose env template. Fill in real values: BASE_URL (your real https URL), POSTGRES_PASSWORD, SESSION_SECRET, and ADMIN_EMAIL with ADMIN_PASSWORD (your first admin sign-in).

   cd deployments
   cp .env.example .env
   $EDITOR .env
   #   POSTGRES_PASSWORD: openssl rand -hex 24
   #   SESSION_SECRET:    openssl rand -hex 32

2. Create and protect the signing key

   This key signs every token. Set the owner to the container's non-root user. Restrict the file mode. Back up the key off-host. If you lose the key, every issued token stops working.

   mkdir -p signing
   openssl genrsa -out signing/signing.pem 2048
   sudo chown 65532:65532 signing/signing.pem
   chmod 600 signing/signing.pem

3. Put the server behind TLS

   The server speaks HTTP. Terminate HTTPS in front. Use a reverse proxy (Caddy is the documented companion; Traefik also works) or a tunnel (for example, Cloudflare) that points at the container's HTTP port. Set BASE_URL to the public https URL. BASE_URL must match what the proxy serves.

4. Start the stack

   This command starts Postgres and IAM. The server creates the first admin account from ADMIN_EMAIL and ADMIN_PASSWORD on the first run.

   docker compose up -d --build

5. Harden the deployment

   Sign in. Then enroll a second factor at /mfa/enroll. Set SIGNUP_ENABLED=false to keep registration closed. Set SESSION_COOKIE_DOMAIN and PROXY_ALLOWED_CALLBACK_ORIGINS if you use the reverse-proxy companion across subdomains.

6. Operate the server

   Update the server by a rebuild. Follow the logs with the compose logs command.

   docker compose up -d --build   # update
   docker compose logs -f iam     # logs

Back up two things

Check before you go live

• BASE_URL matches what users type (scheme, host, no trailing slash).
• <BASE_URL>/.well-known/openid-configuration returns JSON.
• <BASE_URL>/healthz returns ok.
• Your admin account has MFA enrolled.

Caddy example

Caddy is the documented companion proxy. It handles TLS for you.

app.example.com {
    forward_auth iam:8080 {
        uri /proxy/verify
        copy_headers X-Auth-User X-Auth-Email X-Auth-Groups
    }
    reverse_proxy backend:3000
}

08 API routes

HTTP API reference

Every route the server exposes, grouped by area. Use the filter in the sidebar to find a route fast.

No route matches your filter.

09 CSRF

CSRF protection

CSRF is cross-site request forgery. An attacker tricks a browser into sending a request with the user's session cookie attached. The server blocks this with a double-submit cookie.

How it works

The server issues a random token in a cookie named iam_csrf. The cookie is readable by JavaScript, so the admin UI can echo it. On every state-changing request, the client must present the same token. The server compares the two values.

• The admin UI sends the token in the X-CSRF-Token header.
• A server-rendered form sends the token in the _csrf field.

The server checks POST, PUT, PATCH, and DELETE requests. It does not check GET, HEAD, or OPTIONS, because those requests are safe.

Which routes are checked

The server protects the browser flows:

• POST /cas/login
• /password/forgot and POST /password/reset
• The /mfa/* POST routes (verify and enroll)
• The /admin/v1/* POST, PATCH, and DELETE routes

Which routes are exempt

Machine-to-machine and read-only routes skip CSRF. A browser does not drive them, so a forged request is not a risk.

Send the token from a client

Read the iam_csrf cookie. Send its value in the X-CSRF-Token header.

const token = document.cookie
  .split("; ")
  .find((c) => c.startsWith("iam_csrf="))
  ?.split("=")[1];

await fetch("/admin/v1/users", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-CSRF-Token": token },
  body: JSON.stringify({ email: "[email protected]" }),
});

10 CAS

CAS

CAS is the Central Authentication Service protocol. The server accepts CAS 2.0 and 3.0. Older apps use it for single sign-on.

The sign-in flow

1. An app sends the user to /cas/login?service=<app-url>.
2. The server signs the user in. It issues a service ticket (ST).
3. The server sends the user back to the app with the ticket.
4. The app calls a validate endpoint to check the ticket.
5. The server returns the user and, in CAS 3.0, the released attributes.

Endpoints

The CAS-to-SSO bridge

A CAS app can use a modern provider. When the user has no local session, the server starts an upstream OIDC or OAuth flow (Google, GitHub, and others). It maps the returned identity to a local user. Then it issues the CAS ticket.

Client App  --CAS login-->  IAM Server  --OIDC flow-->  Google / GitHub
                <-- ST --                   <-- id_token --
Client App  --validate ST--> IAM Server
                <-- user attrs --

Register a CAS service

The server issues a ticket only for a registered service URL. Add the service in the admin UI, or with the admin API.

curl -X POST https://auth.example.com/admin/v1/cas-services \
  -H "X-CSRF-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  --cookie "iam_session=$SESSION" \
  -d '{"name":"Wiki","service_url":"https://wiki.example.com/.*"}'

11 OpenID Connect

OpenID Connect & OAuth 2.0

The server is a standards-conformant authorization server. Modern apps use it for sign-in and for API authorization.

Supported flows

• Authorization Code with PKCE: for web apps, single-page apps, and mobile apps.
• Client Credentials: for machine-to-machine access.
• Refresh Token: to get a new access token without a new sign-in.

The Implicit flow and the Password flow are off by default.

Discovery

An app reads the server's metadata from the discovery document. It finds every endpoint and the signing keys there.

curl https://auth.example.com/.well-known/openid-configuration
curl https://auth.example.com/.well-known/jwks.json

The Authorization Code flow with PKCE

1. The app creates a code_verifier and a code_challenge.
2. The app sends the user to /oauth2/authorize with the challenge.
3. The user signs in and grants consent.
4. The server returns an authorization code to the app.
5. The app calls /oauth2/token with the code and the verifier.
6. The server returns an id_token and an access_token.

Register a client

Add a client in the admin UI, or with the admin API. Set the redirect URIs and the scopes. A public client (a single-page app or a mobile app) uses PKCE and holds no secret.

curl -X POST https://auth.example.com/admin/v1/clients \
  -H "X-CSRF-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  --cookie "iam_session=$SESSION" \
  -d '{
    "name": "My SPA",
    "redirect_uris": ["https://app.example.com/callback"],
    "is_public": true,
    "require_pkce": true
  }'

Exchange a code for tokens

curl -X POST https://auth.example.com/oauth2/token \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://app.example.com/callback \
  -d client_id=my-spa \
  -d code_verifier=$VERIFIER

12 MFA

Multi-factor authentication

MFA adds a second factor to sign-in. The server challenges the user after the password step.

Methods

Enroll a factor

A signed-in user enrolls a factor at /mfa/enroll.

1. Open /mfa/enroll.
2. For TOTP, scan the QR code. Enter the 6-digit code to confirm.
3. For a passkey, follow the browser prompt.
4. Generate backup codes. Store them in a safe place.

Enforce MFA

You control MFA at two levels:

• Per user: a user enrolls a factor. The server then challenges that user.
• Per client: a client sends acr_values to require MFA for its sign-in.
• Global: set FORCE_MFA=true to require MFA for everyone.

13 Federation

Set up federation (upstream SSO)

Federation lets users sign in with an external provider. The server maps the external identity to a local user.

How linking works

On the provider callback, the server does three checks in order:

1. It looks for a user already linked to this provider and subject. If it finds one, it signs the user in.
2. It looks for a user with the same email. If it finds one, it prompts the user to link the accounts.
3. If it finds neither, it creates a new user and links the provider.

Set up Google

1. Create an OAuth client in the Google Cloud console.
2. Set the redirect URI to <BASE_URL>/oauth/callback/google.
3. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
4. Restart the server. A Google button appears on the sign-in page.

Set up GitHub

1. Create an OAuth app in GitHub settings.
2. Set the callback URL to <BASE_URL>/oauth/callback/github.
3. Set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET.
4. Restart the server. A GitHub button appears on the sign-in page.

Set up any OIDC provider

Use the generic OIDC connector for Microsoft, Okta, GitLab, Keycloak, and others. List each provider by a slug. Then add its four variables.

OIDC_PROVIDERS=microsoft,okta

OIDC_MICROSOFT_ISSUER=https://login.microsoftonline.com/common/v2.0
OIDC_MICROSOFT_CLIENT_ID=...
OIDC_MICROSOFT_CLIENT_SECRET=...
OIDC_MICROSOFT_DISPLAY_NAME=Microsoft

OIDC_OKTA_ISSUER=https://acme.okta.com
OIDC_OKTA_CLIENT_ID=...
OIDC_OKTA_CLIENT_SECRET=...

Set the redirect URI at the provider to <BASE_URL>/oauth/callback/<slug>. For the example above, the slugs are microsoft and okta.

14 Systems

Systems & features

What each part of the server does.

15 Security

Security defaults

The server ships with safe defaults. This section lists them so you know what protects your deployment.

Passwords & sessions

• The server hashes passwords with Argon2id.
• Session cookies are HMAC-SHA256 signed. They set HttpOnly, Secure, and SameSite=Lax.
• A https BASE_URL turns on the Secure flag automatically.

Response headers

The server sets these headers on every response:

Rate limits

• The login endpoint accepts 5 requests per minute per IP.
• The token endpoint accepts 20 requests per minute per client.

Report a vulnerability

Do not open a public issue for a security problem. Report it privately. See SECURITY.md in the repository.

16 Operations

Operations

Run and maintain the server after it is live.

Health endpoints

Rotate the signing key

Rotate the key with no downtime. Old tokens stay valid until they expire.

1. Generate a new key. Add it to the JWKS as a second key.
2. Deploy. The server signs new tokens with the new key. It verifies old tokens against both keys.
3. Wait for the maximum token lifetime to pass.
4. Remove the old key from the JWKS.

make rotate-key dir=/etc/iam/keys

Update & logs

docker compose up -d --build   # update to a new build
docker compose logs -f iam     # follow the logs