Hosted Login (Universal Login)

The Problem: Where Should the Login Form Live?

Every application that authenticates users must decide where the login form lives. There are three fundamental approaches, and the choice has profound security implications.

Embedded Login (the risky approach)

The application renders its own login form and collects credentials directly:

The credentials are entered on a different origin — one controlled entirely by the identity provider. Your application’s JavaScript cannot read the form fields, intercept keystrokes, or access the credentials in any way. The browser’s same-origin policy enforces this boundary automatically.

How It Works: The Complete Flow

Auris Hosted Login implements the OAuth2 Authorization Code flow with PKCE (RFC 7636). Here is the complete sequence, step by step.

Sequence Diagram

PKCE S256: Why It Matters

PKCE (Proof Key for Code Exchange) prevents authorization code interception attacks. The mechanism is simple but effective.

The Code Verifier and Code Challenge

Before initiating the flow, the client generates two values:

1. Code Verifier: A cryptographically random string (43-128 characters)
2. Code Challenge: BASE64URL(SHA256(code_verifier))

The client sends the code challenge (the hash) to the authorize endpoint. When exchanging the code for tokens, the client sends the raw code verifier. Auris recomputes SHA256(code_verifier) and verifies it matches the stored code challenge.

code_verifier:  "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
                           │
                     SHA-256 + Base64URL
                           │
                           ▼
code_challenge: "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

Why This Stops Interception

If an attacker intercepts the authorization code in the redirect URL (via a malicious app registered on the same URI scheme, a proxy, or browser history), they cannot exchange it. To exchange the code, they need the code_verifier — which was never transmitted through the browser URL. It was stored in the client’s memory and only sent directly to the token endpoint over HTTPS.

SHA-256 is a one-way function: given the code challenge, the attacker cannot reverse it to obtain the code verifier.

Session Management

Auris uses two server-side models to manage the hosted login flow:

OAuthSession

Created at step 3 when the user arrives at the authorize endpoint. Stored in the database and identified by an httpOnly cookie.

The OAuthSession tracks the user’s progress through the hosted login pages. It persists across the login page, the 2FA page (if triggered), and any social login redirects. If the user abandons the flow, the session expires and is cleaned up by a cron job.

AuthorizationCode

Created at step 9 after successful authentication.

The authorization code is consumed via an atomic Prisma transaction: the code is marked as used and deleted in the same database operation. If two requests attempt to use the same code simultaneously, only one succeeds — the other receives an error.

// Atomic single-use enforcement (simplified)
const code = await prisma.authorizationCode.update({
  where: {
    code: authCode,
    usedAt: null,  // Only succeeds if not yet used
  },
  data: {
    usedAt: new Date(),
  },
})
// If the code was already used, Prisma throws (record not found with usedAt: null)

Tenant Branding

Auris Hosted Login pages automatically adapt to the tenant’s brand configuration. Tenants configure branding in the Auris Console under Settings > Branding.

The hosted login pages read branding from the HostedAuthContext, which is resolved from the OAuthSession’s clientId → Application → Tenant chain:

The branding is applied purely with CSS custom properties, so the hosted pages render correctly regardless of the tenant’s color scheme. The Console includes a live preview so administrators can see the effect before publishing.

The Security Pipeline

Every authentication attempt through Hosted Login passes through the full Auris security pipeline. No layer can be bypassed — they execute sequentially, and any layer can block the request.

Each layer is independently configurable per tenant. A small startup might only have Keycloak auth enabled, while an enterprise tenant might have all nine layers active.

Social Login on Hosted Pages

Auris supports 9 social login providers on the hosted login pages:

When a tenant enables social providers in the Console, the hosted login page automatically shows the corresponding buttons. No changes are needed in the client application — social login is handled entirely within the hosted page.

SSO Detection via Email Domain

For tenants with Enterprise SSO (SAML 2.0 / OIDC federation) configured, the hosted login page can detect SSO domains automatically. When the user enters their email address:

1. The page calls GET /api/auth/sso/[email protected]
2. If the domain company.com is verified and linked to an SSO connection, the page shows a “Continue with SSO” button
3. Clicking it redirects through the SSO flow (Keycloak IdP brokering) instead of password authentication

This provides a seamless experience: users from SSO-enabled organizations are automatically directed to their corporate identity provider.

Comparison: Login Approaches

Code Example: Using the Auris SDK

The recommended way to integrate Hosted Login is through the Auris SDK. The SDK handles PKCE generation, state management, redirect handling, and token storage automatically.

JavaScript SDK (@auris/js)

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'your-tenant.auris.example.com',
  clientId: 'app_abc123',
  redirectUri: 'https://app.yourdomain.com/callback',
  autoRefresh: true,
})
 
// Initiate login — redirects to Hosted Login page
// Internally: generates code_verifier, computes S256 challenge,
// generates state, stores both in sessionStorage, redirects
await auris.loginWithRedirect()
 
// On the callback page (/callback) — exchange code for tokens
// Internally: validates state, extracts code from URL,
// sends code + code_verifier to token endpoint, stores tokens
const result = await auris.handleRedirectCallback()
 
console.log(result.user)
// {
//   id: 'usr_abc123',
//   email: '[email protected]',
//   firstName: 'Jane',
//   lastName: 'Doe',
//   roles: ['user'],
// }

React SDK (@auris/react)

import { AurisProvider, useAuris, AuthGuard } from '@auris/react'
 
// Wrap your app with AurisProvider
function App() {
  return (
    <AurisProvider
      domain="your-tenant.auris.example.com"
      clientId="app_abc123"
      redirectUri="https://app.yourdomain.com/callback"
    >
      <Router />
    </AurisProvider>
  )
}
 
// Use the hook in any component
function LoginButton() {
  const { loginWithRedirect, isAuthenticated, user, logout } = useAuris()
 
  if (isAuthenticated) {
    return (
      <div>
        <span>Welcome, {user.firstName}</span>
        <button onClick={() => logout()}>Logout</button>
      </div>
    )
  }
 
  return <button onClick={() => loginWithRedirect()}>Login</button>
}
 
// Protect routes with AuthGuard
function ProtectedPage() {
  return (
    <AuthGuard>
      <Dashboard />
    </AuthGuard>
  )
}

Next.js SDK (@auris/nextjs)

// middleware.ts — protect routes at the Edge
import { aurisMiddleware } from '@auris/nextjs'
 
export default aurisMiddleware({
  protectedPaths: ['/dashboard', '/settings', '/admin'],
  publicPaths: ['/', '/about', '/pricing'],
  loginPath: '/auth/login',
})
 
export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}

// Server Component — check auth on the server
import { getSession } from '@auris/nextjs/server'
 
export default async function DashboardPage() {
  const session = await getSession()
 
  if (!session) {
    redirect('/auth/login')
  }
 
  return <h1>Welcome, {session.user.firstName}</h1>
}

Redirect URI Validation

Auris enforces strict redirect URI validation to prevent authorization code theft via open redirect attacks.

Rules

If the redirect_uri does not match a registered value, Auris returns an error page directly (it does not redirect to the mismatched URI, as that would defeat the purpose).

Why Exact Match?

Partial matching (e.g., prefix matching like https://app.example.com/) creates a vulnerability: an attacker could register https://app.example.com/evil-page and have authorization codes redirected there. Exact match eliminates this class of attack entirely.

Cleanup and Expiration

Auris runs a cron job (/api/oauth/cron/cleanup/) to clean up expired sessions and codes:

The cron runs periodically (configured in vercel.json) and ensures the database does not accumulate stale sessions from abandoned login flows.

Related Concepts

• PKCE Flow — Detailed walkthrough of the PKCE mechanism used by Hosted Login
• OAuth 2.0 & OIDC — The authorization framework Hosted Login implements
• Sessions & Token Rotation — How tokens are managed after Hosted Login completes
• Adaptive MFA & Risk Scoring — Risk-based step-up MFA during the login flow
• Actions & Sandboxed Execution — Custom logic hooks that run during Hosted Login
• Tokens Explained — The access, refresh, and ID tokens returned after login