---
title: "External OAuth Providers"
description: "Set up OAuth login with Google, GitHub, and other providers"
canonical_url: "https://wpnuxt.com/auth/headless-login"
---
# 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

```text
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

<table>
<thead>
  <tr>
    <th>
      Feature
    </th>
    
    <th>
      External OAuth
    </th>
    
    <th>
      miniOrange OAuth
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Token type
    </td>
    
    <td>
      WPGraphQL JWT
    </td>
    
    <td>
      miniOrange token
    </td>
  </tr>
  
  <tr>
    <td>
      Viewer query
    </td>
    
    <td>
      ✅ Works
    </td>
    
    <td>
      ❌ Not compatible
    </td>
  </tr>
  
  <tr>
    <td>
      Avatar
    </td>
    
    <td>
      ✅ Available
    </td>
    
    <td>
      ❌ Limited
    </td>
  </tr>
  
  <tr>
    <td>
      Roles
    </td>
    
    <td>
      ✅ Available
    </td>
    
    <td>
      ❌ Limited
    </td>
  </tr>
  
  <tr>
    <td>
      WordPress plugin
    </td>
    
    <td>
      Headless Login
    </td>
    
    <td>
      miniOrange Server
    </td>
  </tr>
</tbody>
</table>

## WordPress Setup

### 1. Install Headless Login for WPGraphQL

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

1. Install [Headless Login for WPGraphQL](https://github.com/AxeWP/wp-graphql-headless-login)
2. Go to **GraphQL → Settings → Headless Login**
3. Enable desired providers (Google, GitHub, etc.)

### 2. Configure Provider (Example: Google)

In the Headless Login settings:

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Client ID
    </td>
    
    <td>
      From Google Cloud Console
    </td>
  </tr>
  
  <tr>
    <td>
      Client Secret
    </td>
    
    <td>
      From Google Cloud Console
    </td>
  </tr>
  
  <tr>
    <td>
      Redirect URI
    </td>
    
    <td>
      <code>
        https://your-nuxt-app.com/api/auth/provider/google/callback
      </code>
    </td>
  </tr>
</tbody>
</table>

<callout type="info">

Each provider has different setup requirements. Consult the [Headless Login documentation](https://github.com/AxeWP/wp-graphql-headless-login/wiki) for provider-specific configuration.

</callout>

### 3. Get Provider Credentials

**Google OAuth:**

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing
3. Enable the Google+ API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URI: `https://your-app.com/api/auth/provider/google/callback`

**GitHub OAuth:**

1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Create a new OAuth App
3. Set callback URL: `https://your-app.com/api/auth/provider/github/callback`

## Nuxt Configuration

```typescript [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
      }
    }
  }
})
```

<callout type="tip">

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

</callout>

## Usage

### Login Page with Provider Buttons

```vue [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>
```

### Check User After Login

```vue [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

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

  // Fetch available providers from WordPress
  fetchHeadlessLoginProviders,

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

### HeadlessLoginProvider Type

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

### Available Providers

Headless Login for WPGraphQL supports:

<table>
<thead>
  <tr>
    <th>
      Provider
    </th>
    
    <th>
      Enum Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Google
    </td>
    
    <td>
      <code>
        GOOGLE
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      GitHub
    </td>
    
    <td>
      <code>
        GITHUB
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Facebook
    </td>
    
    <td>
      <code>
        FACEBOOK
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      LinkedIn
    </td>
    
    <td>
      <code>
        LINKEDIN
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Instagram
    </td>
    
    <td>
      <code>
        INSTAGRAM
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Generic OAuth2
    </td>
    
    <td>
      <code>
        OAUTH2_GENERIC
      </code>
    </td>
  </tr>
</tbody>
</table>

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

### User data missing after login

- 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

<table>
<thead>
  <tr>
    <th>
      Feature
    </th>
    
    <th>
      Headless Login (Recommended)
    </th>
    
    <th>
      miniOrange
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Token Type
    </td>
    
    <td>
      WPGraphQL JWT
    </td>
    
    <td>
      Custom token
    </td>
  </tr>
  
  <tr>
    <td>
      WPGraphQL Compatible
    </td>
    
    <td>
      ✅ Yes
    </td>
    
    <td>
      ❌ No
    </td>
  </tr>
  
  <tr>
    <td>
      Full User Data
    </td>
    
    <td>
      ✅ Yes
    </td>
    
    <td>
      ❌ Limited
    </td>
  </tr>
  
  <tr>
    <td>
      External Providers
    </td>
    
    <td>
      ✅ Google, GitHub, etc.
    </td>
    
    <td>
      ❌ WordPress only
    </td>
  </tr>
  
  <tr>
    <td>
      Config Location
    </td>
    
    <td>
      WordPress only
    </td>
    
    <td>
      Both WordPress + Nuxt
    </td>
  </tr>
  
  <tr>
    <td>
      Free Version
    </td>
    
    <td>
      ✅ Full features
    </td>
    
    <td>
      ⚠️ Limited
    </td>
  </tr>
</tbody>
</table>

<callout type="success">

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

</callout>


## Sitemap

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