Strapi SSO & OAuth — Google, GitHub, Facebook, and Custom Providers

In this tutorial, you will learn how to configure single sign-on (SSO) for Strapi using OAuth providers like Google, GitHub, and Facebook, enabling users to log in with their existing social accounts instead of creating new credentials.

What You'll Learn

• How OAuth authentication works with Strapi
• How to configure Google as an authentication provider
• How to configure GitHub as an authentication provider
• How to configure Facebook as an authentication provider
• How to create custom OAuth providers
• How to handle provider tokens and user data mapping

Why It Matters

Password-based authentication creates friction. Users forget passwords, abandon registration forms, and hesitate to create yet another account. Social login removes this friction by letting users authenticate with accounts they already have. For many applications, offering social login can increase registration rates by 30-50%.

Real-World Use

A recipe sharing app wants to reduce sign-up friction. Instead of requiring email and password registration, they add "Sign in with Google" and "Sign in with GitHub" buttons. Users click once, authorize the app, and are logged in. The app receives the user's name, email, and profile picture from the provider, pre-populating the user profile.

Learning Path

flowchart LR
  A["Authentication"] --> B["SSO & OAuth
-- You are here"]:::current
  B --> C["Advanced Auth"]

  classDef current fill:#4945ff,color:#fff,stroke-width:2px

How OAuth Works in Strapi

OAuth is a delegation protocol. Instead of Strapi handling passwords, it delegates authentication to a trusted provider (Google, GitHub, Facebook).

OAuth flow:
1. User clicks "Sign in with Google"
2. Frontend redirects user to Strapi's OAuth endpoint
3. Strapi redirects to Google's authorization page
4. User approves the authorization request on Google
5. Google redirects back to Strapi with an authorization code
6. Strapi exchanges the code for an access token
7. Strapi uses the token to fetch the user's profile from Google
8. Strapi creates or finds a matching user account
9. Strapi returns a JWT to the frontend
10. Frontend uses the JWT for subsequent API requests

The user never gives their Google password to your application. They authorize your app on Google's domain, and Google tells Strapi "this user is authenticated."

Configuring Google Provider

To enable Google login, you need credentials from the Google Cloud Console.

# Step 1: Go to Google Cloud Console (console.cloud.google.com)
# Step 2: Create a new project or select existing
# Step 3: Enable the Google+ API or Google Identity Services
# Step 4: Go to Credentials > Create Credentials > OAuth Client ID
# Step 5: Set Application type to "Web application"
# Step 6: Add Authorized redirect URI:
#    http://localhost:1337/api/auth/google/callback

// Step 7: Configure Strapi provider
// config/plugins.js
module.exports = {
  "users-permissions": {
    config: {
      providers: {
        google: {
          enabled: true,
          clientId: process.env.GOOGLE_CLIENT_ID,
          clientSecret: process.env.GOOGLE_CLIENT_SECRET,
          redirectUri: "http://localhost:1337/api/auth/google/callback",
          icon: "google",
          scope: ["email", "profile"],
        },
      },
    },
  },
};

// Step 8: Frontend — redirect to Strapi's Google auth endpoint
// The user clicks "Sign in with Google"
window.location.href = "http://localhost:1337/api/connect/google";

Strapi handles the OAuth callback and returns a JWT. The frontend needs to capture this JWT from the URL after the redirect.

Configuring GitHub Provider

GitHub follows the same pattern but with slightly different configuration.

# Step 1: Go to GitHub Settings > Developer Settings > OAuth Apps
# Step 2: Click "New OAuth App"
# Step 3: Fill in:
#    Application name: Your App Name
#    Homepage URL: http://localhost:1337/admin
#    Authorization callback URL: http://localhost:1337/api/auth/github/callback
# Step 4: Register and copy Client ID and Client Secret

// config/plugins.js
module.exports = {
  "users-permissions": {
    config: {
      providers: {
        github: {
          enabled: true,
          clientId: process.env.GITHUB_CLIENT_ID,
          clientSecret: process.env.GITHUB_CLIENT_SECRET,
          redirectUri: "http://localhost:1337/api/auth/github/callback",
          icon: "github",
          scope: ["user:email"],
        },
      },
    },
  },
};

// Frontend — redirect to GitHub auth
window.location.href = "http://localhost:1337/api/connect/github";

GitHub returns the user's username, email (if public), and avatar URL.

Configuring Facebook Provider

# Step 1: Go to Facebook Developers (developers.facebook.com)
# Step 2: Create a new app or select existing
# Step 3: Add Facebook Login product
# Step 4: Configure OAuth redirect URI:
#    http://localhost:1337/api/auth/facebook/callback
# Step 5: Copy App ID and App Secret

// config/plugins.js
module.exports = {
  "users-permissions": {
    config: {
      providers: {
        facebook: {
          enabled: true,
          clientId: process.env.FACEBOOK_APP_ID,
          clientSecret: process.env.FACEBOOK_APP_SECRET,
          redirectUri: "http://localhost:1337/api/auth/facebook/callback",
          icon: "facebook",
          scope: ["email", "public_profile"],
        },
      },
    },
  },
};

Handling the OAuth Callback

After the OAuth provider redirects back to Strapi, the frontend needs to handle the callback URL.

// The OAuth callback returns to:
// http://localhost:1337/api/auth/{provider}/callback
// With a JWT in the response

// Frontend approach 1: Handle the redirect in your app
// Configure Strapi's server to redirect to your frontend after auth
// config/plugins.js:
{
  "users-permissions": {
    config: {
      jwt: {
        expiresIn: "7d",
      },
      providers: {
        callbackUrl: "http://localhost:3000/auth/callback",
      },
    },
  },
}

// Frontend approach 2: Parse the JWT from the URL
// The callback URL includes the JWT as a query parameter
function handleAuthCallback() {
  const urlParams = new URLSearchParams(window.location.search);
  const jwt = urlParams.get("access_token");
  if (jwt) {
    localStorage.setItem("strapi_jwt", jwt);
    window.location.href = "/dashboard";
  }
}

Custom Provider Configuration

You can create custom OAuth providers for services not included by default.

// config/plugins.js — Custom provider example (LinkedIn)
module.exports = {
  "users-permissions": {
    config: {
      providers: {
        linkedin: {
          enabled: true,
          clientId: process.env.LINKEDIN_CLIENT_ID,
          clientSecret: process.env.LINKEDIN_CLIENT_SECRET,
          redirectUri: "http://localhost:1337/api/auth/linkedin/callback",
          icon: "linkedin",
          scope: ["r_emailaddress", "r_liteprofile"],
        },
      },
    },
  },
};

Custom providers may require additional server-side code to map the provider's user data to Strapi's user fields. Check the Strapi documentation for provider-specific configuration.

User Data Mapping

Each OAuth provider returns different user data. Strapi maps this data to Strapi user fields:

// Default mapping:
// Google: email, name, picture -> email, username, avatar
// GitHub: email, login, avatar_url -> email, username, avatar
// Facebook: email, name, picture -> email, username, avatar

// The username may be auto-generated from the provider name
// if the user already exists with that username, Strapi appends a suffix

You can customize the mapping in the provider configuration or by extending the Users & Permissions plugin.

Common Mistakes

1. Incorrect redirect URIs. The redirect URI in your provider configuration must exactly match what is registered with the OAuth provider. A missing trailing slash or different protocol (http vs https) causes the OAuth flow to fail.

2. Not configuring the frontend callback URL. After OAuth authentication, Strapi redirects to its own callback URL, not your frontend. You must configure a frontend callback URL or handle the token from the Strapi callback URL.

3. Storing provider secrets in code. OAuth client secrets must be environment variables. Committing them to version control exposes them to anyone with access to the Repository.

4. Not handling cases where email is not provided. Some OAuth providers (GitHub) allow users to hide their email. Have a fallback — ask the user to provide an email or generate a placeholder.

5. Forgetting to test the full OAuth flow. OAuth involves redirects between three parties (your app, Strapi, the provider). Test the complete flow end-to-end. A broken redirect URI at any step breaks the authentication.

Practice Questions

1. What is the OAuth flow for social login in Strapi? Answer: User clicks social login button, redirects to Strapi, Strapi redirects to provider, user authorizes, provider redirects back to Strapi with code, Strapi exchanges code for token, creates/finds user, returns JWT to frontend.

2. What configuration is needed to add Google login to Strapi? Answer: Google OAuth credentials (Client ID, Client Secret) from Google Cloud Console, configured in Strapi's config/plugins.js under providers.google, and a registered redirect URI matching http://localhost:1337/api/auth/google/callback.

3. What happens when a user logs in with a social provider for the first time? Answer: Strapi creates a new user account with data from the provider (name, email, avatar) and assigns the default Authenticated role. The user does not need to register separately.

4. Challenge: Implement a complete social login system: (1) Register an OAuth app with Google and GitHub, (2) Configure both providers in Strapi, (3) Build a login page with "Sign in with Google" and "Sign in with GitHub" buttons, (4) Handle the OAuth callback and store the JWT, (5) Display the logged-in user's profile info (name, email, avatar from provider), (6) Handle the case where a user tries to connect a social account to an existing local account.

FAQ

Mini Project

Your task: Set up social login for a frontend application.

1. Register OAuth applications with Google and GitHub for development (localhost).
2. Configure both providers in Strapi's config/plugins.js.
3. Build a login page with social login buttons.
4. Implement the OAuth callback handler that extracts the JWT and redirects to a dashboard.
5. Test the complete flow: click social login button, authorize on provider's page, get redirected back, see the dashboard with user info.
6. Add error handling for cases where the user denies authorization or the OAuth flow fails.

What's Next

Now that you understand SSO and OAuth, proceed to Advanced Auth to learn about API tokens, Webhooks, and server-to-server authentication patterns for machine-to-machine communication.

Related lessons:

• REST API Security — Securing API endpoints
• Node.js OAuth — How OAuth works in Node.js
• WordPress OAuth — Compare OAuth implementations