Social Authentication

Social login for web apps (redirect-first OAuth) and native mobile apps (token verification).

Web Apps:

• Start: NAuthClient.loginWithSocial()
• Callback: if exchangeToken exists, call NAuthClient.exchangeSocialRedirect()
• Angular: use socialRedirectCallbackGuard

Native Mobile Apps:

• Use @capgo/capacitor-social-login plugin (recommended)
• Verify tokens with NAuthClient.verifyNativeSocial()

Supported providers

Provider	Web OAuth	Native token verify
Google	Yes	Yes
Apple	Yes	Yes
Facebook	Yes	Yes

Requirements

• Backend must implement the redirect-first endpoints. See Social Login (backend).
• Frontend must configure redirect routes in NAuthClientConfig and optionally override endpoints in NAuthEndpoints.

Frontend (web)

Start login

await client.loginWithSocial('google', { returnTo: '/auth/callback', appState: '12345' });

Options: SocialLoginOptions

Handle callback

• cookies mode: backend sets httpOnly cookies before redirecting; callback URL typically has appState only
• json/hybrid (and cookies-with-challenge): callback URL includes exchangeToken; frontend exchanges it

Angular

// app.routes.ts
import { Routes } from '@angular/router';
import { socialRedirectCallbackGuard } from '@nauth-toolkit/client-angular';

export const routes: Routes = [
  {
    path: 'auth/callback',
    canActivate: [socialRedirectCallbackGuard],
    loadComponent: () => import('./auth-callback/auth-callback.component').then((m) => m.AuthCallbackComponent),
  },
];

Vanilla JS/TS

const params = new URLSearchParams(window.location.search);
const exchangeToken = params.get('exchangeToken');

if (exchangeToken) {
  const response = await client.exchangeSocialRedirect(exchangeToken);
  // Route based on response.challengeName or success
}

Frontend (Native Mobile)

For Capacitor and React Native apps, use native SDKs to get tokens and verify them with the backend.

Recommended Plugin

@capgo/capacitor-social-login is the recommended plugin for native social authentication in Capacitor apps. It provides:

• Unified API for Google, Apple, and Facebook
• Works on both iOS and Android
• Native SDK integration (no web views)
• TypeScript support
• Active maintenance

Installation

npm install @capgo/capacitor-social-login @nauth-toolkit/client
npx cap sync

Initialize Plugin and SDK

Important: You must call initialize() before using any login methods.

import { SocialLogin } from '@capgo/capacitor-social-login';
import { NAuthClient } from '@nauth-toolkit/client';

// Initialize plugin
await SocialLogin.initialize({
  google: {
    webClientId: 'YOUR_GOOGLE_WEB_CLIENT_ID.apps.googleusercontent.com',
    iOSClientId: 'YOUR_GOOGLE_IOS_CLIENT_ID.apps.googleusercontent.com',
    mode: 'online', // 'online' returns user data, 'offline' returns only serverAuthCode
  },
  facebook: {
    appId: 'YOUR_FACEBOOK_APP_ID',
    clientToken: 'YOUR_FACEBOOK_CLIENT_TOKEN', // Required for iOS, optional for Android
  },
  apple: {
    clientId: 'YOUR_APPLE_CLIENT_ID',
    redirectUrl: 'https://your-app.com/auth/apple/callback', // Android only
  },
});

// Initialize nauth-toolkit client
const client = new NAuthClient({
  baseUrl: 'https://api.example.com/auth',
  tokenDelivery: 'json', // Mobile apps use JSON mode
  onAuthStateChange: (user) => {
    // Handle auth state changes
    console.log('User:', user);
  },
  onSessionExpired: () => {
    // Handle session expiration
    console.log('Session expired');
  },
});

await client.initialize();

Sign In with Google

try {
  // Get native token from plugin
  const result = await SocialLogin.login({
    provider: 'google',
    options: { scopes: ['email', 'profile'] },
  });

  // Type assertion needed - plugin types don't fully match runtime
  const googleResult = result.result as {
    idToken?: string;
    accessToken?: { token?: string } | string;
  };

  if (!googleResult?.idToken) {
    throw new Error('No ID token received from Google');
  }

  // Extract access token - can be an object with token property or a string
  const accessToken =
    typeof googleResult.accessToken === 'string' ? googleResult.accessToken : googleResult.accessToken?.token;

  // Verify with backend using SDK
  const authResponse = await client.verifyNativeSocial({
    provider: 'google',
    idToken: googleResult.idToken,
    accessToken,
  });

  // Handle response
  if (authResponse.challengeName) {
    // Handle challenge (MFA, email verification, etc.)
    console.log('Challenge:', authResponse.challengeName);
  } else {
    // Login successful - tokens are automatically stored by SDK
    console.log('User:', authResponse.user);
  }
} catch (error) {
  console.error('Google sign-in error:', error);
  // Handle error
}

Sign In with Facebook

try {
  const result = await SocialLogin.login({
    provider: 'facebook',
    options: { permissions: ['email', 'public_profile'] },
  });

  const facebookResult = result.result as {
    accessToken?: { token?: string } | string;
  };

  const accessToken =
    typeof facebookResult.accessToken === 'string' ? facebookResult.accessToken : facebookResult.accessToken?.token;

  if (!accessToken) {
    throw new Error('No access token received from Facebook');
  }

  const authResponse = await client.verifyNativeSocial({
    provider: 'facebook',
    accessToken,
  });

  if (authResponse.challengeName) {
    // Handle challenge
  } else {
    // Login successful
    console.log('User:', authResponse.user);
  }
} catch (error) {
  console.error('Facebook sign-in error:', error);
}

Sign In with Apple

const result = await SocialLogin.login({
  provider: 'apple',
  options: { scopes: ['email', 'name'] },
});

const appleResult = result.result as {
  idToken?: string;
  authorizationCode?: string;
};

const authResponse = await client.verifyNativeSocial({
  provider: 'apple',
  idToken: appleResult.idToken!,
  authorizationCode: appleResult.authorizationCode,
});

Platform Setup

Android: Requires MainActivity modification for Google Sign-In. The @capgo/capacitor-social-login plugin requires your MainActivity.java to implement ModifiedMainActivityForSocialLoginPlugin interface and handle Google login intents. See the plugin documentation for complete setup.

iOS: Requires URL schemes in Info.plist and AppDelegate.swift modifications. Configure URL schemes for Google and Facebook, and implement URL handling in AppDelegate. See the plugin documentation for complete setup.

Related

• Social Login (backend)
• NAuthClient.loginWithSocial() - Web redirect-first
• NAuthClient.verifyNativeSocial() - Native mobile
• NAuthClient.exchangeSocialRedirect() - Web callback
• SocialLoginOptions
• socialRedirectCallbackGuard
• Social Login (backend) - Backend setup including native mobile verify endpoints
• @capgo/capacitor-social-login - Plugin documentation