Auth client mode

Client mode signs people in from an app without its own server, such as a browser single-page application (SPA) or a Capacitor app: at an issuer, with PKCE (Proof Key for Code Exchange), and with tokens the app keeps and refreshes itself. This page is for app developers; client mode only, with the same app code and Authorization guards as server mode.

Quick setup

pnpm add @frigear-nu/auth @frigear-nu/authorization
# inside a Capacitor app also:
pnpm add @capacitor/app @capacitor/browser @capacitor/preferences @aparajita/capacitor-secure-storage

export default defineNuxtConfig({
  modules: ['@nuxt/ui', '@frigear-nu/auth', '@frigear-nu/authorization'],
  authentication: {
    mode: 'client',
    client: {
      issuer: 'https://frigear.nu',
      clientId: 'my-app',
      scopes: ['openid', 'profile', 'email', 'offline_access'], // must contain 'openid'
      apiBase: 'https://api.example.com', // default: the issuer
      native: { scheme: 'com.example.app' }, // redirect URI com.example.app:/auth/callback
    },
  },
  routeRules: {
    '/**': { authenticated: true },
  },
})

<script setup lang="ts">
const { user } = useUserSession()
const { logout } = useAuth()
const { data: bills } = await useApi<Bill[]>('/api/bills')
</script>

The mode

Client mode checks the app when it builds:

The openid check also covers runtimeConfig.public.authentication.client.scope, and an environment override is checked again when the client starts. The modules that install Users are server mode only: Account, Events, Payments, Subscriptions and Preferences.

Options

Options go under the authentication key.

client.scopes. Add offline_access for refresh tokens where the provider needs it.

client.apiOrigins. Setting it replaces the default. Any other origin gets no token. The core's own client.fetch sends the token to these origins plus apiBase and the issuer.

client.onUnauthorized. 'signOut' signs out and goes to the sign-in page, then back afterwards. 'none' only throws.

client.native.scheme. The redirect URI is <scheme lowercase>:<callbackPath>. An invalid scheme, for example one with _, fails the build. Mobile fills it in from appId.

client.endpoints. Each is absolute or relative to the issuer. They win over discovery.

client.discovery. Discovery reads openid-configuration and falls back to RFC 8414 (OAuth server metadata). false uses the OAuth Server paths (/oauth/authorize, ...).

client.dev.rewriteLoopback. In development on a device, localhost in the issuer and apiBase becomes the host the app was loaded from. A string sets the host.

settings.pages.login. A string sets another path, false none.

The other settings (password, emailed links, passkeys, OAuth providers) are server mode only. In client mode every feature flag in runtimeConfig.public.authentication is false, so code that checks them works in both modes. useAuthPages() returns the sign-in path in both modes.

Sign-in page branding

Brand the sign-in page in app.config.ts:

export default defineAppConfig({
  authentication: {
    login: { title: 'Household bills', description: 'Sign in to continue.', logo: '/logo.svg', icon: 'i-lucide-wallet' },
  },
})

logo is an image path or { light, dark }. icon shows when there is no logo. The page strings are in the auth.client i18n namespace.

Runtime config

The runtime config is runtimeConfig.public.authentication.client. Your app's own values win over the module options.

• NUXT_PUBLIC_AUTHENTICATION_CLIENT_SECRET works as well as ..._CLIENT_CLIENT_SECRET.
• A list set in runtimeConfig.public.authentication.client (apiOrigins) replaces the module's.
• In a static build the values are baked in when it is generated.

Token storage

The client.storage option decides where tokens live.

A file path is relative to the app's rootDir, or names a package.

On a device, an install marker wipes tokens that survived a reinstall. The Capacitor plugins are optional peers: only the installed ones are imported.

App

const { ready, loggedIn, user, session, fetch, clear } = useUserSession()
const { status, authenticated, signingIn, login, completeLogin, logout, getAccessToken, isCallbackUrl, claims, getClient } = useAuth()
const { data } = await useApi<Bill[]>('/api/bills') // client only (`server: false`) by default
const me = await useNuxtApp().$api<Me>('/api/me')

useUserSession(). ready turns true once the stored tokens were read. loggedIn is true only when signed in and there is a user (see The user). session is { id, user }, where the id belongs to the sign-in and survives refreshes. clear() is logout({ redirect: false }), and openInPopup() throws.

useUserSession().fetch(). It maps the user again, with a fresh userinfo. It rejects when the mapping failed for a reason other than being offline; offline, it keeps the claims mapping.

useAuth(). status is unknown, signed-in or signed-out. login({ returnTo?, params? }) starts a sign-in and completeLogin(url?) finishes it. logout({ redirect? }) stays on the page with false and goes to a string. getAccessToken() refreshes when needed, and returns null when signed out or on the server. Only in client mode: claims (the ID token claims) and getClient() (the core client).

Pages without @nuxt/ui. Build your own with useAuth().login() and completeLogin().

user.id is the issuer's sub, a string. In server mode it is the local user's id. Code that runs in both modes treats user.id as opaque.

Inside a native app. The plugin completes sign-ins from the cold-start URL (App.getLaunchUrl()) and from appUrlOpen. Only callback URLs count: other deep links are left alone, and a link that answers no pending sign-in is ignored. The plugin refreshes the tokens on resume. A failed native sign-in goes to redirect.login with ?error=sign-in.

The user

The user comes from the ID token.

• A sign-in whose response has no valid ID token fails in completeLogin, and its tokens are discarded.
• A stored session without readable claims is signed out and fires auth:user-failed. Causes are a corrupt store, or another issuer or client.
• So loggedIn always means user !== null.

By default the user is mapped from the claims only, so a cold start offline still knows who is signed in:

{ id: sub, sub, name, email, avatar: picture }

Roles are not read from the token. What the user may do comes from the issuer: useAuthorization() asks its GET /api/auth/me/access with the access token, and falls back to the token's permissions claim. See Client mode.

client.userinfo: true merges the issuer's /userinfo response into that. client.mapUser maps the user yourself, and may be async:

import type { AuthClientUserContext } from '@frigear-nu/auth/client-core'

export default async ({ claims, userinfo, api }: AuthClientUserContext) => ({
  id: claims.sub,
  name: claims.name ?? '',
  avatar: (await userinfo()).picture as string | undefined,
})

authentication: { mode: 'client', client: { mapUser: './app/auth/map-user' } }

• userinfo() is fetched once per sign-in. It is fetched again after useUserSession().fetch() or after a refresh that changed the claims.
• userinfo() rejects a response whose sub is not the ID token's.
• api is $api. It works while a restored session is mapped at startup.
• Until an async mapping finishes, user is the claims mapping, so loggedIn never waits on the network.
• Mapping again within one sign-in keeps the previous result until the new one lands.
• A result that arrives after a sign-out or another sign-in is dropped.
• A failure fires auth:user-failed and leaves user at the claims mapping.
• A transient error is retried at the next refresh: offline, 429, 5xx, or a mapping that takes over 15 seconds.
• A 401 goes through onUnauthorized.

What the client knows about permissions is a hint for the interface, never access control. See Security.

Guards

Your app chooses which pages need a user, through Authorization, as in server mode. Nothing is protected by default.

routeRules: {
  '/**': { authenticated: true }, // signed in everywhere
  '/about': { authenticated: false }, // except here
},

• definePageMeta({ authorize: false }) opens one page.
• Auth's sign-in page and callback are exempt from less specific rules such as '/**', without a rule of yours.
• A rule of yours for that exact path, or a more specific one, still applies.
• In client mode the rules only decide what the app shows. The API decides what is allowed.

A visitor on a guarded page is sent to the sign-in path (client.redirect.login, by default the sign-in page) with the page in ?redirect=. Once signed in, they come back there. Authorization's redirectTo changes the target. redirectTo: false shows a 401 error instead.

Hooks

Your app listens to these runtime hooks on the client with useNuxtApp().hook(...). They exist in client mode only.

auth:signed-out. The session ends through logout, a rejected refresh token, the API refusing the tokens, or no identity. A stored session cleared at startup only fires auth:user-failed.

auth:user-failed. The causes are a stored session without identity (which is signed out), or a failed mapUser or userinfo mapping.

Security

Why a public application has no secret is explained in Identity.

Sign-in

• PKCE uses S256, with state, nonce and the iss check. There is no client secret.
• Pending sign-ins are keyed by state. So a forged callback is ignored and never cancels a real sign-in, and two tabs can sign in at once.
• An authorization response with a wrong iss is rejected (RFC 9207).

Tokens

• ID token checks. Auth checks iss, aud / azp, sub and nonce, not the device clock. A refreshed ID token that fails them keeps the previous claims. The rotated tokens are always stored.
• No signature check. The ID token comes straight from the token endpoint over TLS (OpenID Connect Core 3.1.3.7). Resource servers must verify access tokens themselves, as OAuth Resource does.
• Refresh rotation. One refresh runs at a time: single-flight in the page, Web Locks across tabs. The stored tokens are re-read under the lock, so a tab never reuses a rotated token. A refresh token that was not rotated is kept.
• Bearer tokens go to allowed origins only (client.apiOrigins).
• Redirects stay on this site. returnTo, redirect.afterLogin, redirect.afterLogout and logout({ redirect }) follow the shared rule in Redirects.

Errors

Every request to the issuer times out after 15 seconds. Errors come in four kinds:

Client secrets

• NUXT_PUBLIC_AUTHENTICATION_CLIENT_CLIENT_SECRET is for nuxt dev against a confidential application.
• allowClientSecretInBundle: true overrides the build check, for throwaway builds.
• Outside development, clientSecret is not declared at all, so a runtime environment variable cannot reach the bundle's config.

Without Nuxt

The framework-agnostic core, @frigear-nu/auth/client-core, works anywhere with fetch and WebCrypto:

import { createOAuthClient, webStorage } from '@frigear-nu/auth/client-core'

const client = createOAuthClient({
  issuer: 'https://frigear.nu',
  clientId: 'my-app',
  redirectUri: `${location.origin}/callback`,
  scope: 'openid offline_access',
  storage: webStorage(),
  attachTo: ['https://api.example.com'],
})
await client.authorize() // redirects
// on /callback:
const { returnTo } = await client.handleCallback(location.href)
const response = await client.fetch('https://api.example.com/me')

• The types of client-core include AuthClientUserContext.
• The adapters of capacitor are secureStorage, preferencesStorage, browserUserAgent and withInstallMarker.
• TokenStorage and AuthorizationUserAgent are the extension points for another secure storage, or for an ASWebAuthenticationSession user agent.

Next steps

• Mobile starter – a Capacitor app that already runs in client mode.
• OAuth Resource – verify the access token in the API your app calls.
• Authorization – the guards, in both modes.