Enterprise SSO

This guide covers how to start an enterprise single sign-on (OIDC) login from your web application. Make sure you have configured an enterprise connection on your backend before proceeding. An enterprise SSO login is the same three-step flow as social login:

Redirect — Your app asks the SDK to start the flow; it redirects the user to the Identity Provider.
Callback — After authenticating, the IdP redirects back and Prelude redirects to your app with a challenge_token.
Finalize — Your app sends the challenge_token to complete authentication.

The challenge_token is finalized exactly like social login — via finalizeOAuthLogin. Unlike personal social login, an enterprise connection is bound to email domains, so it never returns the otp_required step: it always resolves to { status: "logged_in" }.

How is the enterprise flow secured?

The flow is protected by PKCE (Proof Key for Code Exchange). The SDK generates a unique code_verifier/code_challenge pair for each login and stores the verifier locally; the challenge_token can only be finalized once, by the browser that started the flow. In addition, the connection the flow launched with is pinned server-side, and the IdP-asserted email’s domain must fall within that connection’s allowlist.

Redirect to the Identity Provider

There are two ways to start the flow.

By email

Resolve the connection from the user’s email domain (it must match exactly one enabled connection’s allowlist):

await client.loginWithEnterpriseOAuth({
  email: "jane@acme.com",
  redirectURI: "https://yourapp.com/callback",
});

By connection

When you already know the connection, pass its connectionId:

await client.loginWithEnterpriseOAuth({
  connectionId: "ocon_01jqebhswje1ka1z7ahr9rfsgt",
  redirectURI: "https://yourapp.com/callback",
});

redirectURI is optional — it must be allowlisted for your app, and falls back to the connection’s default_redirect_uri when omitted. The provider (Okta, Google, Microsoft) is derived server-side from the connection, so you never pass it here.

Both forms navigate the browser to the IdP. If you need the authorization URL without navigating (e.g. to open it yourself), call initiateEnterpriseOAuthLogin, which returns { authorization_url }.

Handle the callback

When the IdP redirects back to your app, extract the challenge_token from the URL and finalize the login — the same call used for social login and SAML:

import { PrldErrors } from "@prelude.so/js-sdk";

const params = new URLSearchParams(window.location.search);
const challengeToken = params.get("challenge_token");
const error = params.get("error");

if (error) {
  // Enterprise validation or provisioning failure, e.g.
  // oauth_email_domain_not_allowed, oauth_user_not_provisioned.
  console.error(params.get("error_description") || error);
} else if (challengeToken) {
  try {
    await client.finalizeOAuthLogin(challengeToken);
    // The user is now authenticated. Enterprise challenge tokens always
    // resolve to { status: "logged_in" }.
    await client.refresh();
  } catch (err) {
    if (err instanceof PrldErrors.ExpiredChallengeToken) {
      // Challenge token has expired — restart the flow
    } else if (err instanceof PrldErrors.InvalidChallengeToken) {
      // Challenge token is invalid
    }
  }
}

Try it

Replace src/App.jsx with:

src/App.jsx

import "@picocss/pico";
import { useState, useEffect } from "react";
import { PrldSessionClient, PrldErrors, decode } from "@prelude.so/js-sdk";

const client = new PrldSessionClient({ domain: `${import.meta.env.VITE_APP_ID}.session.prelude.dev` });

export default function App() {
  const [user, setUser] = useState(null);
  const [email, setEmail] = useState("");
  const [error, setError] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const init = async () => {
      const params = new URLSearchParams(window.location.search);
      const challengeToken = params.get("challenge_token");
      const callbackError = params.get("error");

      if (challengeToken || callbackError) {
        window.history.replaceState({}, "", window.location.pathname);
      }

      if (callbackError) {
        setError(params.get("error_description") || callbackError);
        setLoading(false);
        return;
      }

      if (challengeToken) {
        try {
          await client.finalizeOAuthLogin(challengeToken);
        } catch (err) {
          if (err instanceof PrldErrors.ExpiredChallengeToken) {
            setError("Login expired. Please try again.");
          } else if (err instanceof PrldErrors.InvalidChallengeToken) {
            setError("Invalid login. Please try again.");
          } else {
            setError("Something went wrong. Please try again.");
          }
          setLoading(false);
          return;
        }
      }

      try {
        const { user } = await client.refresh();
        setUser(user);
      } catch {
        // No active session
      }

      setLoading(false);
    };

    void init();
  }, []);

  const handleEnterpriseLogin = async () => {
    setError(null);
    try {
      await client.loginWithEnterpriseOAuth({
        email,
        redirectURI: window.location.origin + window.location.pathname,
      });
    } catch (err) {
      // The initiate endpoint rejects an unknown email domain
      // (oauth_no_connection_for_email).
      setError("No SSO connection is configured for that email domain.");
    }
  };

  return (
    <>
      <style>{`body, #root { display: flex; justify-content: center; align-items: center; min-height: 100vh; margin: 0; padding: 0; }`}</style>
      <main style={{ textAlign: "center", maxWidth: "600px", width: "100%" }}>
        <h1>Enterprise SSO</h1>
        {loading ? (
          <p aria-busy="true">Completing login...</p>
        ) : user ? (
          <article>
            <p>Logged in</p>
            <pre style={{ textAlign: "left", whiteSpace: "pre-wrap", wordBreak: "break-all" }}>
              {JSON.stringify(decode(user.accessToken).claims, null, 2)}
            </pre>
            <button className="secondary" onClick={async () => {
              await client.logout();
              setUser(null);
            }}>Log Out</button>
          </article>
        ) : (
          <>
            {error && <p role="alert" style={{ color: "var(--pico-color-red-500)" }}>{error}</p>}
            <input
              type="email"
              placeholder="you@company.com"
              value={email}
              onChange={(e) => setEmail(e.target.value)}
            />
            <button onClick={handleEnterpriseLogin} disabled={!email.trim()}>
              Sign in with SSO
            </button>
          </>
        )}
      </main>
    </>
  );
}

Documentation

API Reference

Redirect to the Identity Provider

By email

By connection

Handle the callback

What’s next?

Configure a connection

Social login

​Enterprise login flow

​Redirect to the Identity Provider

​By email

​By connection

​Handle the callback

​What’s next?

Configure a connection

Social login

Enterprise login flow

Redirect to the Identity Provider

By email

By connection

Handle the callback

What’s next?