Configuring Social Connectors for Social Login with Logto: A Complete Implementation Guide

Logto implements social connectors as type-safe plugins that implement OIDC/OAuth2 protocols through a three-layer architecture consisting of the Connector Kit interface, Core orchestration layer, and Experience UI, enabling seamless integration with providers like Google, GitHub, and Facebook.

Configuring social connectors for social login with Logto requires understanding its modular architecture that cleanly separates connector contracts from runtime orchestration. The logto-io/logto repository provides a complete implementation where social authentication flows through distinct layers—from type definitions in packages/toolkit/connector-kit to verification handlers in packages/core.

Understanding Logto's Social Connector Architecture

Logto organizes social authentication across three architectural layers that handle everything from type definitions to end-user UI.

The Connector Kit Interface Layer

The Connector Kit defines the type-safe contract that every social connector must implement. Located at packages/toolkit/connector-kit/src/types/social.ts, this layer specifies the SocialConnector interface requiring two core methods: getAuthorizationUri(payload, setSession) for building the provider's OAuth URL and getUserInfo(data, getSession) for exchanging codes and normalizing user profiles. The interface also defines optional helpers like getTokenResponseAndUserInfo and getAccessTokenByRefreshToken for connectors requiring long-lived API access.

Core Orchestration Layer

The Core layer manages HTTP endpoints that orchestrate the OAuth flow, store temporary sessions, and optionally persist token sets. The verification callback logic lives in packages/core/src/routes/experience/classes/verifications/social-verification.ts, while packages/core/src/libraries/social.ts contains helper functions that build authorization URLs and validate session data using connectorSessionGuard.

Experience and Console UI Layer

The Experience layer handles frontend interactions. The utility functions for listing and initiating social connectors reside in packages/experience/src/utils/social-connectors.ts, while the Console UI renders provider logos using assets from packages/console/src/onboarding/assets/icons/social-*.svg and provides the onboarding interface for toggling connectors.

Configuring Built-In Social Connectors in the Console

Logto ships with ready-made connectors in packages/connectors for providers like Google, GitHub, and Facebook. Each connector includes a README.md with provider-specific instructions, such as the Google connector guide at packages/connectors/connector-google/README.md.

Follow these steps to configure a social connector:

1. Create the provider application – Generate clientId and clientSecret in your provider's developer console (e.g., Google Cloud Console, GitHub OAuth Apps).

2. Enter credentials in Logto Console – Navigate to Connectors → Add new → select your provider → fill in clientId and clientSecret.

3. Configure scopes – Leave blank for default openid profile email or specify additional scopes separated by spaces (e.g., https://www.googleapis.com/auth/calendar.readonly).

4. Set OIDC prompts – Optionally specify an array of prompt values (none, login, consent, select_account) validated by the oidcPromptsGuard type guard in social.ts.

5. Enable token storage – Toggle Store tokens for persistent API access to activate the getTokenResponseAndUserInfo path, persisting tokens in the Secret Vault for later API calls.

6. Configure Google One Tap (optional) – For Google connectors, enable One Tap and configure autoSelect, closeOnTapOutside, and itpSupport via the GoogleOneTapConfig type.

Once saved, the connector appears in the Social sign-in section of the Sign-up & sign-in page, making the "Sign in with [Provider]" button visible to end-users.

Runtime Flow of Social Authentication

When a user initiates social login, Logto executes a five-step verification process:

1. Initiation – The frontend calls /api/social/:connectorId/authorization-uri, triggering getAuthorizationUri in the connector.

2. Session storage – The Core stores a ConnectorSession containing state, nonce, and redirectUri via the setSession callback.

3. Provider redirect – The user is redirected to the provider's OAuth endpoint; after consent, the provider redirects back to Logto's /callback/:connectorId endpoint.

4. Verification and token exchange – Core validates the state parameter, exchanges the authorization code for tokens, and retrieves normalized SocialUserInfo (id, email, name, avatar, rawData).

5. User creation linking – If token storage is enabled, tokens are persisted in the Secret Vault and retrievable via the Social Verification API (/api/experience/social-verification). The session data is automatically cleared after successful authentication.

Building Custom Social Connectors

If your provider is not in the built-in catalogue, create a new connector under packages/connectors. The minimal scaffold implements the SocialConnector type:

// my-connector/src/index.ts
import { SocialConnector, SocialUserInfo } from '@logto/connector-kit';
import { z } from 'zod';

export const configGuard = z.object({
  clientId: z.string(),
  clientSecret: z.string(),
  scope: z.string().optional(),
});

export const MyConnector: SocialConnector = {
  type: 'Social',
  configGuard,
  getAuthorizationUri: async (payload, setSession) => {
    const url = new URL('https://myprovider.com/oauth/authorize');
    url.searchParams.set('client_id', payload.connectorFactoryId);
    url.searchParams.set('redirect_uri', payload.redirectUri);
    url.searchParams.set('response_type', 'code');
    url.searchParams.set('state', payload.state);
    if (payload.scope) url.searchParams.set('scope', payload.scope);
    await setSession({ /* store nonce, redirectUri … */ });
    return url.toString();
  },
  getUserInfo: async (data, getSession) => {
    // Exchange code for token, fetch profile, normalize:
    const userInfo: SocialUserInfo = {
      id: data.sub,
      email: data.email,
      name: data.name,
      avatar: data.picture,
    };
    return userInfo;
  },
};

Register the connector by adding a package.json with "connectorFactoryId": "my-connector" and publishing it under the connector scope, or load it locally in development mode.

Programmatic Configuration via Management API

You can automate connector configuration using the Logto Management API instead of the Console UI.

Creating a Google Connector via API

import axios from 'axios';

await axios.post(
  `${process.env.LOGTO_ADMIN_ENDPOINT}/api/connectors`,
  {
    connectorId: 'google',
    config: {
      clientId: 'YOUR_GOOGLE_CLIENT_ID',
      clientSecret: 'YOUR_GOOGLE_CLIENT_SECRET',
      scope: 'https://www.googleapis.com/auth/calendar.readonly',
      prompts: ['consent'],
      offlineAccess: true,
      oneTap: { isEnabled: true, autoSelect: false },
    },
  },
  { headers: { Authorization: `Bearer ${adminAccessToken}` } }
);

The request body mirrors the GoogleConnectorConfig type defined at lines 9-20 of packages/toolkit/connector-kit/src/types/social.ts.

Initiating Authorization from Frontend

async function startGoogleLogin() {
  const resp = await fetch('/api/social/google/authorization-uri', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ 
      redirectUri: window.location.origin + '/callback' 
    })
  });
  const { authorizationUri } = await resp.json();
  window.location.href = authorizationUri;
}

Re-requesting Scopes with Social Verification

To request additional scopes after initial sign-in:

await axios.post(
  `${process.env.LOGTO_ENDPOINT}/api/experience/social-verification`,
  {
    connectorId: 'google',
    data: { /* idToken from One Tap */ },
    scope: 'https://www.googleapis.com/auth/calendar',
  },
  { headers: { Authorization: `Bearer ${userAccessToken}` } }
);

This triggers the social-verification route in packages/core/src/routes/experience/classes/verifications/social-verification.ts, which re-initiates the OAuth flow, stores the new token set, and returns the updated user profile.

Summary

• Three-layer architecture: Logto separates social connectors into the Connector Kit (type definitions), Core (orchestration), and Experience (UI) layers.
• Required implementation: Every social connector must implement getAuthorizationUri and getUserInfo as defined in packages/toolkit/connector-kit/src/types/social.ts.
• Configuration steps: Create provider credentials, configure scopes and prompts, and optionally enable token storage for persistent API access.
• Token persistence: Enable "Store tokens" to access provider APIs later via the Social Verification API endpoint.
• Custom connectors: Build new connectors by implementing the SocialConnector interface and registering them in packages/connectors.

Frequently Asked Questions

How does Logto store temporary OAuth state during the authentication flow?

Logto stores temporary OAuth state using the ConnectorSession type defined in packages/toolkit/connector-kit/src/types/social.ts. When getAuthorizationUri is called, it receives a setSession callback that persists state, nonce, and redirectUri in the Core layer. This session data is automatically validated and cleared during the callback phase in packages/core/src/routes/experience/classes/verifications/social-verification.ts.

Can I request additional OAuth scopes after the user has already signed up?

Yes. Use the Social Verification API endpoint /api/experience/social-verification to re-initiate the OAuth flow with new scopes. This triggers the social-verification.ts handler to exchange the new authorization code and store updated tokens in the Secret Vault, allowing you to incrementally request permissions like calendar access or email sending without forcing a full re-authentication.

What is the difference between getUserInfo and getTokenResponseAndUserInfo?

getUserInfo is the required method that exchanges the authorization code for an access token and returns normalized user profile data (id, email, name, avatar). getTokenResponseAndUserInfo is an optional method used when "Store tokens" is enabled; it returns the full token response including refresh tokens and access tokens, which Logto persists for later API calls. Use the latter when you need long-lived access to provider APIs beyond the initial authentication.

Where does Logto store social connector tokens when "Store tokens" is enabled?

When you enable the "Store tokens for persistent API access" toggle in the Console, Logto persists tokens in the Secret Vault. These tokens are accessible via the Social Verification API at packages/core/src/routes/experience/classes/verifications/social-verification.ts. The system uses the optional getTokenResponseAndUserInfo method from the connector to retrieve and store both access tokens and refresh tokens securely.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}