Architecture Overview
A deep dive into AuthMe's system design, module structure, authentication flows, and extensibility.
System Design
AuthMe is a monorepo consisting of three main packages that share a single PostgreSQL database:
React / Vue / Next.js
Native / Hybrid
Express / NestJS
AuthMe Server (NestJS)
REST API
100+ endpoints
OIDC Engine
RFC 6749 + OIDC 1.0
SAML 2.0
IdP + Metadata
Admin Console
React SPA served
Prisma ORM
Type-safe queries
Metrics
Prometheus
PostgreSQL 16+
27 Prisma models
Module Structure
AuthMe's NestJS backend is divided into 32 focused modules. Here are the most important:
AuthModule
Login, logout, token issuance, session management
RealmModule
Multi-tenant realm creation and configuration
UsersModule
User CRUD, profile, email verification, password reset
ClientsModule
OAuth/OIDC/SAML client registration and secrets
RolesModule
Realm roles, role mappings, role-based access
GroupsModule
User groups and group-to-role assignments
OidcModule
Authorization Code, Implicit, Client Credentials flows
SamlModule
SAML 2.0 IdP, assertion generation, metadata
LdapModule
LDAP/AD federation and user sync
MfaModule
TOTP, WebAuthn, backup codes
SessionsModule
Active session listing and revocation
TokensModule
JWT issuance, key rotation, introspection
Authentication Flow
The standard Authorization Code + PKCE flow used by most web applications:
- 1
Authorization Request
The client redirects the user to AuthMe's
/authendpoint with acode_challenge(PKCE). - 2
User Authentication
AuthMe presents the login page. The user enters credentials. MFA is prompted if enabled on the realm.
- 3
Consent
If the client requests custom scopes, the user is shown a consent screen.
- 4
Authorization Code Redirect
AuthMe redirects back to the client's
redirect_uriwith a short-lived authorization code. - 5
Token Exchange
The client exchanges the code +
code_verifierfor an access token, refresh token, and ID token. - 6
API Access
The client includes the access token as
Authorization: Bearer <token>on every API request. - 7
Token Refresh
When the access token expires, the client uses the refresh token to obtain a new access token silently.
Database Schema Overview
AuthMe uses Prisma with 27 models. The key relationships are:
| Model | Key Fields | Relationships |
|---|---|---|
| Realm | name, displayName, theme | has many Users, Clients, Roles |
| User | email, username, passwordHash, mfaEnabled | belongs to Realm, has many Sessions, Roles |
| Client | clientId, secret, type, redirectUris | belongs to Realm, has many Tokens |
| Session | refreshToken, expiresAt, ipAddress | belongs to User, Client |
| Role | name, description, composite | belongs to Realm, has many Users via mapping |
| Group | name, path | has many Users, Roles; supports nesting |
Plugin System
AuthMe's modular architecture makes it straightforward to extend. Common extension points:
Custom Identity Providers
Implement the IdP interface to add any external identity source (LDAP, social logins, custom OAuth providers).
Attribute Mappers
Write custom mappers to transform, filter, or enrich user attributes included in tokens and assertions.
Custom MFA Providers
Implement the MFA interface to add hardware tokens, push notifications, or any OTP delivery mechanism.
Event Listeners
Subscribe to auth events (login, logout, registration, token issued) to trigger webhooks or sync external systems.