This directory contains the operational documentation set for Issuerd — guides and references for the people who deploy, configure, administer, and troubleshoot an Issuerd installation, and for application developers integrating their software with it. Every guide below opens with its own table of contents (the two short references, CLUSTERING.md and PERFORMANCE.md, go straight to the point).
The documentation is written against the repository itself (configuration structs, route definitions, CLI, compose stacks, and test harnesses) and reflects behavior as implemented. Where Issuerd deliberately diverges from Keycloak, the difference is called out and also tracked in tests/KEYCLOAK_DIFFS.md.
Depending on your role, you will typically read the set in this order:
| Document |
What it covers |
| Getting started |
Installation (Docker demo stack or build from source), first boot and seeding, verifying the installation, obtaining a first token, first hardening steps. |
| Configuration |
Complete issuerd.toml reference: loading order, environment overrides, and every section — storage, TLS, logging, proxy, CORS, cluster, cache, themes, SMTP including per-realm overrides. |
| Provisioning |
Declarative realm seeding with provision.yaml: the apply-once marker semantics, the provision CLI command, and a field-by-field reference for realms, roles, groups, clients, users, identity providers, and flow configs. |
| Document |
What it covers |
| Deployment |
Deployment topologies, container and bare-metal/systemd installation, TLS termination options, reverse-proxy requirements, health checks, and the production checklist. |
| Clustering |
Multi-node operation: the shared-state model (PostgreSQL + Redis), storage-backed signing keys, load-balancer requirements, and the two-node demo stack. |
| Performance |
Measured performance and sizing: k6 benchmark stack (tests/perf/, isolated network, Docker CPU/memory limits), throughput/latency vs Keycloak 26.7, CPU/RAM/disk/log growth, agentic workloads (DPoP/CIBA); plus the in-process micro-benchmarks (tests/integration/bench.rs). |
| Document |
What it covers |
| Administration |
The admin access model (master realm, realm-management roles), the admin console, the Admin REST API with a curl cookbook, OpenAPI export, and events management. |
| Client integration |
The application developer’s guide: discovery and endpoint map, choosing a flow, registering clients, the authorization code flow with PKCE end to end, token handling, logout, client authentication methods, adapter-config download, and advanced OAuth capabilities. |
| Document |
What it covers |
| MCP server |
The realm-scoped external MCP endpoint: 71 curated read/write/account/strict tools, three read-only resources, exact operation-bound CIBA, resource provenance, DPoP by default, dual-era stateless transport, and real TypeScript/rmcp acceptance rigs. |
| Agentic IAM: MCP tool calls with DPoP and token exchange |
Securing AI-agent tool calls end to end and governing non-human identities: DPoP sender-constraining (cnf.jkt, single-use jti replay cache), RFC 8693 audience/scope attenuation per call (per-tool scoped credentials), the resource-server enforcement checklist, a live failure matrix, and the recorded MCP demo. |
| Human step-up approval with CIBA |
Client-Initiated Backchannel Authentication (poll mode) as the human-in-the-loop for privileged agent actions: endpoints and parameters, binding messages, DPoP-bound step-up tokens, the step-up configuration pattern, and the recorded refund-approval demo. |
Runnable example: examples/agentic-mcp/ |
The external downstream-agent scenario as a self-contained docker compose stack (chat agent + MCP server + PostgreSQL RLS): docker compose up -d, sign in as alice/changeme, and watch every protocol step in the security-trace panel. |
Runnable example: examples/mcp-admin/ |
Official-TypeScript-SDK acceptance for the built-in endpoint: code + PKCE + DPoP, reads/resources, ordinary writes, exact-operation approval, replay reconciliation, and a three-node rig. |
| Document |
What it covers |
| One approval, one exact operation |
The security architecture of agent-native administration: model-independent server policy, risk tiers, canonical operation binding, fresh CIBA approval, atomic mutation, and reconciliation across three nodes. |
| OpenID conformance and certification |
What self-hosted engineering runs, OIDF-hosted evidence, and registry entries each prove; the 11-profile version matrix, expected results, and the v0.1.19 resubmission. |
| Document |
What it covers |
| User federation |
LDAP (Samba AD, OpenLDAP, MS Active Directory) and Kerberos/SPNEGO: provider configuration, user synchronization, group-mapping semantics, and operating a federated realm. |
| LDAP group mapping and token claims |
The end-to-end pipeline: directory memberships → synced Issuerd groups → group role mappings → realm_access / resource_access / groups claims in tokens, with MS AD, Samba, and OpenLDAP specifics. |
| Identity brokering |
External OIDC and social identity providers (Google, GitHub, Microsoft): configuration, first broker login, account linking, IdP mappers, and kc_idp_hint. |
| Document |
What it covers |
| Security |
Hardening: TLS and proxy baseline, signing-key rotation, password policies, brute-force protection, MFA operations (TOTP, WebAuthn, email codes), session and token hardening, admin-surface hygiene. |
| Monitoring |
/health and /ready probes, Prometheus metrics, logging and request correlation, login events and admin events (querying, retention, auditing). |
| Backup, restore, and upgrade |
Where state lives, PostgreSQL, SQLite, and JSON-snapshot backup/restore procedures, schema migrations, single-node and rolling cluster upgrades, rollback rules, and a disaster-recovery skeleton. |
| Troubleshooting |
Symptom → cause → fix for startup, login flow, token, email, federation, brokering, and cluster problems, plus how to gather diagnostics and file a useful bug report. |
These documents live outside docs/ but are part of the operational picture:
- Commands are shown for a Linux shell and assume the repository root as the working directory unless stated otherwise.
- Placeholders use angle brackets (
<db-password>) or example domains (idp.example.com); replace them before running.
- Admonitions:
> **Note:** for clarifications, > **Warning:** for actions that can lock users out, invalidate tokens, or lose data.
- Cross-references between these documents are relative links; source files are cited by repository path (e.g.
crates/issuerd-server/src/config.rs).
- Default credentials and demo content (
admin/admin, alice/changeme) refer to the seeded demo material described in Getting started — never leave them in place on a reachable deployment.
