Virtneu Auth Docs

OAuth and OpenID Connect

Sign in Web and native applications through the system browser with Authorization Code and PKCE.

Business OIDC authenticates users from the existing App user directory. A browser displays the business App name, signs in the user, asks for explicit consent, and returns a single-use code to the registered callback. Management MCP OAuth remains separate.

This page describes the repository protocol. Verify the selected deployment and its acceptance record before enabling an application. Documentation does not establish production rollout.

Configure a client

In Studio, select the App and its test or production environment, then choose OAuth clients and hosted login from the environment menu. In the Business application login section, choose Create OAuth client. App configuration write permission is required for creation and changes. A viewer can inspect configuration without modifying it.

ClientToken endpoint authenticationCallback
Native publicnone, with PKCE S256Registered reverse-domain custom scheme or associated HTTPS URL
Server Web confidentialclient_secret_basic, with PKCE S256Exact registered HTTPS URL

Public clients never have a client secret. Web secrets are shown once and belong in the backend's Secret store. Never use a service credential or platform key in browser or native code. Native test clients may register http://127.0.0.1:<port>/callback or IPv6 loopback for development; only the port may vary, while the address, path and query must match. Other HTTP callbacks and development loopback in production are rejected.

Each client belongs to exactly one App and environment. Use separate clients for Web, macOS and Windows, and separate test and production configuration. Client IDs are public identifiers and do not prove that an authorization request came from an official application.

Issuer and endpoints

Copy the complete Issuer shown in that Studio section. It combines the selected deployment's public API origin, App ID, and App environment. For example, on the production platform with an App's test environment:

https://auth-api.virtneu.com/oidc/<application-id>/test

BOE / PROD deployment targets are separate from the App's test / production environments. A named BOE uses its own API origin; do not reuse the production issuer or assume a shared BOE hostname. The issuer, client, user directory, signing key and grant context must all match.

For issuer I, discovery is I/.well-known/openid-configuration. It advertises I/authorize, I/token, I/userinfo, I/jwks, I/introspect and I/revoke. Use a maintained OIDC client library and validate discovery's exact issuer. Download the separate business OIDC OpenAPI contract; the backend SDK uses the separate /v1 backend contract.

Only Authorization Code and refresh grants are supported. PKCE S256 is required for both client types. Implicit, resource-owner password and client-credentials grants are unavailable. Public dynamic registration is closed.

Request and validate login

For every login, generate a new verifier, challenge, random state and nonce. Keep the verifier, state and nonce in a short-lived protected transaction. Open the discovery authorization endpoint with:

response_type=code
client_id=<your-client-id>
redirect_uri=<exact-registered-callback>
scope=openid profile email offline_access
code_challenge_method=S256
code_challenge=<derived-challenge>
state=<random-state>
nonce=<random-nonce>

offline_access is optional. The hosted page reuses existing business passwords, configured email-code sign-in or enabled Passkeys, account status and durable attempt limits. It completes the App/environment's business MFA policy before consent and code issuance. Users explicitly allow, deny or cancel. A known client ID never bypasses consent. Studio / Console MFA remains a separate management identity system.

Add login_method=passkey to /authorize to open the passkey sign-in view directly. This is a page preference: device verification, current MFA and explicit consent still apply, and other enabled sign-in methods remain available.

Understand the hosted prompts

ParameterAccepted valuesCurrent behavior
promptlogin, consent, login consent, consent loginEach authorization already creates a new login transaction and asks for explicit consent. These values skip neither step. prompt=none and silent login are unsupported and return login_required.
max_ageInteger seconds from 0 to 999999999Requests authentication freshness. The current host does not reuse a cross-transaction sign-in cookie, so each request authenticates again. It does not change the application's session lifetime or renew a session.
login_methodpasskeyOpens the passkey view; it cannot enable passkeys, prove device verification or satisfy MFA on its own. Other enabled sign-in methods remain accessible.

These are OIDC parameters, rather than an AI instruction prompt. The independent account-security-request body accepts only its five documented fields, so it does not accept any of these parameters. Repository examples/oidc-client.ts supports start(callback, true, {prompt:'login',maxAge:0,loginMethod:'passkey'}) while retaining new state, nonce and PKCE for the attempt.

At the callback, validate the saved transaction, callback location, state and issuer. Exchange the code with the original callback and verifier using a form-encoded token request. Native clients send client_id without a secret. Web backends use HTTP Basic and omit form client credentials. Reject repeated callbacks, expired transactions, denial and protocol errors.

Validate ID Token signature through JWKS, the allowed ES256 algorithm, exact issuer, the client ID audience, expiry, issued-at and nonce. Then call UserInfo and require its sub to match. The repository examples use oauth4webapi for these checks. Identify a user by (issuer, sub), rather than matching accounts by email across Apps.

ScopeAuthorized identity data
openidStable sub and ID Token; required
profileName and profile image
emailEmail and verification status
offline_accessA rotating refresh token, subject to the originating session and account safety state

The client registration and user consent both constrain returned data. Custom business scopes and arbitrary API resources are unavailable in this version. If resource is sent, it must exactly equal the selected issuer's /userinfo endpoint.

The hosted flow signs in existing users; it does not provide self-signup or automatically link matching emails across Apps. New-user provisioning continues through the existing registration API / SDK. sub is the Auth user_id from the selected App/environment directory, not external_user_id. Resolve existing mappings on the backend before migrating business ownership records.

Social sign-in

The selected App/environment can enable Google, GitHub and Apple under Social sign-in. Customers supply their own Client ID and write-only Client Secret in Studio and register the platform-generated provider callback URL with that provider. Apple uses a Services ID and an unexpired signed client-secret JWT; its developer private key stays with the customer. The provider callback returns to Auth, separately from your application's registered OIDC callback.

The hosted page completes provider authorization, then the same business MFA policy and explicit consent. Existing users sign in locally and connect providers through Account security after recent complete authentication. Equal email addresses never automatically merge accounts. First-time social identities require a verified provider email and no local conflict or deletion tombstone. Connection changes invalidate previous security versions and require signing in again.

Tenant migration 0018_business_social_login.sql is required in addition to 0017. Provider code exchange and ID-token verification use the pinned official Better Auth provider SDKs; isolated provider fixtures are not evidence of real Google/GitHub/Apple acceptance or production deployment.

Business MFA and Passkeys

In the selected App/environment's Authentication policy, choose mfa_mode (off, optional, required), passkeys_enabled and passkey_satisfies_mfa. Defaults are off, false and true. Customers decide whether a Passkey with verified device User Verification (UV) satisfies MFA or must be followed by TOTP/recovery-code verification. An enrolled user's TOTP remains enforced when the policy returns to off; that mode prevents first-time enrollment while allowing an enrolled user to replace an authenticator after recent complete authentication. These settings apply across the environment's clients.

The 0.6.0 runtime requires verified device UV for every passkey registration and login, including when passkey_satisfies_mfa is off. That setting adds the required second factor; it does not permit presence-only passkey authentication. Historical passkey sessions without UV are rejected. Existing credential keys and counters are retained, but a legacy key must complete a new UV login before it counts as a verified remaining MFA alternative when removing factors.

Account state when MFA is requiredNext step
No passkey or verified TOTPInitial enrollment; a passkey is offered only when enabled and its verified UV is accepted as MFA.
Verified TOTP already enrolledUse the authenticator or a remaining recovery code. Returning the policy to off does not bypass that factor.
Passkey exists, but no TOTP; password/email/social primary just succeededProve the existing passkey. That primary continuation cannot enroll a replacement passkey or TOTP.
Existing passkey was verified with UV, but it cannot alone satisfy the policyEnroll TOTP when no verified TOTP exists, or verify the enrolled TOTP/recovery code.
Passkey disabled and no usable alternative403 MFA_METHOD_UNAVAILABLE; no presence-only or password-only enrollment fallback is granted.

Hosted login handles the additional steps within the existing browser transaction. Keep the same issuer, callback, PKCE, state and nonce checks. First-time required enrollment can offer a passkey only when the account has no passkey or verified TOTP and the policy accepts its verified user verification as MFA. A password-only attempt cannot add a new factor in place of an existing passkey or TOTP. Account security manages authenticator enrollment/replacement, recovery-code replacement, and passkey creation, labels and removal. A user who signs in with a recovery code can choose Replace authenticator: the old factor stays valid until a new TOTP is confirmed atomically, then its old secret/codes and earlier sessions become invalid. Reading factor status and passkey lists needs a live complete session; changes still require a recent five-minute session. Hosted OIDC keeps the platform canonical RP/origin. SDK 0.7.0 separately supports embedded passkeys on a DNS-verified customer RP, with browser and Swift/Android adapters. It does not migrate hosted keys or change the hosted issuer.

The backend /v1 API and published SDK 0.7.0 also expose business factors. Their login/registration result can be HTTP 202 with an authentication_token and next_step; this is not a session or an OAuth token. Backend integrations must handle the continuation before creating an authenticated session. Completed continuation proofs are single-use: after an uncertain MFA/Passkey verification response, restart login instead of automatically retrying the proof. Verify the actual installed SDK version and use the matching API/schema; older packages do not acquire new methods when repository files change.

The 0.7.0 runtime requires reviewed tenant migrations through 0020_embedded_passkeys.sql, preserving the hosted credential metadata from 0019_passkey_management.sql and the factor schema from 0017_business_security_factors.sql. The independent account-security transaction also requires control-database migration 0042_business_account_security.sql. Review the new schema and pinned production publisher policy, apply the independently authorized DDL and verify migration/data receipts before deploying the matching runtime. Do not automatically expand the publisher's trust to unknown schemas. SDK 0.7.0 publication, registry consumer checks, schema migration and production activation have separate receipts. After an environment adopts business factors, do not roll back to a runtime that ignores MFA/session assurance checks. Local workerd, virtual-authenticator and software-signature tests do not establish physical authenticator, cross-device or deployed end-to-end acceptance.

The device picker and cross-device QR

The system authenticator or passkey manager creates the credential. Auth stores its public key and safe metadata; it never receives the private key, fingerprint or face data. A synchronized passkey may be available on another device through the user's credential provider; that does not mean Auth sends a private key to your backend.

Hosted WebAuthn uses the platform's canonical HTTPS RP/origin, such as production auth-api.virtneu.com. The picker may display that domain and an account label. The separate embedded route uses the customer's verified RP; it does not migrate hosted keys. App/environment credentials remain isolated even when the hosted RP is shared.

When supported by the browser and device, choose another device in the system picker and scan its QR with a phone that holds the passkey. This system-owned cross-device flow differs from the secret-bearing QR used to enroll a TOTP authenticator. Availability and labels vary by operating system and passkey manager; keep the enabled fallback methods visible.

Hosted custom issuers, seamless migration of existing RP credentials and cross-App SSO are not implemented. The 0.7.0 embedded integration offers customer RP configuration and native adapter sources; system-browser OIDC remains available. Physical Touch ID/Face ID/Windows Hello, security keys and cross-device sync need their own acceptance; a virtual CTAP2 authenticator or software signature is not that evidence.

Open account security from your app

Add an Account security action to your application's settings. A signed-in user can open this center after the original authorization has completed; no unfinished consent page is needed.

From your backend's same-origin, CSRF-protected POST, create a new protected attempt with the existing (issuer, sub), new state, nonce and PKCE verifier, the registered callback and a fixed settings return path. Send the current user's live OIDC access token in the Authorization header:

POST /oidc/<application-id>/<environment>/account-security-request
Authorization: Bearer <current-oidc-access-token>
Content-Type: application/json

{
  "redirect_uri": "https://your-app.example/callback",
  "state": "<new-random-state>",
  "nonce": "<new-random-nonce>",
  "code_challenge": "<new-S256-challenge>",
  "code_challenge_method": "S256"
}

State and nonce are required strings of 1–512 characters; the S256 challenge is 43 base64url characters. These are the only accepted body fields. The callback must match the token's current client registration. The user and granted scopes come from the live token; callers cannot supply another user, client, scope or return URL.

HTTP 201 returns native OIDC JSON, {url, expires_at}, without a /v1 data envelope. expires_at is the RFC3339 deadline to claim the URL within five minutes. A claimed center has a separate ten-minute window; retain callback state/nonce/verifier long enough for both windows. The example uses sixteen minutes from initiation. Check the URL against the configured issuer and /account-security path, then open it in the system browser. The URL carries a short-lived, single-use request token. Keep it out of logs, third-party resources and prefetching; the access token never belongs in a URL.

Claiming the URL checks the source grant again and requires fresh authentication of the pinned account. The center then has an independent protected browser transaction. Security changes invalidate the old sessions and grant security versions; the user signs in again to the same account and returns to the center. After claim, the old security version need not stay valid, but explicitly revoking the source connection terminates its unfinished center transaction. The transaction cannot switch accounts or revive the old grant. Changes to client revision or tenant generation, or disabling/deleting the target user or losing its verified email, fail closed.

Done explicitly returns a new authorization code, state and issuer to the fixed callback. Cancel returns error=access_denied, state and issuer. Either completes the transaction once. Validate the new state/issuer, exchange using this attempt's verifier, validate the new nonce and signature, and require ID Token/UserInfo sub to match the original account before atomically replacing the application's tokens and cookie. Return to the fixed settings page. An error or cancellation must not restore invalidated old credentials.

If the user cancels a device prompt, keep the current page and let them choose an available method; this does not authorize the account. An uncertain verification or factor-change response must not trigger an automatic retry. Reauthenticate and read the current list. If the center expires after a factor change invalidated the old connection, start a new application OIDC login before creating another settings request; the expired center URL and old token pair are not recovery credentials.

The repository's examples/oidc-account-security.ts and runnable examples/oidc-web.ts show this integration. Native public clients use the same request and a new PKCE attempt with their system-browser callback. There is no separate /v1 session-token bridge to this center; backend-only integrations retain their existing factor APIs and the fixed-RP browser requirement.

Tokens, refresh and revocation

The access token is opaque and lasts at most five minutes. ID Tokens are ES256 JWTs lasting at most five minutes, with aud equal to the client ID. An ID Token is proof of a completed login, not a business API access token. These tokens cannot replace a service credential, an existing session_token, or a management MCP token.

Refresh tokens rotate after each use. Serialize refreshes and atomically replace the stored pair. Replaying a spent token revokes its connection family; a timeout may mean the old token has already been consumed, so do not retry blindly. Refresh lifetime is at most 30 days and never exceeds the originating Auth session's absolute deadline. Online refresh also requires that session's current expiry to remain valid (seven days by default). Refreshing OAuth tokens does not renew that underlying session.

UserInfo, code exchange, refresh and introspection check current App/environment, client revision, grant, user security version, session and required MFA assurance. Account disable/delete, password or factor security-version changes, an unmet current MFA policy, disabled Passkeys for a Passkey-based session, session expiry/revocation, client edits/disablement and connection revocation invalidate online use. Re-enabling does not restore revoked user security versions or superseded OIDC client revisions. /revoke revokes the client-owned connection from a submitted token, including its access and refresh tokens.

The hosted consent page shows the authenticated identity and offers Manage my connections. Users can inspect and revoke their own connections for the current App/environment there. Each action requires the same protected browser transaction, a valid current session and same-origin submission.

An offline-verified ID Token can remain valid until expiry after a later revocation, for up to five minutes. For a current account check, call UserInfo with the access token or introspect from a confidential client of the same App/environment. An introspection consumer must also match issuer, audience, the expected client ID and scopes. Fail the current request on infrastructure errors; do not permanently delete the account because a check was unavailable.

Web, macOS and Windows

The repository contains examples/oidc-client.ts, examples/oidc-web.ts and examples/oidc-native.ts. They use pinned oauth4webapi and are checked with the repository examples. See the repository's docs/oidc.md for runnable configuration and the migration order.

The Web example redirects from /login, exchanges the code on the backend, validates ID Token and UserInfo, then gives the browser an HttpOnly, Secure, SameSite=Lax application session cookie. OAuth tokens and the client secret stay on the server. Put the demo backend behind the registered HTTPS origin; replace its in-memory stores with bounded shared storage before deployment.

The native example starts a loopback callback listener in the test environment and opens the system browser: open on macOS and the operating system URL handler on Windows. It validates the callback and closes the listener after completion or expiry. It does not embed a WebView or require a client secret. For a packaged application, use a registered custom scheme or associated HTTPS handler, restore the same login transaction on activation, and save refresh tokens in macOS Keychain or Windows Credential Locker. OS packaging and actual installed-app activation must be tested by the consuming application.

Auth owns identity and protocol tokens. An application backend owns business membership and permissions. For Mail, mailbox selection, mailbox membership and read/send permission remain in Mail; an identity access token does not grant any of them. The separate /v1 session protocol can continue independently; backend consumers must support authentication continuations before enabling the new MFA requirements.

The implementation follows OIDC Core, OIDC Discovery, RFC 8252, RFC 7636 and RFC 9700.

On this page