FerrisKey
Open-source identity and access management, written in Rust
Sponsors
FerrisKey is an identity and access management (IAM) server written in Rust. It implements OpenID Connect and OAuth 2.0, keeps the users, roles and clients of each tenant in a separate realm, and ships with an admin console and a Helm chart. It is meant as an open-source alternative to the heavier IAM servers.
- Features
- Quick start
- Configuration
- Database migrations
- Modules
- Architecture
- Observability
- Roadmap
- Adopters
- Contributing
- Code of conduct
- Security
- Sponsors and governance
- License
- Links
| Capability | Details |
|---|---|
| OpenID Connect / OAuth 2.0 | Standard flows for applications and services. |
| Multi-tenant realms | Users, roles, clients and secrets are isolated per realm. |
| Clients and service accounts | Fine-grained role mapping on a bitwise role system. |
| MFA | TOTP, WebAuthn, magic links and recovery codes, enforced through required actions. |
| Observability | Prometheus metrics and a security event log. |
| Kubernetes | Helm chart published as an OCI artifact. |
For local development with the repository justfile, see DEVELOPMENT.md.
docker compose --profile registry up -ddocker compose --profile build up -dWith either option, the console is at http://localhost:5555. The default credentials are admin / admin.
The compose file mounts
pgdataat/var/lib/postgresql, the mount point recommended from Postgres 18. If an older local setup used a different path, remove or migrate the old volume first.docker compose down -vresets it and deletes its data.
The chart needs a reachable Postgres, external or deployed by your platform's operator. See the chart documentation.
-
Clone the repository.
git clone https://github.com/ferriskey/ferriskey cd ferriskey -
Start the database and run the migrations.
cd api cp env.example .env # edit .env if the defaults do not suit you docker compose up -d cd ../core # sqlx-cli: cargo install sqlx-cli --no-default-features --features postgres DATABASE_URL=postgres://ferriskey:ferriskey@localhost:5432/ferriskey sqlx migrate run
-
Start the API. It needs a recent stable Rust toolchain (
rustup update).cd ../api cargo run -
Start the frontend (optional).
cd ../front cp .env.example .env pnpm install pnpm run dev
The console is at http://localhost:5555. The default credentials are admin / admin.
Common environment variables:
PORT=3333
ENV=development
LOG_LEVEL=info
DATABASE_URL=postgres://ferriskey:ferriskey@localhost:5432/ferriskey
ADMIN_PASSWORD=admin
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@ferriskey.rs
ALLOWED_ORIGINS=http://localhost:5555
ALLOWED_ORIGINS lists the origins accepted on every route. Each client can also declare its own web origins at runtime, enforced per realm (see the web-origins endpoints of a client). Those per-client origins never replace ALLOWED_ORIGINS: /config, the health probes and the API docs carry no realm, so an admin console served from another origin than the API must keep its origin in ALLOWED_ORIGINS.
By default, the API listens on port 3333 and the frontend on port 5555.
FerrisKey uses SQLx for database migrations. To apply pending migrations:
cd core
DATABASE_URL=postgres://ferriskey:ferriskey@localhost:5432/ferriskey sqlx migrate runTo check migration status:
DATABASE_URL=postgres://ferriskey:ferriskey@localhost:5432/ferriskey sqlx migrate infoIf DATABASE_URL is set in your environment or in .env, you can drop it from the command.
- Trident: multi-factor authentication (TOTP, WebAuthn, magic links, recovery codes) and the required actions that enforce it.
- SeaWatch: security event log, queryable and exportable from the console.
- Webhooks: notifications on user, client and realm lifecycle events, so integrations do not need a fork.
FerrisKey follows a hexagonal (ports and adapters) architecture. The domain logic does not depend on the database or the HTTP layer: those implement the ports the domain defines, and can be replaced without touching it.
The API serves Prometheus metrics on /metrics, under the configured root path.
The public roadmap is at https://ferriskey.rs/roadmap. ROADMAP.md lists the epics in progress and how the roadmap is maintained.
Organizations using FerrisKey are listed in ADOPTERS.md. If you run FerrisKey, add yourself with a pull request.
Bug fixes, features, documentation and tests are all welcome.
- Read CONTRIBUTING.md.
- Pick an issue. Those labelled
good first issueare a good place to start. - Open a pull request with tests and a short description.
Questions about modules, APIs or the console go to Discussions.
FerrisKey follows the CNCF Code of Conduct. See CODE_OF_CONDUCT.md for scope and how to report an incident.
Report vulnerabilities privately through the Security tab, never in a public issue. Supported versions, response targets and the disclosure process are in SECURITY.md.
FerrisKey is Apache-2.0 only, with no CLA, no open-core model and no enterprise edition. Sponsors fund the project but do not control it. See Sponsors and open source commitments in GOVERNANCE.md.
The project is preparing a CNCF Sandbox application, tracked in #1623. The answers to the Day 0 General Technical Review live in docs/cncf/general-technical-review.md.
FerrisKey is released under the Apache-2.0 license.
- Source: https://github.com/ferriskey/ferriskey
- Helm chart (OCI):
oci://ghcr.io/ferriskey/charts/ferriskey - Documentation: https://docs.ferriskey.rs/en/discover/what-is-ferriskey
- Discussions: https://github.com/ferriskey/ferriskey/discussions
- Sponsor: https://github.com/sponsors/ferriskey