Core Concepts

DarkAuth is easiest to understand as a standards-compatible authorization server with a stronger password and key-custody story than a typical login system. Applications can treat it as an OAuth 2.0 and OpenID Connect provider, but the user portal uses OPAQUE for password authentication and can optionally deliver client-scoped key material to trusted clients without storing that plaintext key material server-side.

Three audiences

DarkAuth separates responsibilities across three groups:

• Users authenticate, approve access, manage MFA, recover passwords, switch organizations, and launch apps.
• Admins configure the instance, clients, users, organizations, roles, permissions, email, branding, keys, and audit logs.
• Developers integrate applications through OIDC, the SDK, APIs, and token claims.

This separation is reflected in the product. The user portal and admin portal are different applications. Regular users and admin users are different account cohorts. The public authentication surface and management surface run on different ports.

OIDC compatibility

For applications, DarkAuth speaks familiar OAuth and OpenID Connect. A client redirects the user to /authorize, receives an authorization code, exchanges it at /token, and validates tokens using the issuer metadata and JWKS.

DarkAuth supports:

• Authorization Code flow.
• PKCE with S256.
• Public clients with no client secret.
• Confidential clients with client_secret_basic.
• Refresh tokens with rotation.
• Client credentials for service-to-service scenarios.
• Standard discovery and JWKS endpoints.

That means many applications can integrate without knowing about OPAQUE or zero-knowledge delivery at all.

OPAQUE password authentication

OPAQUE is a password-authenticated key exchange. In DarkAuth, the user and admin portals use OPAQUE so the password is not sent to the server during login. The server stores an OPAQUE record rather than a plaintext password or conventional password hash.

OPAQUE also gives the client an export key after successful authentication. DarkAuth uses that client-side material to unlock a password envelope in the user’s keybag. The server does not receive the export key or the unwrapped account root key.

Account and app key delivery

Some applications need user-held key material to decrypt application data. DarkAuth stores an Account Root Key, or ARK, inside a keybag. The keybag contains encrypted envelopes that can unwrap the ARK using password-derived material, passkey PRF output, trusted-device handoff material, or recovery keys.

For current ZK clients, the application sends an ephemeral public key in the authorization request. After the user authenticates, browser code unwraps the ARK locally, derives a Client App Key, or CAK, for the requesting client and organization context, encrypts that CAK to the ephemeral key as a compact JWE, and delivers it through the URL fragment. The server stores only a hash that lets the application verify that the fragment matches the authorization code.

Legacy v1 clients can still be configured to receive the older DRK-style root key delivery, but new clients should use v2 CAK delivery. This is not magic. The model still requires trusted JavaScript, trusted origins, and a safe browser environment. It is designed to keep the backend and database from seeing the password, export key, plaintext ARK, plaintext CAK, or plaintext app data during honest hosted-web operation.

Organizations and permissions

DarkAuth supports organization-scoped access. A user can belong to organizations, memberships can carry roles, and roles resolve to permissions. When an organization context is selected, tokens can include organization claims, roles, and effective permissions.

This is useful for SaaS-style applications where the same user may belong to multiple workspaces or customers. It also keeps application authorization logic explicit: the app can check org_id, roles, permissions, and scopes instead of guessing from user identity alone.

Sessions and tokens

DarkAuth has first-party sessions for its own portals and OAuth tokens for clients. The user portal uses HttpOnly cookies for its own session. OAuth clients receive ID tokens and optional access tokens through the token endpoint. Refresh credentials rotate and replay is rejected.

This distinction matters. A DarkAuth session means the user is signed into the authorization server. A token means a specific client has been granted access under a specific flow, scope, and organization context.

Two-port architecture

By default, DarkAuth uses:

• 9080 for the user portal and OIDC/user APIs.
• 9081 for the admin portal, install UI, and admin APIs.

This makes production routing easier to reason about. The user origin is the public identity surface. The admin origin is operational infrastructure and should be restricted, monitored, and protected more aggressively.