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

> Configure enterprise SSO connectors with Logto for OIDC and SAML providers. Learn about JIT provisioning and encrypted token storage in this technical guide.

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

---

**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/main/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/main/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/main/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:

```bash
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/main/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/main/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/main/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/main/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/main/enterprise-sso.openapi.json)](https://github.com/logto-io/logto/blob/master/packages/core/src/routes/admin-user/enterprise-sso.openapi.json):

```bash
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

```typescript
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

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