---
title: "Auth Providers"
description: "Configure authentication providers to control access to Nuxt Studio."
canonical_url: "https://nuxt.studio/auth-providers"
---
# Auth Providers

> Configure authentication providers to control access to Nuxt Studio.

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

<note>

Auth providers are different from [Git providers](https://nuxt.studio/git-providers). Auth providers handle user authentication, while Git providers handle repository operations.

</note>

## Provider Comparison

<table>
<thead>
  <tr>
    <th>
      Feature
    </th>
    
    <th>
      GitHub OAuth
    </th>
    
    <th>
      GitLab OAuth
    </th>
    
    <th>
      Google OAuth
    </th>
    
    <th>
      SSO Server
    </th>
    
    <th>
      Custom Auth
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Authentication
      </strong>
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Git Operations
      </strong>
    </td>
    
    <td>
      ✅ Automatic (OAuth token)
    </td>
    
    <td>
      ✅ Automatic (OAuth token)
    </td>
    
    <td>
      ⚠ Requires PAT
    </td>
    
    <td>
      ✅ Automatic (SSO token)
    </td>
    
    <td>
      ⚠ Requires PAT
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Access Control
      </strong>
    </td>
    
    <td>
      ✅ OAuth scope
    </td>
    
    <td>
      ✅ OAuth scope
    </td>
    
    <td>
      ⚠ Moderator whitelist
    </td>
    
    <td>
      ✅ SSO server
    </td>
    
    <td>
      ⚠ Custom logic
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Secured Auth Flow
      </strong>
    </td>
    
    <td>
      ✅ Provider-managed
    </td>
    
    <td>
      ✅ Provider-managed
    </td>
    
    <td>
      ✅ Provider-managed
    </td>
    
    <td>
      ✅ SSO-managed
    </td>
    
    <td>
      ⚠ Self-managed
    </td>
  </tr>
</tbody>
</table>

<note>

You can use multiple providers simultaneously. For example, use GitHub OAuth for developers and Google OAuth for non-technical content editors.

</note>

## Built-in Providers

<tip>

Once deployed with the appropriate credentials set as environment variables, Studio will be accessible from your production instance. Navigate to `/_studio` (or your configured route) to start editing and publishing content.

</tip>

### GitHub

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

<steps level="4">

#### Navigate to GitHub Developer Settings

Go to [GitHub Developer Settings](https://github.com/settings/developers) and click **New OAuth App**

#### Configure the GitHub OAuth Application

Fill in the required fields:

- **Application name**: Your app name
- **Homepage URL**: `https://yourdomain.com`
- **Authorization callback URL**: `https://yourdomain.com/__nuxt_studio/auth/github`

<note>

For local development, add: `http://localhost:3000/__nuxt_studio/auth/github`

</note>

#### Copy Your GitHub Credentials

After creating the OAuth app, you'll receive:

- A **Client ID** (visible immediately)
- A **Client Secret** (click **Generate a new client secret**)

#### Set GitHub Environment Variables

Add the GitHub OAuth credentials to your deployment platform's environment variables or `.env` file:

```bash [.env]
NUXT_STUDIO_AUTH_GITHUB_CLIENT_ID=<your_github_client_id>
NUXT_STUDIO_AUTH_GITHUB_CLIENT_SECRET=<your_github_client_secret>

# Optional: Restrict access to specific users
# NUXT_STUDIO_AUTH_GITHUB_MODERATORS=admin@example.com,editor@example.com

# Optional: GitHub entreprise server
NUXT_STUDIO_AUTH_GITHUB_INSTANCE_URL=https://gh-ent.com
```

</steps>

### GitLab

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

<steps level="4">

#### Navigate to GitLab Applications

Go to your GitLab [User Settings → Applications](https://gitlab.com/-/user_settings/applications) (or your group/organization settings) and create a **New Application**.

#### Configure the GitLab OAuth Application

Fill in the required fields:

- **Application name**: Your app name
- **Redirect URI**: `https://yourdomain.com/__nuxt_studio/auth/gitlab`
- **Scopes**: Select `api` (required for publication)

<note>

For local development, add: `http://localhost:3000/__nuxt_studio/auth/gitlab`

</note>

#### Copy Your GitLab Credentials

After creating the OAuth application, you'll receive:

- An **Application ID** (visible immediately)
- A **Secret** (visible immediately)

#### Set GitLab Environment Variables

Add the GitLab OAuth credentials to your deployment platform's environment variables or `.env` file:

```bash [.env]
NUXT_STUDIO_AUTH_GITLAB_APPLICATION_ID=<your_gitlab_application_id>
NUXT_STUDIO_AUTH_GITLAB_APPLICATION_SECRET=<your_gitlab_secret>

# Optional: Restrict access to specific users
# NUXT_STUDIO_AUTH_GITLAB_MODERATORS=admin@example.com,editor@example.com

# Optional: Self hosted GitLab server
NUXT_STUDIO_AUTH_GITLAB_INSTANCE_URL=https://gh-ent.com
```

</steps>

### Google

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

<steps level="4">

#### Navigate to Google Cloud Console

Go to [Google Cloud Console](https://console.cloud.google.com/) and select or create a project, then navigate to **APIs & Services → Credentials**.

#### Create OAuth Application

Click **Create Credentials** and **OAuth client ID** and select **Web application** as the application type.

Fill in the required fields:

- **Name**: Your app name
- **Authorized redirect URIs**: `https://yourdomain.com/__nuxt_studio/auth/google`

<note>

For local development, add: `http://localhost:3000/__nuxt_studio/auth/google`

</note>

After creating the OAuth client, you'll receive:

- A **Client ID**
- A **Client Secret**

<warning>

Save these credentials immediately; you may not be able to view them again.

</warning>

#### Create a Personal Access Token

Since Google doesn't provide Git access, you must also configure a [Personal Access Token](https://nuxt.studio/git-providers#creating-a-personal-access-token) for repository operations.

#### Set Environment Variables

Add the Google OAuth credentials, your personal access token and moderator list:

<tabs>
<tabs-item icon="i-lucide-github" label="With GitHub Repository">

```bash [.env]
NUXT_STUDIO_AUTH_GOOGLE_CLIENT_ID=<your_google_client_id>
NUXT_STUDIO_AUTH_GOOGLE_CLIENT_SECRET=<your_google_client_secret>
NUXT_STUDIO_GIT_GITHUB_TOKEN=<your_github_personal_access_token>
NUXT_STUDIO_AUTH_GOOGLE_MODERATORS=admin@example.com,editor@example.com
```

</tabs-item>

<tabs-item icon="i-lucide-gitlab" label="With GitLab Repository">

```bash [.env]
NUXT_STUDIO_AUTH_GOOGLE_CLIENT_ID=<your_google_client_id>
NUXT_STUDIO_AUTH_GOOGLE_CLIENT_SECRET=<your_google_client_secret>
NUXT_STUDIO_GIT_GITLAB_TOKEN=<your_gitlab_personal_access_token>
NUXT_STUDIO_AUTH_GOOGLE_MODERATORS=admin@example.com,editor@example.com
```

</tabs-item>
</tabs>

<warning>

The `NUXT_STUDIO_AUTH_GOOGLE_MODERATORS` environment variable is **required** for Google OAuth. Only users with email addresses in this list can access Studio.

</warning>
</steps>

### SSO Server

SSO (Single Sign-On) allows you to authenticate users via a centralized authentication server like [Nuxt Studio SSO](https://github.com/nuxt-content/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

<steps level="4">

#### Deploy the SSO Server

Deploy [Nuxt Studio SSO](https://github.com/nuxt-content/nuxt-studio-sso) to your preferred platform (Vercel, Cloudflare, etc.).

#### Register Your Site as an OAuth Client

1. Login to the SSO server dashboard
2. Create a new OAuth client with your site's URL
3. Copy the **Client ID** and **Client Secret**

#### Set Environment Variables

Add the SSO credentials to your deployment platform's environment variables:

```bash [.env]
NUXT_STUDIO_AUTH_SSO_SERVER_URL=https://your-sso-server.com
NUXT_STUDIO_AUTH_SSO_CLIENT_ID=<your_client_id>
NUXT_STUDIO_AUTH_SSO_CLIENT_SECRET=<your_client_secret>
```

<note>

The callback URL is automatically set to `https://yourdomain.com/__nuxt_studio/auth/sso`

</note>
</steps>

<tip>

When users authenticate with GitHub on the SSO server, their GitHub access token is automatically passed through to Studio. This means commits are made with the user's own GitHub identity, and no shared PAT is needed.

</tip>

## Custom Authentication

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

<warning title="Security Responsibility">

When using custom authentication, **you are fully responsible for securing your authentication flow**. Studio only manages the session after you authenticate the user.

</warning>

### Personal Access Token Required

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

```bash [.env]
# For GitHub repositories
NUXT_STUDIO_GIT_GITHUB_TOKEN=<your_github_personal_access_token>

# For GitLab repositories
NUXT_STUDIO_GIT_GITLAB_TOKEN=<your_gitlab_personal_access_token>
```

See [Git Providers](https://nuxt.studio/git-providers#creating-a-personal-access-token) 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:

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      Display name for the user
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        email
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      User's email address
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        providerId
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      ❌
    </td>
    
    <td>
      Unique identifier for the user
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        avatar
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      ❌
    </td>
    
    <td>
      URL to user's avatar image
    </td>
  </tr>
</tbody>
</table>

### Example: Password-based Login

```ts [server/api/studio/login.ts]
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

```ts [server/api/studio/logout.ts]
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.

```ts [server/api/studio/login.ts]
// 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 `NUXT_STUDIO_AUTH_{PROVIDER}_MODERATORS` environment variable.

```bash [.env]
# GitHub OAuth moderators
NUXT_STUDIO_AUTH_GITHUB_MODERATORS=admin@example.com,editor@example.com

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

# Google OAuth moderators (required)
NUXT_STUDIO_AUTH_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

<table>
<thead>
  <tr>
    <th>
      Provider
    </th>
    
    <th>
      Moderator List
    </th>
    
    <th>
      Behavior
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      GitHub OAuth
    </td>
    
    <td>
      Optional
    </td>
    
    <td>
      If empty, all OAuth-authenticated users have access
    </td>
  </tr>
  
  <tr>
    <td>
      GitLab OAuth
    </td>
    
    <td>
      Optional
    </td>
    
    <td>
      If empty, all OAuth-authenticated users have access
    </td>
  </tr>
  
  <tr>
    <td>
      Google OAuth
    </td>
    
    <td>
      <strong>
        Required
      </strong>
    </td>
    
    <td>
      Without moderators, no one can access Studio
    </td>
  </tr>
  
  <tr>
    <td>
      Custom Auth
    </td>
    
    <td>
      N/A
    </td>
    
    <td>
      Implement your own access control logic
    </td>
  </tr>
</tbody>
</table>

<note>

For GitHub and GitLab OAuth, repository write access is still controlled by OAuth scopes, preventing unauthorized users from pushing changes even if they can access Studio.

</note>

### Custom Redirect URL

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

```bash [.env]
# GitHub OAuth
NUXT_STUDIO_AUTH_GITHUB_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/github

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

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

<note>

This is useful when you need to handle OAuth callbacks through a specific endpoint, such as behind a reverse proxy or with custom domain routing.

</note>

### 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:**

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        user
      </code>
    </td>
    
    <td>
      <code>
        StudioUser
      </code>
    </td>
    
    <td>
      The authenticated user object
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        event
      </code>
    </td>
    
    <td>
      <code>
        H3Event
      </code>
    </td>
    
    <td>
      The H3 event object from the current request
    </td>
  </tr>
</tbody>
</table>

**Example Usage:**

```ts [server/plugins/studio.ts]
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:**

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        user
      </code>
    </td>
    
    <td>
      <code>
        StudioUser
      </code>
    </td>
    
    <td>
      The user object who is logging out
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        event
      </code>
    </td>
    
    <td>
      <code>
        H3Event
      </code>
    </td>
    
    <td>
      The H3 event object from the current request
    </td>
  </tr>
</tbody>
</table>

**Example Usage:**

```ts [server/plugins/studio.ts]
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
  })
})
```


## Sitemap

See the full [sitemap](https://nuxt.studio/sitemap.md) for all pages.