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

> Integrate social login effortlessly with Logto's social connectors. This guide details implementation using OIDC/OAuth2 for seamless user authentication with Google, GitHub, and more.

- Repository: [Logto/logto](https://github.com/logto-io/logto)
- Tags: how-to-guide
- Published: 2026-07-04

---

**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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/packages/core/src/routes/experience/classes/verifications/social-verification.ts), while [`packages/core/src/libraries/social.ts`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/README.md) with provider-specific instructions, such as the Google connector guide at [`packages/connectors/connector-google/README.md`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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:

```typescript
// 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`](https://github.com/logto-io/logto/blob/main/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

```typescript
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`](https://github.com/logto-io/logto/blob/main/packages/toolkit/connector-kit/src/types/social.ts).

### Initiating Authorization from Frontend

```javascript
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:

```typescript
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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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.