OAuth Server

You have one app where people already have an account, and other apps that should use that same account: a mobile app, a partner site or a separate service. OAuth Server makes your app the issuer for them. The other apps send people here to sign in and get tokens back, and your app decides who may sign in where. If you only need people to sign in to this app itself, use Auth instead.

The module is @frigear-nu/oauth-server, a Nuxt module that speaks OAuth 2.0 and OpenID Connect (OIDC). It has no role model of its own. It follows the permissions and roles of Auth and Authorization: who may manage applications, which roles may sign in where and which scopes a user may hand to an application are all decided there.

What you get

• Pages.
  • The consent screen at /authorize, where a person allows an app to sign them in. On by default.
  • The signed-in user's applications at /account/applications. Opt-in.
• Admin area.
  • An OAuth applications screen at /admin/oauth to create, edit and disable applications, and an OAuth scopes screen at /admin/oauth/scopes to define scopes. Opt-in, and only with Admin.
  • Menu items in the account menu and the admin sidebar, with Menu. On when Menu is installed.
• Server routes.
  • The standard OAuth and OIDC endpoints: discovery, signing keys, authorize, token, revoke and userinfo. On by default.
  • Your own API accepts the access tokens these endpoints issue. On by default.
  • A staff API to manage applications and scopes. On by default. It needs the session-only oauth:managepermission, which the admin role gets by default.
  • Token introspection at POST /oauth/introspect (RFC 7662), for services that must ask the issuer what a token may do now. On by default.
  • A my-oauth-applications tool for MCP. Opt-in.
• Composables and helpers. Composables for the admin screen and the user's applications, and server helpers to create applications from code. See Helpers.
• Emails. None.

Quick setup

pnpm add @frigear-nu/oauth-server @frigear-nu/admin @frigear-nu/authorization @nuxthub/core

export default defineNuxtConfig({
  modules: ['@nuxthub/core', '@frigear-nu/admin', '@frigear-nu/authorization', '@frigear-nu/oauth-server'],
  authorization: {
    roles: {
      admin: { label: 'Admin', grant: ['*'] },
    },
  },
  oauthServer: {
    issuer: 'https://id.example.com',
    settings: {
      pages: { admin: true, applications: true },
    },
  },
})

Options

Options go under the oauthServer key.

issuer must be set explicitly behind a proxy.

keyId changes when you rotate the signing key.

accessTokenTtl should stay at 5 to 15 minutes when other services accept the tokens. Those services cannot revoke a token. They can only stop a refresh. The module warns at startup when an audience is set and the lifetime is over 900 seconds.

refreshToken is the default for applications without their own session length. Each application can set its own in the admin area (Session lifetimes).

accessTokenAudience is for tokens that other services accept. ID tokens keep the client_id as their audience.

scopes is where you name scopes. Pass a string, or an object { name, label?, description?, icon?, service?, permissions? }. A single word such as tickets is a named scope that stands for its permissions. A permission such as vouchers:read only describes that permission on the consent screen and groups it under its service. Modules add named scopes with addScope from @frigear-nu/auth/utils, and staff add more in the admin area. Add claims for a scope with the oauth:claims hook. See Scopes.

settings.roleScopes caps what each role may hand to an application, as scopes, permissions or wildcards. A user's cap is the union over all their effective roles. A role that is not listed adds nothing. Role names are checked at build time. See Capping scopes by role.

cors.origins never takes *. The origins of configured clients are added for you. See Public applications.

cors.paths takes prefixes such as ['/api/']. See Calling from a browser on another origin.

clients defines applications in config instead of in the admin area. See Configured clients.

settings.pages.admin is registered only when Admin is installed.

Runtime config

Keys are secrets, so they are set through runtime config, not module options.

oauthServer.corsOrigins helps when the origins differ per environment, such as the dev server of a mobile app.

oauthServer.clients is validated when the first OAuth request needs it. An invalid list answers 500 not_configured.

oauthServer.previousPublicKeys is { "<kid>": "<SPKI PEM>" }, or the same object as a JSON string.

Signing keys

A missing or malformed signing key answers 500 with "The OAuth server signing keys are not configured." Signing keys covers generating, storing and rotating the key.

Module pages

Next steps

• Create an OAuth application – register the first app that signs in here.
• Scopes – decide what applications may ask users for.
• Hooks – add claims, veto access and audit tokens.
• Authorization – roles and permissions, which decide who manages applications and what users may grant.
• Identity – see where OAuth Server sits next to Auth, Mobile and OAuth Resource.
• OAuth Resource – let a separate service accept this issuer's access tokens.