Advanced20 minutes

Set Up SSO

Configure single sign-on with SAML 2.0 or OIDC to enable seamless enterprise authentication using Origin Auth.

Prerequisites

Tenant operator or platform operator access in Origin Auth
An identity provider (IdP) that supports SAML 2.0 or OIDC
Your tenant slug and Origin Auth base URL
A callback URL configured in your application

Choose Your Protocol

Decide whether to use SAML 2.0 or OIDC based on your identity provider.

SAML 2.0

Best for enterprise IdPs like Okta, Azure AD, and Keycloak.

Uses XML metadata exchange and supports signed assertions. Recommended for enterprise deployments.

OIDC / OAuth 2.0

Best for modern SaaS and cloud-native IdPs.

Uses JSON Web Tokens (JWT) and discovery endpoints. Easier to configure and widely supported.

Configure SAML SSO

Set up Origin Auth as a SAML service provider.

First, create a SAML connection in Origin Auth. Then download the service provider metadata and upload it to your IdP.

# Create a SAML connection
curl -X POST https://auth.origin-auth.io/v1.0/sso/saml \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Okta Enterprise SSO",
    "entityId": "https://auth.origin-auth.io/saml/my-tenant",
    "acsUrl": "https://auth.origin-auth.io/saml/my-tenant/acs",
    "idpMetadataUrl": "https://my-org.okta.com/app/exk123456/sso/saml/metadata",
    "jitProvisioning": true,
    "defaultRole": "TenantUser"
  }'

# Download SP metadata
curl -X GET "https://auth.origin-auth.io/v1.0/sso/saml/CONNECTION_ID/metadata" \
  -H "Authorization: Bearer YOUR_TOKEN"

Configure OIDC SSO

Set up Origin Auth as an OIDC relying party.

For OIDC, you'll need your IdP's discovery URL, client ID, and client secret. Origin Auth will fetch the JWKS automatically.

# Create an OIDC connection
curl -X POST https://auth.origin-auth.io/v1.0/sso/oidc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Google Workspace SSO",
    "discoveryUrl": "https://accounts.google.com/.well-known/openid-configuration",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "redirectUri": "https://auth.origin-auth.io/oidc/callback",
    "scopes": ["openid", "email", "profile"],
    "jitProvisioning": true,
    "defaultRole": "TenantUser"
  }'

# Get the login URL for this connection
curl -X GET "https://auth.origin-auth.io/v1.0/sso/oidc/CONNECTION_ID/login-url?redirect_uri=https://app.example.com/callback" \
  -H "Authorization: Bearer YOUR_TOKEN"

Configure Attribute Mapping

Map IdP attributes to Origin Auth user claims.

Map IdP claims to user attributes so new users are provisioned with the correct name, email, and role.

# Update attribute mapping for a SAML connection
curl -X PUT "https://auth.origin-auth.io/v1.0/sso/saml/CONNECTION_ID/mapping" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "urn:oid:0.9.2342.19200300.100.1.3",
    "firstName": "urn:oid:2.5.4.42",
    "lastName": "urn:oid:2.5.4.4",
    "role": "role",
    "groups": "groups"
  }'

# Update mapping for an OIDC connection
curl -X PUT "https://auth.origin-auth.io/v1.0/sso/oidc/CONNECTION_ID/mapping" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "email",
    "firstName": "given_name",
    "lastName": "family_name",
    "role": "roles",
    "groups": "groups"
  }'

Handle the SSO Callback

Complete the authentication flow in your application.

After the IdP authenticates the user, Origin Auth will redirect to your callback URL with a token. Validate it and start a session.

// Next.js App Router route handler
import { NextResponse } from "next/server";

export async function GET(request) {
  const { searchParams } = new URL(request.url);
  const code = searchParams.get("code");
  const state = searchParams.get("state");

  if (!code) {
    return NextResponse.redirect("/login?error=missing_code");
  }

  // Exchange the authorization code for tokens
  const tokenResponse = await fetch(
    "https://auth.origin-auth.io/v1.0/sso/oidc/token",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        code,
        redirectUri: "https://app.example.com/callback",
      }),
    }
  );

  const { access_token, refresh_token, user } = await tokenResponse.json();

  // Set a session cookie and redirect to the app
  const response = NextResponse.redirect("/dashboard");
  response.cookies.set("session", access_token, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    maxAge: 60 * 60 * 24, // 24 hours
  });

  return response;
}

Enable Just-in-Time Provisioning

Automatically create users when they sign in via SSO.

With JIT provisioning enabled, Origin Auth automatically creates a user account on first successful SSO login and assigns the default role.

// Example: configure JIT provisioning with role rules
const connection = await client.sso.updateConnection(connection.id, {
  jitProvisioning: true,
  defaultRole: "TenantUser",
  roleMappings: {
    "admin": "TenantAdmin",
    "finance": "BillingAdmin",
    "support": "SupportAdmin",
    "user": "TenantUser",
  },
});

// You can also set conditional access rules
await client.sso.setAccessRules(connection.id, {
  allowedDomains: ["example.com"],
  requiredGroups: ["employees"],
  blockUnmappedRoles: true,
});

What You've Configured

SAML 2.0 and OIDC SSO connections in Origin Auth
Service provider and relying party configuration
Attribute/claim mapping between IdP and Origin Auth
SSO callback handling with secure session cookies
Just-in-Time provisioning with role mapping rules

Next Steps

Continue learning with these related tutorials:

Build a Membership Site

User registration and RBAC

Add Contacts

Contact management and sync