Configuring SSO Connectors for Enterprise Identity Providers with Logto: A Complete Technical Guide

Logto treats enterprise SSO connectors as first-class objects stored in the sso_connectors table, supporting OIDC and SAML providers with built-in just-in-time provisioning and optional encrypted token storage.

The logto-io/logto repository provides a comprehensive identity infrastructure where configuring SSO connectors for enterprise identity providers involves declarative management APIs, type-safe validation guards, and automated user provisioning workflows. This guide examines the database schemas, verification classes, and API endpoints that enable seamless enterprise authentication.

Understanding the SSO Connector Data Model

Logto persists enterprise SSO configurations in the sso_connectors table, defined in [packages/schemas/tables/sso_connectors.sql](https://github.com/logto-io/logto/blob/master/packages/schemas/tables/sso_connectors.sql). Each connector record contains provider-agnostic metadata and provider-specific configuration.

Core Schema Fields

The sso_connectors table stores the following critical fields:

• id: UUID primary key for the connector
• connectorName: Human-readable identifier displayed in the Admin Console
• providerName: Enumerated value from SsoProviderName (e.g., OIDC, SAML, AzureAD) defined in [packages/schemas/src/types/sso-connector.ts](https://github.com/logto-io/logto/blob/master/packages/schemas/src/types/sso-connector.ts#L18-L25)
• providerType: Either oidc or saml as specified by the SsoProviderType enum
• providerConfig: JSON blob containing IdP-specific discovery data (OIDC .well-known endpoints or SAML metadata XML)
• logo / darkLogo: HTTPS URLs for provider icons rendered in the sign-in experience
• tokenStorageEnabled: Boolean flag enabling encrypted storage of IdP token sets

Type Validation with Zod Guards

Before persistence, all incoming data passes through the ssoConnectorMetadataGuard in [packages/schemas/src/types/sso-connector.ts](https://github.com/logto-io/logto/blob/master/packages/schemas/src/types/sso-connector.ts#L9-L15). This Zod schema validates the shape of metadata and configuration objects. For full connector creation, the ssoConnectorWithProviderConfigGuard (lines 74-90) enforces type safety on the providerConfig field based on the selected providerType.

Creating Enterprise SSO Connectors via the Management API

The Management API exposes endpoints to provision and update connectors programmatically. When you send a POST request to /api/sso-connectors, the payload undergoes strict validation before database insertion.

Connector Configuration Structure

A valid creation payload includes the provider type, OAuth 2.0/OIDC parameters or SAML metadata, and optional branding assets:

curl -X POST https://your-logto.io/api/sso-connectors \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorName": "My Azure AD",
    "providerName": "AzureAD",
    "providerType": "oidc",
    "providerConfig": {
      "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0",
      "clientId": "<client-id>",
      "clientSecret": "<client-secret>",
      "redirectUris": ["https://your-app.com/callback"]
    },
    "logo": "https://example.com/logo.png",
    "tokenStorageEnabled": true
  }'

Validation and Persistence

The ssoConnectorWithProviderConfigGuard validates the JSON payload structure. Upon successful validation, Logto inserts the record into sso_connectors and writes a static provider detail record that the Experience client renders. Updates via PUT /api/sso-connectors/:id follow the same validation pipeline before modifying the database row.

The Enterprise SSO Verification Flow

When users initiate sign-in, the EnterpriseSsoVerification class in [packages/core/src/routes/experience/classes/verifications/enterprise-sso-verification.ts](https://github.com/logto-io/logto/blob/master/packages/core/src/routes/experience/classes/verifications/enterprise-sso-verification.ts) orchestrates the OAuth 2.0/OIDC or SAML handshake.

Authorization URL Generation

The Experience layer calls GET /api/sso/:connectorId/authorization-url to retrieve the IdP redirect URL. The EnterpriseSsoVerification class constructs this URL using the providerConfig stored in the connector record, including state parameters for CSRF protection.

Callback Verification and Identity Linking

After the IdP redirects back to Logto, the verification class validates the callback parameters (authorization code or SAML assertion) against the configured redirectUris. Upon successful validation, the profile sync logic in [packages/core/src/routes/experience/classes/profile.ts](https://github.com/logto-io/logto/blob/master/packages/core/src/routes/experience/classes/profile.ts) updates the user_sso_identities table (see [user_sso_identities.sql](https://github.com/logto-io/logto/blob/master/packages/schemas/tables/user_sso_identities.sql)) with the IdP-provided identifier, linking the external identity to the Logto user account.

Just-In-Time (JIT) User Provisioning

Logto supports automatic user creation and organization membership assignment through the organization_jit_sso_connectors table (see [organization_jit_sso_connectors.sql](https://github.com/logto-io/logto/blob/master/packages/schemas/tables/organization_jit_sso_connectors.sql)). When an organization enables JIT provisioning for a specific connector, Logto checks this linking table during the first sign-in attempt. If a match exists, the system creates a new user record and automatically adds the user to the organization without manual invitation.

Secure Token Storage for Third-Party API Access

For enterprise scenarios requiring downstream API calls, Logto optionally encrypts and stores the IdP token set. When tokenStorageEnabled is true, the token set resides in the secret_enterprise_sso_connector_relations table (Secret Vault).

Retrieving Stored Tokens

Administrators can retrieve encrypted tokens via the endpoint defined in [enterprise-sso.openapi.json](https://github.com/logto-io/logto/blob/master/packages/core/src/routes/admin-user/enterprise-sso.openapi.json):

curl -X GET https://your-logto.io/api/users/123/enterprise-sso/<connector-id>/token \
  -H "Authorization: Bearer <user-token>"

This returns the token set only when the connector configuration explicitly enabled storage during creation.

Implementation Examples

Creating a Connector with the TypeScript SDK

import { ManagementClient } from '@logto/js';

const client = new ManagementClient({ 
  endpoint: 'https://your-logto.io', 
  accessToken: adminToken 
});

await client.ssoConnectors.create({
  connectorName: 'My Azure AD',
  providerName: 'AzureAD',
  providerType: 'oidc',
  providerConfig: {
    issuer: 'https://login.microsoftonline.com/123456/v2.0',
    clientId: 'abc',
    clientSecret: 'def',
    redirectUris: ['https://app.example.com/callback'],
  },
  logo: 'https://example.com/logo.png',
  tokenStorageEnabled: true,
});

Handling the SSO Callback

import { EnterpriseSsoVerification } from '@logto/core';
import type { Request, Response } from 'express';

export async function enterpriseSsoCallback(req: Request, res: Response) {
  const { ssoConnectorId, state, code } = req.query;
  
  const verification = new EnterpriseSsoVerification(ssoConnectorId as string);
  await verification.verify({ 
    state: state as string, 
    code: code as string 
  });
  
  // Identity is now linked; token stored if enabled
  res.redirect('/dashboard');
}

Summary

• SSO connectors are first-class database entities stored in sso_connectors with strict Zod validation via ssoConnectorMetadataGuard and ssoConnectorWithProviderConfigGuard.
• Provider configuration supports both OIDC and SAML protocols, with specific schemas defined in packages/schemas/src/types/sso-connector.ts.
• Verification flow uses the EnterpriseSsoVerification class to handle authorization URLs, callback validation, and identity linking to user_sso_identities.
• JIT provisioning automatically creates users and assigns organization memberships through the organization_jit_sso_connectors table.
• Token storage optionally encrypts IdP credentials in secret_enterprise_sso_connector_relations when tokenStorageEnabled is true, retrievable via GET /api/users/:id/enterprise-sso/:connectorId/token.

Frequently Asked Questions

What identity providers does Logto support for enterprise SSO?

Logto supports any OIDC or SAML 2.0 compliant identity provider. The SsoProviderName enum in [packages/schemas/src/types/sso-connector.ts](https://github.com/logto-io/logto/blob/master/packages/schemas/src/types/sso-connector.ts#L18-L25) includes built-in presets for popular providers like AzureAD, while the generic OIDC and SAML options accommodate custom enterprise IdPs.

How does Logto validate SSO connector configurations before persistence?

All configurations pass through the ssoConnectorWithProviderConfigGuard Zod schema before database insertion. This guard validates the providerConfig JSON structure against the declared providerType (OIDC or SAML), ensuring required fields like issuer, clientId, and redirectUris are present and correctly formatted.

What is the purpose of token storage in enterprise SSO connectors?

When tokenStorageEnabled is set to true, Logto encrypts and stores the token set returned by the IdP in the Secret Vault (secret_enterprise_sso_connector_relations table). This allows your application to retrieve the tokens later via the Management API to make authenticated calls to the enterprise IdP's APIs on behalf of the user, such as accessing Microsoft Graph or corporate directory services.

How does just-in-time provisioning work with organization memberships?

Just-in-time (JIT) provisioning checks the organization_jit_sso_connectors table during the first sign-in attempt via an enterprise connector. If the organization has enabled JIT for that connector, Logto automatically creates a user account and adds the user to the organization, eliminating the need for manual invitations or pre-provisioning user accounts.

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