Administration overview

The administration area appears in the sidebar as soon as your account holds at least one admin read permission (see Roles). Realm administrators with realm:admin see everything; "granular" admins (e.g. a user manager) only see the areas they have rights for.

First time setting this up?

If you've just installed Modgud and want to bind your first SaaS app, start with the SaaS App Integration Walkthrough — it's the linear path.

Areas

Identity & Access

• Users — create, edit, lock, unlock, GDPR-erase accounts
• Roles — permission bundles per app
• Groups — who is a member of what role; static or scripted

Apps

Modgud is multi-app capable: every SaaS application in a realm is registered as its own App with its own resources, roles, and OAuth bindings.

• Applications — register apps and curate their permission catalogs

OAuth & OpenID Connect

Modgud is not just a login frontend — it's a full OAuth 2.0 / OpenID Connect provider built on OpenIddict. Third-party apps sign in via OIDC instead of maintaining their own user databases.

• OAuth Clients — apps that sign in through the IdP (web, mobile, CLI)
• OAuth Scopes — which capabilities (scopes) are available?
• OAuth APIs (Resource Servers) — register backends that validate tokens
• Dynamic Client Registration — let AI agents (Claude Code, Cursor, MCP clients) register themselves as OAuth clients

Federation & Realms

• Login Providers — built-in Internal plus external OIDC (Google, Microsoft, Entra, any OIDC); step-by-step setup walkthroughs included
• Realms — multi-tenant setup; each tenant gets its own database
• Realm Settings — realm-admin-owned config (self-registration, DCR policy, branding)

Customization

Per-realm look and feel. SPA-shell branding plus a beta page-builder editor.

• Branding — product name, primary color, logo, favicon
• Asset Library — upload images for branding (and, later, page schemas); SVG sanitisation built in
• Pages (Beta) — drag-and-drop editor for login / logout / forgot-password; gated behind a feature flag while the runtime renderer is still being built

Operations

• Observability — OpenTelemetry metrics + tracing + in-app live activity feed
• Auth Log — audit trail of all login events
• Change Requests — approve profile changes (when the approval flow is enabled)
• Settings — 2FA enforcement, grace period, SMTP, …
• Feature Flags — operator-level toggles for beta / WIP surfaces
• Recovery CLI — when the UI no longer responds

Permissions: the three-segment model

Modgud manages permissions in the form app:resource:action. Examples:

Permission	Meaning
user:read	Read the user list in modgud
oauth-client:write	Manage OAuth clients in modgud
todo:write	Write todos in the acme-tasks app
realm:admin	Realm-wide bypass — everything in any app
modgud:admin	App-wide bypass for modgud
modgud:user:admin	Resource-wide bypass for "user" in modgud

Three bypass tiers keep permission lists short:

• realm:admin — realm-wide. Whoever holds it may do anything in any app.
• <app>:admin — app-wide.
• <app>:<resource>:admin — resource-wide.

Who is a realm admin?

The first admin in every realm — created via the recovery CLI or the Control-Plane-issued bootstrap invite (see First-time setup) — is automatically placed into the Administratoren group whose BoundTo: ["*"] wildcard makes them effective in every app. Add more admins by putting users into that group (or any other group with equivalent rights).

Granular gating

The sidebar automatically hides everything you can't read. Examples:

• Realm admin (realm:admin) — sees and may do everything, in every app
• User manager in modgud — user:read + :write + session:read + auth-log:read → only the user/session area
• OAuth manager — modgud:oauth-client:* + modgud:oauth-scope:* + modgud:oauth-api:* → only the OAuth area
• Acme-Tasks Editor (in the acme-tasks app) — todo:write + project:write → not an admin in modgud, but very much in acme-tasks

Typical workflows

Bind a new SaaS app

Full step-by-step walkthrough: SaaS App Integration — realm admin → app → OAuth client → resource server → group/role → backend code.

Onboard a new employee

1. Create the user (first name, last name, email)
2. Send the sign-in link — the user sets their password and 2FA themselves
3. Add them to the right groups — those already carry the right roles + BoundTo to the right apps
4. Done — the user can log in and has the right permissions in every connected app

Wire up external SSO (Microsoft Entra)

Full step-by-step walkthrough: Login Providers.

Run multiple tenants

Each tenant gets its own realm — own database, own users, own roles. Routing is per subdomain (tenant1.auth.firma.at, tenant2.auth.firma.at).

Admin locked out

Recovery CLI — a shell tool inside the container that bypasses the UI and writes directly to the database.

Real-time updates

All admin lists refresh themselves automatically when another admin (or you in a second tab) changes something. This happens via SignalR push — no manual reload needed.