Social Login

Overview

Social Login lets users authenticate with third-party identity providers (Google, GitHub, Apple, etc.). The SDK supports two modes:

• Popup — Opens a popup window for the provider’s login page. The main window stays open.
• Redirect — Redirects the entire page to the provider. Requires a callback page to complete the flow.

Popup Login

The simplest approach — opens a popup, completes authentication, and returns the result:

const { data, error } = await auth.social.loginWithPopup('google');

if (error) {
  console.error('Social login failed:', error.message);
  return;
}

console.log('User:', data.user);
console.log('Session:', data.session);

The popup is managed by the SDK. When the user completes authentication at the provider, the popup closes automatically and the promise resolves.

Supported Providers

type SocialProvider = 'google' | 'github' | 'apple' | 'microsoft' | 'facebook' | string;

The built-in provider identifiers returned by the SDK are google, github, apple, microsoft, and facebook. Custom external providers configured in the Authrim Admin panel can also be used by their string identifier when the backend is configured for them.

// Check which providers are configured
const providers = auth.social.getSupportedProviders();
// ['google', 'github', 'apple', 'microsoft', 'facebook']

Popup Options

interface SocialLoginOptions {
  /** Redirect URI after authentication */
  redirectUri?: string;
  /** Additional OAuth scopes */
  scopes?: string[];
  /** Custom state parameter */
  state?: string;
  /** Login hint (e.g., email address) */
  loginHint?: string;
  /** Popup window features */
  popupFeatures?: {
    width?: number;
    height?: number;
  };
}

// Example: request additional scopes
await auth.social.loginWithPopup('google', {
  scopes: ['profile', 'email'],
  loginHint: '[email protected]',
});

Redirect Login

For environments where popups are blocked (some mobile browsers), use redirect mode:

// Step 1: Redirect to provider (this navigates away from your page)
await auth.social.loginWithRedirect('github');

// Step 2: Handle callback in your callback page (callback.html)
if (auth.social.hasCallbackParams()) {
  const { data, error } = await auth.social.handleCallback();
  if (!error) {
    window.location.href = '/';  // Redirect to home
  }
}

Callback Page Setup

Create a callback page (e.g., callback.html) that handles the provider’s redirect:

import { createAuthrim } from '@authrim/web';

const auth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
});

// Check if this is a social login callback
if (auth.social.hasCallbackParams()) {
  const { data, error } = await auth.social.handleCallback();

  if (error) {
    document.getElementById('error').textContent = error.message;
  } else {
    // Success — redirect to home or dashboard
    window.location.href = '/';
  }
} else {
  // Not a social callback — might be an OAuth/SSO callback
  // See Cross-Domain SSO docs for handling trySilentLogin callbacks
}

Register the callback URL (https://yourapp.com/callback.html) in the Authrim Admin panel’s client settings as an allowed redirect URI.

Popup vs Redirect

Feature	Popup	Redirect
User experience	Stays on page	Navigates away
Mobile support	May be blocked	Always works
Implementation	Single call	Two-step (redirect + callback)
State preservation	App state preserved	App state lost (use storage)

Note

Popup mode provides a smoother user experience on desktop browsers but may be blocked on mobile. Redirect mode works in all environments. Consider using redirect as the primary mode for mobile-first applications, or implement popup with redirect fallback.

Error Handling

Common social login errors:

Error Code	Meaning	User Action
AR004001	Provider not configured	Check Admin panel settings
AR004002	Popup blocked	Use redirect mode or prompt user to allow popups
AR004003	User denied consent	Allow retry
AR004004	Provider error	Show error message, offer retry
AR004005	Callback validation failed	Check callback URL configuration
AR004006	Token exchange failed	Retry or check backend provider configuration

const { data, error } = await auth.social.loginWithPopup('google');

if (error) {
  if (error.code === 'AR004002') {
    // Popup blocked — fall back to redirect
    await auth.social.loginWithRedirect('google');
  } else {
    showMessage(error.message);
  }
}

Complete Example

import { createAuthrim } from '@authrim/web';

const auth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
});

// Render available providers
const providers = auth.social.getSupportedProviders();

providers.forEach(provider => {
  const button = document.createElement('button');
  button.textContent = `Sign in with ${provider}`;
  button.addEventListener('click', async () => {
    button.disabled = true;

    const { data, error } = await auth.social.loginWithPopup(provider);

    if (error) {
      if (error.code === 'AR004002') {
        // Popup blocked — try redirect
        await auth.social.loginWithRedirect(provider);
        return;
      }
      alert(error.message);
    } else {
      window.location.href = '/dashboard';
    }

    button.disabled = false;
  });

  document.getElementById('social-buttons').appendChild(button);
});

Next Steps

• Passkey Authentication — WebAuthn-based passwordless login
• Email Code Authentication — OTP-based login
• Session Management — Working with sessions after login
• Cross-Domain SSO — SSO across multiple domains