Create an OAuth application

An app can sign its users in at your issuer only after it is registered there. That registration is an OAuth application. It gives the app a client_id, the redirect URIs the issuer accepts and, optionally, the roles that may sign in. This page registers one at an issuer that runs OAuth Server, and picks its type.

The other side of the sign-in depends on the app:

• A browser or mobile app uses Auth in client mode.
• A web app with its own server uses Auth in server mode.

Pick the application type

An application is confidential or public. The type is fixed when the application is created. Why the two exist is on Public and confidential applications.

• PKCE with S256 is mandatory for both types. A request without code_challenge_method=S256 is a 400.
• A public application has no secret at all. The server stores a throwaway hash and never shows it.
• A client_secret sent to a public application is refused, with 401 invalid_client. It is not ignored.
• A confidential application without its secret gets 401 invalid_client on every token and revoke request.
• Client mode is public by design. A production build that embeds NUXT_PUBLIC_AUTHENTICATION_CLIENT_CLIENT_SECRET fails.
• The type cannot be changed afterwards. Register a new application instead.

Create it in the admin area

Use the admin area for a confidential application, or for a public one that does not need the same client_id in every environment.

1. Open OAuth applications in the Settings group of the admin sidebar (/admin/oauth). Choose Add application.
2. Pick the Client type: Confidential or Public.
3. Fill in the Name, which the consent screen shows.
4. Fill in the Website URL: the origin of the app, without a path, such as https://app.example.com. Use http only for localhost. A confidential application needs it. A public application needs it or at least one redirect URI, so a native app can leave it empty and list its callback under Redirect URIs.
5. Fill in the Redirect URIs. See Redirect URIs.
6. Optional: a Preview URL pattern, such as https://*.vercel.app. It accepts the callback path on preview deployments, where * is one hostname label.
7. Set the Allowed roles. Leave them empty to let every signed-in user in, or list the roles that may. They are the roles of authorization.roles (including inherited and auto ones), plus any your app adds in the authorization:roles hook.
8. Optional: Login URL, Description, Icon, Priority and Tags. The Login URL is where the Open button of the user's application list goes, and it defaults to the website URL. Priority orders that list.
9. Choose Add application.

A row's menu has Edit application, Copy client ID, Disable application, New client secret, Sign everyone out and Delete application. Disable application sets isActive to false.

Create it in nuxt.config

oauthServer.clients defines public applications in config. These are configured clients. Use them when:

• the app ships with its client_id compiled in, such as a mobile app, an SPA or a starter, and the id must be the same in every environment;
• the registration should be versioned with the app.

Ids are free-form, such as mobile or com.example.app. app_… is reserved for applications created in the admin area.

export default defineNuxtConfig({
  oauthServer: {
    cors: { paths: ['/api/'] },
    clients: [
      {
        // Mobile (Capacitor): custom-scheme redirect, webview origins for CORS.
        id: 'bills-mobile',
        name: 'Bills (mobile)',
        redirectUris: ['nu.frigear.bills:/auth/callback'],
        // Accepted under `nuxt dev` only.
        devRedirectUris: ['http://localhost:3001/auth/callback'],
        corsOrigins: ['capacitor://localhost', 'https://localhost'],
      },
      {
        // Web SPA: the origin is taken from the redirect URI.
        id: 'bills-web',
        name: 'Bills (web)',
        redirectUris: ['https://bills.example.com/auth/callback'],
        devRedirectUris: ['http://localhost:3000/auth/callback'],
      },
    ],
  },
})

• Other fields. websiteUrl, description, icon, allowedRoles, tags and corsOrigins. See CORS. The full table is on Configured clients.
• Runtime override. NUXT_OAUTH_SERVER_CLIENTS, as JSON, replaces the list at runtime.
• The stored row. The row is created on the first OAuth request, and the config wins on every read.
• In the admin area. The application shows Managed in nuxt.config. Staff can disable it and change its priority and login URL. Any other change, or a delete, is 409 managed_by_config.
• Turning it back. Remove the entry from config to turn it into an ordinary application.
• Id clashes. An id that already belongs to a confidential application is ignored, with a warning in the server log.

Redirect URIs

The server accepts a redirect_uri only when it is an exact string match of one of these. No prefixes, wildcards, query strings or fragments.

• The website URL plus callbackPath, which defaults to /auth/frigear. This applies to applications created in the admin area. Configured clients do not get it implicitly: list every URI.
• An entry of Redirect URIs (redirectUris, at most 20). It is https, or http for localhost, 127.0.0.1 and [::1]. Loopback is matched exactly, so list the port you use.
• The Preview URL pattern, for web redirects.

Native redirects are for public applications only. A confidential application is limited to https and loopback.

• A native redirect is a private-use scheme with one slash, such as nu.frigear.bills:/auth/callback, with the app id in lowercase.
• A webview origin also works, such as capacitor://localhost/auth/callback.
• Web schemes, javascript:, data:, file:, credentials and fragments are rejected.

devRedirectUris exist for configured clients only. For an application created in the admin area, add the localhost URI to Redirect URIs.

Scopes, consent and roles

An access token is a scope of what the user may do, never more. Four things decide what an application gets:

• Named scopes. A scope is one word (tickets) that stands for permissions. Define it in config, or add it in the admin area (Scopes, in the Settings group). A named scope never holds a sensitive or sessionOnly permission.
  nuxt.config.ts (the issuer)

  oauthServer: {
    scopes: [
      { name: 'tickets', label: 'Your tickets', permissions: ['tickets:read', 'tickets:write'] },
    ],
  }
  

  
  Scopes defined in config or by a module are read-only in the admin area (409 managed_by_config). When a stored scope grows, its version is bumped and users are asked to consent again.
• Unknown scopes. A scope the server does not know is invalid_scope at /oauth/authorize, redirected back to the application once its redirect URI is trusted. On a refresh nothing is rejected: scopes the user can no longer grant are dropped silently. No scope means openid profile email.
• The role cap. roleScopes maps a role to the scopes, permissions or wildcards it may grant. A user's cap is the union over all their roles, inheritance included, and a role that is not listed contributes nothing. Unset, there is no cap beyond the user's permissions. Names must be configured roles; the build checks them.
  nuxt.config.ts (the issuer)

  oauthServer: {
    settings: {
      roleScopes: {
        admin: ['*'],
        user: ['openid', 'profile', 'tickets:read', 'tickets:write'],
      },
    },
  }
  

  
  It is a ceiling, not a default: a role listed there still only grants what the user could do.
• Wildcard scopes. An application gets * or resource:* only with wildcardScopes: true on it (default off). Sensitive permissions (:pii) are never covered by a wildcard, and sessionOnly permissions are never offered as scopes at all.
• The permissions claim. The access token carries the scopes, expanded and intersected with the user's permissions at issue. A resource server reads this claim (OAuth Resource) instead of looking up roles it does not have. A token never gains permissions later; it only loses them if the user does.
• Introspection. A resource server that cannot verify tokens locally calls POST /oauth/introspect (RFC 7662) with its client credentials. It authenticates as a confidential application and only gets an answer for tokens issued to it or for its audience: anything else is { "active": false }. The answer holds the live permissions, so a role change shows at once, not at expiry.
• Consent. Every sign-in shows the consent screen (/authorize) with the requested scopes. It cannot be skipped per application.
• Allowed roles. An application with roles refuses users who hold none of them: with 403 at the authorization request, and with access_denied at the token endpoint. Roles are resolved through the role provider, so assigned, inherited and auto roles all count. The check runs again on every refresh. So removing a role, or disabling the application, stops the next refresh.
• Refresh tokens. The server always issues one with a user grant. There is no offline_access scope: it is dropped as unsupported, so asking for it is harmless. Each refresh replaces the token, and using an old one revokes its whole family.
• Lifetimes. accessTokenTtl (default 900 s) and codeTtl (600 s) are server options. How long a refresh token lives is set per application (Session length in the admin area), else by the server's refreshToken option (30 days unused). The token response includes refresh_token_expires_in. See Session lifetimes.

Secrets

A confidential application's secret is shown once: in the modal after creating the application, and after New client secret. Only a hash is stored, so a lost secret is replaced, not recovered.

Access tokens already issued stay valid until they expire, after 15 minutes by default. To end one user's sessions, call revokeUserGrants(userId, applicationId?). See the OAuth Server helpers.

CORS for browser and Capacitor clients

Native redirects need no cross-origin requests (CORS). Two kinds of app do call the server from a browser on another origin, so CORS applies to them:

• the webview of a Capacitor app: capacitor://localhost on iOS, and https://localhost on Android;
• an SPA on another origin.

• An application created in the admin area adds no origins. List them in cors.origins.
• /oauth/authorize is never opened to CORS. It is a navigation, with cookies.
• Cookies never travel cross-origin. So session-only routes answer 401 to these apps.

Connect the app

A public application, in a browser or mobile app. Point Auth in client mode at the issuer. There is no secret option.

export default defineNuxtConfig({
  modules: ['@nuxt/ui', '@frigear-nu/auth'],
  authentication: {
    mode: 'client',
    client: {
      issuer: 'https://id.example.com',
      clientId: 'bills-mobile', // or app_… for an admin-created application
      scopes: ['openid', 'profile', 'email'], // must contain 'openid'
      discovery: false, // the Frigear OAuth server's own paths
      native: { scheme: 'nu.frigear.bills' }, // nu.frigear.bills:/auth/callback
    },
  },
})

A confidential application, in a web app with its own server. Use Sign in with frigear.nu (oauth.frigear), with the Client ID and secret from the modal. Create the application with the app's origin as the Website URL. <origin>/auth/frigear is then accepted without a Redirect URIs entry.

NUXT_FRIGEAR_SSO_URL=https://id.example.com
NUXT_FRIGEAR_SSO_CLIENT_ID=app_…
NUXT_FRIGEAR_SSO_CLIENT_SECRET=…

With both set, GET /auth/frigear signs users in at the issuer. The options are on Auth.

A service that only receives the tokens, such as an API behind the app, is not an OAuth application. It verifies the access token with OAuth Resource, and needs no application of its own.

For other issuers, and the full checklist of what the app needs, see Use your own OAuth server.

Troubleshooting

Next steps

• Signing keys – set up the key the issuer signs this application's tokens with.
• Routes and clients – look up every route and configured client field.
• Access control – how permissions, roles and scopes fit together.
• Identity – see how the app, the issuer and the resource server relate.