Custom Social Providers with Auth0

In addition to the standard social login providers (Google, Facebook, Apple), Account Kit allows you to integrate custom OAuth providers through Auth0. This gives you flexibility to add authentication methods like GitHub, Twitter, LinkedIn, and more.

You can implement custom social providers 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 custom social provider 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: Setting Up Auth0

Before configuring the UI components, you need to set up Auth0:

1. Create or log in to an account on auth0.com

2. In the Auth0 dashboard, go to “Authentication → Social” in the sidebar

3. Click “Create Social Connection” and choose your desired provider (e.g., GitHub)

   

4. You can either use Auth0’s dev keys for testing or add your own credentials. If you want to add your own, click the link that says “How to obtain a Client ID” and follow the directions.

5. Select the attributes and permissions you’ll be requesting. It’s recommended to at least request the user’s email address as it can be useful for merging accounts from different providers later. Note that your users will be prompted for consent to share whatever information you request.

   

6. Note the “Name” field (e.g., “github”) - you’ll need this later for the auth0Connection parameter

7. Enable the connection for your Auth0 application

   

8. From your Auth0 dashboard, go to “Applications → Applications” in the sidebar

9. Select your application and note the “Domain”, “Client ID”, and “Client Secret”

   

10. Add these to your Account Kit dashboard in the embedded accounts auth config

    

    In addition to the “Client ID” and “Client Secret” fields, you must also fill in the “Auth0 Domain” field from the Auth0 dashboard.

Step 3: Configure Custom Social Providers in UI Components

After adding the components and setting up Auth0, configure the custom social providers 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
        // Standard social providers
9
        { type: "social", authProviderId: "google", mode: "popup" },
10
11
        // Custom social providers via Auth0
12
        {
13
          type: "social",
14
          authProviderId: "auth0",
15
          // Specify the Auth0 connection to use directly
16
          auth0Connection: "github",
17
          displayName: "GitHub",
18
          // Custom logo URL for the provider
19
          logoUrl:
20
            "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png",
21
          // Optional dark mode logo
22
          logoUrlDark:
23
            "https://github.githubassets.com/assets/GitHub-Mark-Light-ea2971cee799.png",
24
          mode: "popup",
25
        },
26
        {
27
          type: "social",
28
          authProviderId: "auth0",
29
          auth0Connection: "twitter",
30
          displayName: "Twitter",
31
          logoUrl: "https://path-to-twitter-logo.png",
32
          mode: "popup",
33
        },
34
      ],
35
    ],
36
  },
37
};
38
39
export const config = createConfig(
40
  {
41
    transport: alchemy({ apiKey: "your-api-key" }),
42
    chain: sepolia,
43
    // Required for popup flow
44
    enablePopupOauth: true,
45
  },
46
  uiConfig
47
);

Auth0 custom providers accept the following configuration:

1
type SocialAuthType = {
2
  type: "social";
3
  // For Auth0 custom providers
4
  authProviderId: "auth0";
5
  // Auth0-specific connection string (e.g., "github", "twitter")
6
  auth0Connection?: string;
7
  // Display name for the provider button
8
  displayName?: string;
9
  // URL for the provider's logo
10
  logoUrl: string;
11
  // URL for the provider's logo in dark mode (optional, `logoUrl` is used for both light & dark mode if not provided)
12
  logoUrlDark?: string;
13
  // Authentication mode (popup or redirect)
14
  mode: "popup" | "redirect";
15
  // Optional: Specifies the requested OAuth scope
16
  scope?: string;
17
  // Optional: Specifies additional claims to be included in the authentication token
18
  claims?: string;
19
};

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 custom social providers using Account Kit hooks.

Step 1: Set Up Auth0

Before implementing in your React app, you need to configure Auth0 as described in the Setting Up Auth0 section above.

Step 2: Implement Authentication in Your React App

Use the useAuthenticate hook to implement Auth0 authentication:

1
import { useAuthenticate } from "@account-kit/react";
2
3
// Inside your component
4
const { authenticate } = useAuthenticate();
5
6
// Option 1: Generic Auth0 login (shows Auth0 provider selection screen)
7
const handleAuth0Login = () => {
8
  authenticate(
9
    {
10
      type: "oauth",
11
      authProviderId: "auth0",
12
      mode: "popup", // or "redirect"
13
    },
14
    {
15
      onSuccess: () => {
16
        // Authentication successful!
17
      },
18
      onError: (error) => {
19
        // Handle error
20
      },
21
    }
22
  );
23
};
24
25
// Option 2: Direct provider login (bypasses Auth0 selection screen)
26
const handleGitHubLogin = () => {
27
  authenticate(
28
    {
29
      type: "oauth",
30
      authProviderId: "auth0",
31
      auth0Connection: "github", // Use the connection name from Auth0
32
      mode: "popup", // or "redirect"
33
    },
34
    {
35
      onSuccess: () => {
36
        // Authentication successful!
37
      },
38
      onError: (error) => {
39
        // Handle error
40
      },
41
    }
42
  );
43
};

Option 1 will take users to an Auth0 login page where they can choose the authentication method they want. Option 2 sends users directly to the specific provider’s login (like GitHub) without showing the Auth0 selection screen, which usually provides a better user experience.

The value passed to auth0Connection should match the string that appeared in the “Name” field of your auth provider connection in the Auth0 dashboard.

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