Introduction

Enterprise SSO over OpenID Connect (OIDC) lets your users authenticate through their organization’s Identity Provider (IdP), such as Okta, Google Workspace, or Microsoft Entra ID. It reuses the same OAuth authorization-code flow as social login — the difference is tenancy: instead of one global “Sign in with Google” button, you register one or more enterprise connections, each scoped to a customer’s IdP and bound to their email domains.

Prerequisites

Before you start, make sure you have:

A Prelude account with access to Prelude Auth
An Application ID (appID) — see Applications
Your Management API key for backend calls
OAuth credentials from the customer’s IdP application (client ID, client secret, and for Okta the issuer URL)
Admin access to the Identity Provider you want to connect

Supported providers

Enterprise connections are available for the OIDC-capable providers:

Provider	Identifier
Okta	`okta`
Google Workspace	`google`
Microsoft Entra ID	`microsoft`

Personal vs enterprise connections

Each OAuth provider config carries a type:

personal (the default) — the classic social-login button. At most one per provider, addressed as …/oauth/{provider}.
enterprise — a per-customer OIDC connection. An app can hold any number of them per provider, each addressed as …/oauth/{provider}/{connection_id}.

Creating an enterprise connection never conflicts with a personal one for the same provider. Two enterprise connections conflict only if they claim the same email domain — a domain must resolve to exactly one connection.

The type of a connection is immutable. To switch between personal and enterprise, delete the config and create a new one.

Create a connection

Enterprise connections are managed through the same endpoint as social login, with type set to enterprise and an enterprise block:

curl -X POST https://api.prelude.so/v2/session/apps/{appID}/config/login/oauth/okta \
  -H "Authorization: Bearer $PRELUDE_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "enterprise",
    "client_id": "0oa1b2c3d4EXAMPLE",
    "client_secret": "…",
    "enabled": true,
    "scopes": ["openid", "email", "profile"],
    "enterprise": {
      "issuer_url": "https://acme.okta.com/oauth2/default",
      "email_domain_allowlist": ["acme.com"],
      "jit_provisioning": true,
      "allow_email_account_merge": true,
      "sync_profile_on_login": true,
      "default_redirect_uri": "https://acme.yourapp.com/callback"
    }
  }'

The response includes the generated connection_id (an ocon_… identifier). Use it to update, delete, or launch the connection.

Method	Path
List all configs (personal + enterprise)	`GET …/config/login/oauth`
Create	`POST …/config/login/oauth/{provider}`
Update	`PUT …/config/login/oauth/{provider}/{connection_id}`
Delete	`DELETE …/config/login/oauth/{provider}/{connection_id}`

Connection behavior

The enterprise block controls provisioning, login, and profile syncing:

Field	Type	Description
`issuer_url`	string	The IdP’s OIDC issuer (https). Required. For Okta this is the authorization server URL, e.g. `https://acme.okta.com/oauth2/default`.
`email_domain_allowlist`	string[]	Email domains this connection covers. Required and non-empty. It is the domain→connection binding used for email-resolved login, and every login’s IdP-asserted email must fall within it.
`jit_provisioning`	boolean	When `true`, just-in-time provisions a new user on first login. When `false`, a user with no existing match is rejected.
`allow_email_account_merge`	boolean	When `true`, links the OIDC identifier to an existing user that owns the same email.
`enforce_login`	boolean	Reserved for future parity with SAML enforcement.
`sync_profile_on_login`	boolean	When `true`, refreshes `name`, `given_name`, `family_name`, and `picture` from the IdP on every login instead of only at first provisioning.
`default_redirect_uri`	string	Redirect URI used when a login flow omits `redirect_uri`. Must be allowlisted for your app.
`claim_mapping`	object	Optional overrides for the id_token claim names used to read `email`, `given_name`, `family_name`, and arbitrary `custom` claims. Sensible defaults apply when omitted.

How the flow works

An enterprise login is the same authorization-code flow as social login:

Initiate — Your app starts the flow by email (resolved to a connection via its domain allowlist) or by connection id. Prelude derives the provider from the connection and redirects the user to the IdP.
Callback — After authenticating, the IdP redirects back and Prelude redirects to your app with a challenge_token.
Finalize — Your app finalizes the challenge_token, exactly as for social login.

The key difference from personal social login is the email domain check: because the connection is pre-bound to one or more domains, a matching domain is proof enough of the user’s organization, so there is no verify_email OTP step. A login whose IdP email falls outside the allowlist is refused (oauth_email_domain_not_allowed).

Enterprise identities are scoped per connection. The stored identifier is oauth:{provider}:{connection_id}, so the same provider subject seen through two different connections never collapses onto one account.

Getting the email from Microsoft Entra ID

Microsoft only includes an email claim in the id_token when the signed-in user has an email set on their profile, or when the app registration requests the email optional claim. If Entra logins reach the callback without an email — which an enterprise connection rejects, since it cannot match a domain — add the optional claim:

In the Azure portal, open App registrations → your app → Token configuration.
Choose Add optional claim, select ID, and add email.
Request the email scope in the connection’s scopes.

For accounts whose email is not part of the tenant directory, also ensure the user has a verified email on their Microsoft profile.

Documentation

API Reference

Prerequisites

Supported providers

Personal vs enterprise connections

Create a connection

Connection behavior

How the flow works

Getting the email from Microsoft Entra ID

What’s next?

Web integration

Social login

​Prerequisites

​Supported providers

​Personal vs enterprise connections

​Create a connection

​Connection behavior

​How the flow works

​Getting the email from Microsoft Entra ID

​What’s next?

Web integration

Social login

Prerequisites

Supported providers

Personal vs enterprise connections

Create a connection

Connection behavior

How the flow works

Getting the email from Microsoft Entra ID

What’s next?