Application authentication

Use security.auth when your application needs a login boundary before project middleware or routes run. Veryfront uses declarative configuration for runtime auth, not an extension or a template-only integration. A scaffold can write the config and environment placeholders, but it does not own runtime behavior. Authelia, Microsoft Entra ID, AD FS, and other providers use the same surface. Veryfront speaks OpenID Connect to the provider, verifies the ID token, creates an encrypted application session, and exposes one normalized identity to middleware and routes.

Choose a mode

Use OIDC for user login in Veryfront Cloud and self-hosted deployments. Use trusted-proxy auth only when a self-hosted reverse proxy authenticates the user and asserts identity over a transport path the operator controls.

Need	Use
Authelia, Entra ID, AD FS, Keycloak, Authentik, Okta, or another OIDC provider	`security.auth.oidc`
Active Directory users	OIDC through Entra ID, AD FS 2019+, or another directory-backed identity provider
Existing app with its own routes	`veryfront generate auth <provider>` or the MCP scaffold, then review the config diff
Self-hosted proxy that already authenticates users	`security.auth.trustedProxy`
Per-route authorization rules	Middleware or route code that reads the normalized identity

Veryfront does not bind directly to LDAP, NTLM, or Kerberos in application code. Put Active Directory behind Entra ID, AD FS, or another OIDC provider, then connect Veryfront to that provider.

Configure OIDC

In veryfront.config.ts, add the OIDC mode and keep secrets in environment variables:

veryfront.config.ts

import { defineConfig } from "veryfront";

export default defineConfig({
  security: {
    auth: {
      oidc: {
        issuerEnvVar: "OIDC_ISSUER",
        clientIdEnvVar: "OIDC_CLIENT_ID",
        clientSecretEnvVar: "OIDC_CLIENT_SECRET",
        sessionSecretEnvVar: "VERYFRONT_AUTH_SESSION_SECRET",
        scopes: ["openid", "profile", "email", "groups"],
      },
    },
  },
});

Set the environment values in Cloud, CI, or your self-hosted runtime:

.env

APP_URL="https://<APP_HOST>"
OIDC_ISSUER="https://idp.example.com"
OIDC_CLIENT_ID="<OIDC_CLIENT_ID>"
OIDC_CLIENT_SECRET="<OIDC_CLIENT_SECRET>"
VERYFRONT_AUTH_SESSION_SECRET="<32_BYTE_OR_LONGER_RANDOM_SECRET>"

Set APP_URL to the exact public HTTPS origin for the deployment. Local direct loopback development can derive the origin from the request. Cloud, production, and proxied deployments require APP_URL. Generate the session secret with your deployment secret manager or an equivalent cryptographic random source. Give every horizontally scaled instance in one environment the same value. Rotate it as a coordinated deployment. Old sessions stop working after rotation.

Configure the provider

Provider redirect URI

https://<APP_ORIGIN>/_veryfront/auth/callback

Veryfront uses authorization code flow with PKCE and validates issuer, audience, authorized party, nonce, state, token signature, token age, and key type. Use a confidential client secret for server-side deployments. Providers such as Authelia support client_secret_basic. Configure that provider-side method when the provider asks how the client authenticates. For Authelia, use the Authelia issuer URL and a confidential OIDC client. For Microsoft Entra ID, use the tenant-specific issuer and register the exact redirect URI. For AD FS, use a version that supports OIDC authorization code flow and PKCE, or front Active Directory with Entra ID. If the provider publishes authorization, token, or JWKS endpoints on a different HTTPS origin from the issuer, list the canonical origins explicitly:

veryfront.config.ts

import { defineConfig } from "veryfront";

export default defineConfig({
  security: {
    auth: {
      oidc: {
        issuerEnvVar: "OIDC_ISSUER",
        clientIdEnvVar: "OIDC_CLIENT_ID",
        clientSecretEnvVar: "OIDC_CLIENT_SECRET",
        sessionSecretEnvVar: "VERYFRONT_AUTH_SESSION_SECRET",
        scopes: ["openid", "profile", "email"],
        trustedEndpointOrigins: ["https://idp-endpoints.example.com"],
      },
    },
  },
});

Self-hosted runtimes block outbound requests to private and loopback addresses by default. If the identity provider is on an internal network, allow only its exact origin in the host process:

Host environment

VERYFRONT_HOST_ALLOWED_INTERNAL_PROVIDER_ORIGINS="https://auth.internal.example.com"

This is an operator-owned host setting, not application configuration. List comma-separated exact origins when the provider uses more than one internal origin. Do not use the broad internal-egress override for application auth. If the provider uses a private CA, add its PEM certificate bundle to the host runtime trust settings. Use NODE_EXTRA_CA_CERTS for Node.js and Bun. Use DENO_CERT or deno --cert for Deno. Veryfront keeps certificate and hostname verification enabled and adds the private CA to the runtime’s normal trust roots. On Veryfront Cloud, expose the provider through a certificate chain the Cloud runtime already trusts. Changing clientId, claim mappings, scopes, signing algorithms, issuer, callback origin, or trustedEndpointOrigins invalidates existing sessions.

Handle routes and identity

Veryfront reserves these routes:

GET /_veryfront/auth/login
GET /_veryfront/auth/callback
POST /_veryfront/auth/logout

HTML navigations redirect to login. API requests receive a no-store 401. Logout requires POST and a same-origin Origin header. After a request is admitted, middleware and routes receive the same identity. The stable user key is (issuer, subject). Map that pair to your own user record before applying application authorization. When an API route sends identity data to a browser, return only the normalized fields that the UI needs. Do not return the raw provider claims object by default. Keep authorization decisions in server-side middleware or route code. Microsoft group overage does not become an empty group list. When a token says groups must be fetched elsewhere, Veryfront sets groupsComplete: false. Application authorization that depends on groups must treat incomplete groups as not enough information. Application sessions remain inside a bounded encrypted cookie. If raw provider claims do not fit, Veryfront keeps the stable identity, normalized email and name, normalized groups and roles when they fit, and only the protocol claims needed to validate the session. If the normalized groups and roles still do not fit, Veryfront clears both arrays and sets groupsComplete: false. Treat missing raw claims, groups, and roles as unavailable, never as authorization.

Add auth to an existing app

From your existing project root, run the scaffold:

Terminal

veryfront generate auth authelia

The scaffold writes a config fragment, environment placeholders, and provider setup notes. It does not rewrite application routes or middleware. If you use a coding agent through the Veryfront MCP server, ask it to scaffold type: "auth" and then inspect the diff. Keep authorization in your existing middleware or route layer. The scaffold adds the login boundary and identity normalization.

Deploy on Cloud or self-hosted infrastructure

OIDC works in Veryfront Cloud and self-hosted apps because login transaction state and application sessions are encrypted cookies. There is no sticky-session requirement, in-memory session store, database, or distributed cache in the request admission path. Each instance keeps its own bounded OIDC discovery and JWKS caches. These caches improve performance only. A cold instance can fetch provider metadata and keys independently, and key rotation converges without sharing process memory. For Cloud, keep auth config declarative. veryfront.config.ts can contain functions for general configuration, but hosted auth must resolve to a static security.auth shape. Do not put provider clients, network calls, token verification code, or request-specific auth logic in config. For self-hosted trusted-proxy auth, configure exact trusted native peer addresses and strip incoming identity headers at the proxy before setting the trusted values:

veryfront.config.ts

import { defineConfig } from "veryfront";

export default defineConfig({
  security: {
    auth: {
      trustedProxy: {
        trustedPeers: ["10.0.0.10"],
        headers: {
          subject: "x-auth-subject",
          email: "x-auth-email",
          groups: "x-auth-groups",
        },
      },
    },
  },
});

Trusted-proxy auth is not available in Veryfront Cloud. It trusts transport provenance, not Forwarded, X-Forwarded-For, or any caller-controlled header.

Review the security checklist

Use HTTPS provider endpoints. Allow insecure loopback only for local development.
Register the exact callback URI with the provider.
Allow only the provider’s exact internal origins in self-hosted runtimes.
Store OIDC_CLIENT_SECRET and VERYFRONT_AUTH_SESSION_SECRET as secrets.
Share one session secret across horizontally scaled instances in the same environment.
Use the minimum scopes your app needs. Keep openid.
Treat (issuer, subject) as the external identity key.
Treat groupsComplete: false as not authorized for group-dependent actions.
Treat missing claims, groups, and roles as unavailable for authorization.
Keep app authorization in middleware or routes after the Veryfront login boundary.
Rotate session secrets intentionally and expect existing sessions to be cleared.

Verify it worked

Start the app and open a protected route in a new browser session. An HTML route redirects to /_veryfront/auth/login, then returns to the original path after provider sign-in. Probe an API route without cookies:

Terminal

curl -i https://<APP_ORIGIN>/api/account

Expect 401 and Cache-Control: no-store. After sign-in, the same route sees the normalized identity in middleware or route code. For horizontal scaling, complete login on one instance and send the session cookie to another instance with the same VERYFRONT_AUTH_SESSION_SECRET. The second instance admits the request without sticky routing.

veryfront: defineConfig and public application types
veryfront/middleware: middleware request context

Getting Started

Concepts

Guides

API Reference

Application authentication

Choose a mode

Configure OIDC

Configure the provider

Handle routes and identity

Add auth to an existing app

Deploy on Cloud or self-hosted infrastructure

Review the security checklist

Verify it worked

Next

​Choose a mode

​Configure OIDC

​Configure the provider

​Handle routes and identity

​Add auth to an existing app

​Deploy on Cloud or self-hosted infrastructure

​Review the security checklist

​Verify it worked

​Next

​Related

Choose a mode

Configure OIDC

Configure the provider

Handle routes and identity

Add auth to an existing app

Deploy on Cloud or self-hosted infrastructure

Review the security checklist

Verify it worked

Next

Related