Socialite

Introduction

JCC Express MVC includes a Laravel-style Socialite package for OAuth login providers.

Entry point:

• Socialite.driver("provider")

Supported drivers in current source:

• google
• github
• facebook
• gitlab
• twitter
• slack

Basic flow

Social login uses two route steps:

1. redirect user to provider consent page
2. handle callback and fetch normalized profile

import { Socialite } from "jcc-express-mvc/Socialite";

export class OAuthController {
  redirectToGitHub() {
    return Socialite.driver("github").redirect();
  }

  async handleGitHubCallback() {
    const socialUser = await Socialite.driver("github").user();

    return {
      id: socialUser.getId(),
      email: socialUser.getEmail(),
      name: socialUser.getName(),
      avatar: socialUser.getAvatar(),
    };
  }
}

Sign in with Auth.socialLogin(userId)

After you get the provider profile from Socialite.driver(...).user(), resolve or create your local app user, then call:

import { Auth, Socialite } from "jcc-express-mvc";

export class OAuthController {
  async handleGoogleCallback() {
    const socialUser = await Socialite.driver("google").user();

    const user = await User.findOrCreate({
      where: { email: socialUser.getEmail() },
      defaults: {
        name: socialUser.getName(),
        email: socialUser.getEmail(),
      },
    });

    await Auth.socialLogin(user.id);
  }
}

Auth.socialLogin(userId) delegates to auth token issuing and response handling, similar to regular login completion.

Scopes API

Use fluent scope helpers before redirect():

Socialite.driver("github")
  .scopes("read:user", "user:email")
  .redirect();

Or replace scopes fully:

Socialite.driver("google")
  .setScopes(["openid", "profile", "email"])
  .redirect();

Environment configuration

Each provider reads config from env keys:

• {DRIVER}_CLIENT_ID
• {DRIVER}_CLIENT_SECRET
• optional {DRIVER}_REDIRECT_URI

Examples:

• GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
• GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET

Notes:

• if redirect URI is not set, Socialite builds one from APP_URL and default callback paths
• GitLab also supports GITLAB_URL for self-hosted instances

Session requirement

Socialite stores OAuth state (and PKCE verifier when needed) in jccSession.

That means your app must have session middleware enabled before calling:

• Socialite.driver(...).redirect()
• Socialite.driver(...).user()

Returned user object

user() returns a SocialUser object with identity/profile fields (not provider OAuth tokens).

Methods:

• getId()
• getEmail()
• getName()
• getAvatar()
• getRaw()
• toPlainObject()

Error behavior

OAuth failures throw SocialiteAuthError, for example:

• missing provider config
• missing/invalid authorization code
• invalid or expired OAuth state
• missing access token in provider response