Social Login Authentication

Social login authentication allows users to authenticate using OAuth providers like Google, Facebook, or custom providers through Auth0. There are two authentication flows available:

1. Redirect flow: Redirects the user to the provider’s login page and back to your application
2. Popup flow: Opens the provider’s login page in a popup window without leaving your application

Prerequisites

Before implementing social login in your application, you need to configure your Account Kit dashboard and application:

1. Follow the Setup Instructions in the Getting Started Guide:

   • See the Getting Started with Authentication page for complete setup instructions
   • Pay special attention to the social authentication provider configuration and whitelisted origins setup

2. Key Configuration Requirements:

   • Enable desired social providers in your Account Kit dashboard
   • Add your application’s domain to the whitelisted origins
   • Set enablePopupOauth: true in your config if using popup flow

Implementation Options

You can implement Social Login authentication in two ways:

• Pre-built UI Components - Quick implementation with minimal code
• Custom UI - Complete control over the user experience

Pre-built UI Components

Account Kit provides pre-built UI components that handle the entire Social Login authentication flow with minimal code.

Step 1: Add Authentication Components to Your Page

Before configuring your authentication, first add one of the pre-built components to your application:

Using Modal Authentication

To add authentication in a modal popup:

1
import React from "react";
2
import { useAuthModal } from "@account-kit/react";
3
4
export default function MyPage() {
5
  const { openAuthModal } = useAuthModal();
6
7
  return <button onClick={openAuthModal}>Sign in</button>;
8
}

For more details on modal configuration, see the Modal Authentication documentation.

Or:

Using Embedded Authentication

To embed authentication directly in your page:

1
import React from "react";
2
import { AuthCard } from "@account-kit/react";
3
4
export default function MyLoginPage() {
5
  return (
6
    <div className="flex flex-row p-4 bg-white border border-gray-200 rounded-lg">
7
      <AuthCard />
8
    </div>
9
  );
10
}

For more details on embedded authentication, see the Embedded Authentication documentation.

Step 2: Configure Social Login in UI Components

After adding the components, configure the Social Login authentication in your application config:

1
import { AlchemyAccountsUIConfig, createConfig } from "@account-kit/react";
2
import { sepolia, alchemy } from "@account-kit/infra";
3
4
const uiConfig: AlchemyAccountsUIConfig = {
5
  auth: {
6
    sections: [
7
      [
8
        // Include social login providers
9
        { type: "social", authProviderId: "google", mode: "popup" },
10
        { type: "social", authProviderId: "facebook", mode: "popup" },
11
        { type: "social", authProviderId: "apple", mode: "popup" },
12
      ],
13
    ],
14
  },
15
};
16
17
export const config = createConfig(
18
  {
19
    transport: alchemy({ apiKey: "your-api-key" }),
20
    chain: sepolia,
21
    // Required for popup flow
22
    enablePopupOauth: true,
23
  },
24
  uiConfig
25
);

Standard social login providers accept the following configuration:

1
type SocialAuthType = {
2
  type: "social";
3
  // For standard providers (google, facebook, apple)
4
  authProviderId: "google" | "facebook" | "apple";
5
  // Authentication mode (popup or redirect)
6
  mode: "popup" | "redirect";
7
  // Optional: Specifies the requested OAuth scope
8
  scope?: string;
9
  // Optional: Specifies additional claims to be included in the authentication token
10
  claims?: string;
11
};

You can find the full type definition in the Account Kit source code.

For more details on UI component customization, see the UI Components documentation.

Custom UI

If you need complete control over the user experience, you can implement your own custom UI for Social Login authentication using Account Kit hooks.

Step 1: Configure Your Application

Before implementing social login, make sure you’ve:

1. Set up your authentication providers in the Account Kit dashboard
2. If using popup flow, set enablePopupOauth: true in your Account Kit configuration

Step 2: Implement the Authentication

Create buttons or UI elements for each social provider you want to support:

1
import { useAuthenticate } from "@account-kit/react";
2
3
// Inside your component
4
const { authenticate, isPending } = useAuthenticate();
5
6
// For redirect flow
7
const handleGoogleRedirectLogin = () => {
8
  authenticate(
9
    {
10
      type: "oauth",
11
      authProviderId: "google",
12
      mode: "redirect",
13
      redirectUrl: "/", // Redirect to this page after authentication
14
    },
15
    {
16
      onError: (error) => {
17
        // Handle error
18
        // The page will redirect on success, so no need for onSuccess handler
19
      },
20
    }
21
  );
22
};
23
24
// For popup flow
25
const handleGooglePopupLogin = () => {
26
  authenticate(
27
    {
28
      type: "oauth",
29
      authProviderId: "google",
30
      mode: "popup",
31
    },
32
    {
33
      onSuccess: () => {
34
        // Authentication successful!
35
      },
36
      onError: (error) => {
37
        // Handle error
38
      },
39
    }
40
  );
41
};

Step 3: Track Authentication Status

Use the useSignerStatus hook to determine if the user is authenticated:

1
import { useSignerStatus } from "@account-kit/react";
2
3
// Inside your component
4
const { isConnected } = useSignerStatus();
5
6
// You can use isConnected to conditionally render UI

Step 4: Handle Redirect (for redirect flow)

If you’re using the redirect flow, you need to handle the redirect when the user returns to your application:

1
import { useEffect } from "react";
2
import { useSignerStatus } from "@account-kit/react";
3
4
// Inside your component
5
const { isAuthenticating } = useSignerStatus();
6
7
// Show loading state during authentication
8
useEffect(() => {
9
  if (isAuthenticating) {
10
    // Show loading UI while authentication completes
11
  }
12
}, [isAuthenticating]);

Next Steps

Enabling Authenticator App (TOTP) MFA

If you want to require a second factor for Social Login, see Social Login with Multi-Factor Authentication. Once users have set up a TOTP-based authenticator app, they’ll be prompted for their 6-digit code automatically.