Auth Providers

Auth providers handle user authentication and access control for Studio. They determine who can log in and edit content.

Provider Comparison

Built-in Providers

GitHub

GitHub OAuth provides authentication with automatic Git access. Users who authenticate via GitHub can immediately push changes to the repository.

STUDIO_GITHUB_CLIENT_ID=<your_github_client_id>
STUDIO_GITHUB_CLIENT_SECRET=<your_github_client_secret>
# Optional: Restrict access to specific users
# STUDIO_GITHUB_MODERATORS=admin@example.com,editor@example.com

GitLab

GitLab OAuth provides authentication with automatic Git access. Users who authenticate via GitLab can immediately push changes to the repository.

STUDIO_GITLAB_APPLICATION_ID=<your_gitlab_application_id>
STUDIO_GITLAB_APPLICATION_SECRET=<your_gitlab_secret>
# Optional: Restrict access to specific users
# STUDIO_GITLAB_MODERATORS=admin@example.com,editor@example.com

Google

Google OAuth is ideal for non-technical users who don't have GitHub or GitLab accounts.

STUDIO_GOOGLE_CLIENT_ID=<your_google_client_id>
STUDIO_GOOGLE_CLIENT_SECRET=<your_google_client_secret>
STUDIO_GITHUB_TOKEN=<your_github_personal_access_token>
STUDIO_GOOGLE_MODERATORS=admin@example.com,editor@example.com

STUDIO_GOOGLE_CLIENT_ID=<your_google_client_id>
STUDIO_GOOGLE_CLIENT_SECRET=<your_google_client_secret>
STUDIO_GITLAB_TOKEN=<your_gitlab_personal_access_token>
STUDIO_GOOGLE_MODERATORS=admin@example.com,editor@example.com

SSO Server

SSO (Single Sign-On) allows you to authenticate users via a centralized authentication server like Nuxt Studio SSO. This is ideal for organizations managing multiple Nuxt Studio sites.

Key benefits:

• Single login: Users authenticate once and access all connected Studio sites
• GitHub token pass-through: When users login with GitHub on the SSO server, their GitHub token is automatically passed to Studio sites
• One GitHub OAuth client: You can use the same GitHub OAuth client for all Studio sites, reducing the number of OAuth clients you need to manage
• Preview URL support: The SSO server can handle preview URLs for the Studio sites with glob patterns
• Centralized user management: Manage OAuth clients and users in one place

STUDIO_SSO_URL=https://your-sso-server.com
STUDIO_SSO_CLIENT_ID=<your_client_id>
STUDIO_SSO_CLIENT_SECRET=<your_client_secret>

Custom Authentication

For complete control over authentication, you can implement your own auth logic (password forms, SSO, LDAP, etc.) using Studio's session utilities.

Personal Access Token Required

You must configure a Personal Access Token for repository operations based on the Git provider you are using.

# For GitHub repositories
STUDIO_GITHUB_TOKEN=<your_github_personal_access_token>

# For GitLab repositories
STUDIO_GITLAB_TOKEN=<your_gitlab_personal_access_token>

See Git Providers for instructions on creating a PAT.

Implementation Flow

1. Validate the user in your login handler using your preferred method (password, SSO, etc.)
2. Create the session by calling setStudioUserSession(event, user) with a StudioUserSession object
3. Handle logout by calling clearStudioUserSession(event) to clear the session

Required Session Fields

When calling setStudioUserSession, you must provide:

Example: Password-based Login

import { eventHandler, readBody, createError } from 'h3'
import { setStudioUserSession } from '#imports'

export default eventHandler(async (event) => {
  const { email, password } = await readBody<{ email?: string, password?: string }>(event)

  // ⚠️️ Implement your own secure validation logic here
  // This is a simplified example - use proper password hashing and validation
  const user = await validateCredentials(email, password)

  if (!user) {
    throw createError({
      statusCode: 401,
      message: 'Invalid credentials'
    })
  }

  await setStudioUserSession(event, {
    providerId: user.id,
    name: user.name,
    email: user.email,
    avatar: user.avatar || ''
  })

  return { ok: true }
})

Example: Logout Handler

import { eventHandler } from 'h3'
import { clearStudioUserSession } from '#imports'

export default eventHandler(async (event) => {
  await clearStudioUserSession(event)
  return { ok: true }
})

Redirecting After Login

After successfully setting the session, redirect users to your app root (/). Studio will automatically detect the session and activate for that user.

// After setStudioUserSession...
return sendRedirect(event, '/')

Advanced Options

Access Control with Moderators

You can restrict access to Studio by defining a whitelist of authorized users through the STUDIO_{PROVIDER}_MODERATORS environment variable.

# GitHub OAuth moderators
STUDIO_GITHUB_MODERATORS=admin@example.com,editor@example.com

# GitLab OAuth moderators
STUDIO_GITLAB_MODERATORS=admin@example.com,editor@example.com

# Google OAuth moderators (required)
STUDIO_GOOGLE_MODERATORS=admin@example.com,editor@example.com

The moderator list is a comma-separated list of email addresses. Only users with matching email addresses will be granted access.

Behavior by Provider

Custom Redirect URL

By default, Studio uses your deployment URL for OAuth callbacks. To customize the redirect URL:

# GitHub OAuth
STUDIO_GITHUB_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/github

# GitLab OAuth
STUDIO_GITLAB_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/gitlab

# Google OAuth
STUDIO_GOOGLE_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/google

Server Hooks

Studio provides Nitro hooks that allow you to execute custom logic during authentication events.

studio:auth:login

Called when a user successfully logs in to Studio. This hook receives the authenticated user and the current H3 event.

Payload:

Example Usage:

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('studio:auth:login', async ({ user, event }) => {
    console.log(`User ${user.email} logged in via ${user.provider}`)

    // ... Track login analytics
    // ... Notifications
    // ... Extra session management for custom auth
  })
})

studio:auth:logout

Called when a user logs out from Studio. This hook receives the user who logged out and the current H3 event.

Payload:

Example Usage:

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('studio:auth:logout', async ({ user, event }) => {
    // Log logout events
    console.log(`User ${user.email} logged out`)

    // ... Clean ressources
    // ... Notifications
    // ... Extra session management for custom auth
  })
})