Authentication

External OAuth Providers

Set up OAuth login with Google, GitHub, and other providers

Use Headless Login for WPGraphQL to enable OAuth authentication with external providers like Google, GitHub, Facebook, and more. This gives full WPGraphQL compatibility - OAuth users get the same data as password users (avatar, roles, etc.).

How It Works

1. User clicks "Sign in with Google"
         │
         ▼
2. Nuxt redirects to Google OAuth page
         │
         ▼
3. User authenticates with Google
         │
         ▼
4. Google redirects back with authorization code
         │
         ▼
5. Nuxt exchanges code for WPGraphQL JWT via WordPress
         │
         ▼
6. User is authenticated with full WPGraphQL access

Key Benefits

Feature	External OAuth	miniOrange OAuth
Token type	WPGraphQL JWT	miniOrange token
Viewer query	✅ Works	❌ Not compatible
Avatar	✅ Available	❌ Limited
Roles	✅ Available	❌ Limited
WordPress plugin	Headless Login	miniOrange Server

WordPress Setup

The same plugin used for password authentication also handles external OAuth providers.

Install Headless Login for WPGraphQL
Go to GraphQL → Settings → Headless Login
Enable desired providers (Google, GitHub, etc.)

2. Configure Provider (Example: Google)

In the Headless Login settings:

Field	Value
Client ID	From Google Cloud Console
Client Secret	From Google Cloud Console
Redirect URI	`https://your-nuxt-app.com/api/auth/provider/google/callback`

Each provider has different setup requirements. Consult the Headless Login documentation for provider-specific configuration.

3. Get Provider Credentials

Google OAuth:

Go to Google Cloud Console
Create a new project or select existing
Enable the Google+ API
Create OAuth 2.0 credentials
Add authorized redirect URI: https://your-app.com/api/auth/provider/google/callback

GitHub OAuth:

Go to GitHub Developer Settings
Create a new OAuth App
Set callback URL: https://your-app.com/api/auth/provider/github/callback

Nuxt Configuration

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@wpnuxt/core', '@wpnuxt/auth'],

  wpNuxt: {
    wordpressUrl: 'https://your-wordpress-site.com'
  },

  wpNuxtAuth: {
    providers: {
      password: { enabled: true },  // Optional fallback
      headlessLogin: {
        enabled: true
        // Providers are auto-discovered from WordPress
      }
    }
  }
})

No client secrets needed in Nuxt config! All OAuth credentials are stored securely in WordPress.

Usage

pages/login.vue

<script setup>
const {
  loginWithProvider,
  fetchHeadlessLoginProviders,
  hasHeadlessLoginAuth
} = useWPAuth()

// Fetch available providers from WordPress
const providers = ref([])
onMounted(async () => {
  if (hasHeadlessLoginAuth()) {
    providers.value = await fetchHeadlessLoginProviders()
  }
})

// Get icon for provider
function getProviderIcon(provider) {
  const icons = {
    GOOGLE: 'i-simple-icons-google',
    GITHUB: 'i-simple-icons-github',
    FACEBOOK: 'i-simple-icons-facebook'
  }
  return icons[provider] || 'i-lucide-log-in'
}
</script>

<template>
  <div class="login-page">
    <div v-for="provider in providers" :key="provider.provider">
      <button @click="loginWithProvider(provider.provider)">
        Sign in with {{ provider.name }}
      </button>
    </div>
  </div>
</template>

pages/profile.vue

<script setup>
const { user, isAuthenticated } = useWPAuth()
const { fetchUser, getAvatarUrl, hasRole } = useWPUser()

// Fetch full user data from WPGraphQL
onMounted(async () => {
  if (isAuthenticated.value) {
    await fetchUser()
  }
})
</script>

<template>
  <div v-if="user">
    <img :src="getAvatarUrl()" alt="Avatar" />
    <h1>{{ user.name }}</h1>
    <p v-if="hasRole('administrator')">Admin</p>
  </div>
</template>

API Reference

Composable Methods

const {
  // Check if Headless Login is enabled
  hasHeadlessLoginAuth,

  // Fetch available providers from WordPress
  fetchHeadlessLoginProviders,

  // Initiate login with a specific provider
  loginWithProvider
} = useWPAuth()

HeadlessLoginProvider Type

interface HeadlessLoginProvider {
  name: string           // e.g., 'Google'
  provider: string       // e.g., 'GOOGLE'
  authorizationUrl: string
  isEnabled: boolean
}

Available Providers

Headless Login for WPGraphQL supports:

Provider	Enum Value
Google	`GOOGLE`
GitHub	`GITHUB`
Facebook	`FACEBOOK`
LinkedIn	`LINKEDIN`
Instagram	`INSTAGRAM`
Generic OAuth2	`OAUTH2_GENERIC`

Troubleshooting

"Provider not found or not enabled"

Verify the provider is enabled in WordPress Headless Login settings
Check that the provider has valid Client ID and Secret configured
Ensure the redirect URI matches exactly

"Failed to authenticate with WordPress"

Check WordPress GraphQL endpoint is accessible
Verify the authorization code hasn't expired (10 min timeout)
Check WordPress error logs for detailed error messages

The login mutation returns full user data immediately
If using useWPUser().fetchUser(), ensure the auth token is valid
Check that the user exists in WordPress (first-time OAuth users are auto-created)

Comparison with miniOrange OAuth

Feature	Headless Login (Recommended)	miniOrange
Token Type	WPGraphQL JWT	Custom token
WPGraphQL Compatible	✅ Yes	❌ No
Full User Data	✅ Yes	❌ Limited
External Providers	✅ Google, GitHub, etc.	❌ WordPress only
Config Location	WordPress only	Both WordPress + Nuxt
Free Version	✅ Full features	⚠️ Limited

Recommendation: Use Headless Login for external OAuth providers. It provides the best compatibility with WPGraphQL and requires no secrets in your Nuxt configuration.

Edit this pageorReport an issue

OAuth Authentication

Set up OAuth2 login with miniOrange WP OAuth Server

MCP Server

AI-powered development with the WPNuxt MCP Server