Clerk SSO Setup

HatiData uses Clerk for enterprise single sign-on. Clerk provides a unified API for SAML 2.0 and OIDC identity providers, so HatiData supports all major IdPs -- Okta, Azure AD, Google Workspace, OneLogin, and JumpCloud -- through a single integration.

How SSO Works with HatiData

User (browser)
    |
    v
HatiData Dashboard --> Clerk --> Customer IdP (Okta, Azure AD, etc.)
    |                    |                      |
    |                    |<--- SAML/OIDC <------+
    |               <----+
    |
    v
HatiData Control Plane
    |
    +-- Validate Clerk session token
    +-- Map Clerk organization --> HatiData org
    +-- Apply RBAC roles from IdP groups
    +-- Issue HatiData JWT

---

Prerequisites

• A Clerk account with Enterprise SSO enabled
• HatiData Enterprise or Growth tier
• Admin access to your identity provider (Okta, Azure AD, etc.)

---

Step 1: Configure Clerk

Create a Clerk Organization

Each HatiData organization maps to a Clerk organization. Organizations are created automatically when users sign up, or you can create them via the Clerk Dashboard or API:

curl -X POST https://api.clerk.com/v1/organizations \
  -H "Authorization: Bearer sk_live_your_clerk_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp"
  }'

Enable Enterprise SSO

In the Clerk Dashboard:

1. Navigate to Organizations and select the organization
2. Go to SSO Connections
3. Click Add Connection
4. Choose the identity provider (Okta, Azure AD, Google Workspace, etc.)
5. Follow the provider-specific setup instructions

Set Environment Variables

Add Clerk credentials to the HatiData control plane:

CLERK_PUBLISHABLE_KEY=pk_live_your_clerk_publishable_key
CLERK_SECRET_KEY=sk_live_your_clerk_secret_key
CLERK_WEBHOOK_SIGNING_SECRET=whsec_your_clerk_webhook_secret

For the dashboard:

VITE_CLERK_PUBLISHABLE_KEY=pk_live_your_clerk_publishable_key

---

Step 2: SAML Configuration (Okta Example)

In Okta

1. Create a new SAML 2.0 application in Okta
2. Set the Single Sign-On URL to the value provided by Clerk
3. Set the Audience URI (SP Entity ID) to the value provided by Clerk
4. Configure attribute statements:

Name	Value
email	user.email
firstName	user.firstName
lastName	user.lastName

5. Download the IdP Metadata XML and upload it to Clerk

In Clerk

1. Upload the Okta IdP metadata XML
2. Clerk validates the SAML configuration
3. Test the connection with a test login

---

Step 3: OIDC Configuration (Azure AD Example)

In Azure AD

1. Register a new application in Azure AD
2. Set the Redirect URI to the Clerk callback URL
3. Under Certificates & Secrets, create a new client secret
4. Under Token Configuration, add optional claims: email, given_name, family_name

In Clerk

1. Enter the Azure AD Client ID, Client Secret, and Discovery URL
2. Clerk validates the OIDC configuration
3. Test the connection

---

Step 4: Organization-Level Auth

Map Clerk organizations to HatiData organizations:

from hatidata import HatiDataClient

admin = HatiDataClient(
    host="localhost",
    port=5439,
    api_key="hd_live_admin_key",
)

# Link a Clerk organization to a HatiData organization
admin.organizations.configure_sso(
    org_id="org_acme",
    clerk_org_id="org_2abc...",
    allowed_domains=["acme.com"],
    default_role="viewer",
    auto_create_users=True,
)

Configuration Options

Option	Description
clerk_org_id	Clerk organization ID
allowed_domains	Email domains that can SSO into this organization
default_role	Role assigned to new SSO users (viewer, editor, admin)
auto_create_users	Automatically create HatiData users on first SSO login
require_sso	If true, password login is disabled for this org

---

Step 5: Session Management

Clerk handles session tokens. The HatiData control plane validates these tokens and issues its own JWT for API access.

Session Flow

1. User clicks "Sign in with SSO" on the HatiData dashboard
2. Dashboard redirects to Clerk
3. Clerk redirects to the customer's IdP
4. IdP authenticates the user and redirects back to Clerk
5. Clerk redirects to HatiData's callback URL with a session token
6. HatiData control plane validates the token with Clerk
7. Control plane maps the user to a HatiData organization and role
8. A HatiData JWT is issued and stored as an HTTP-only cookie

Token Validation

# The control plane validates Clerk tokens on every API request
# No user code is needed -- this happens automatically

# To check the current user's SSO status:
user_info = admin.auth.whoami()
print(f"User: {user_info.email}")
print(f"Org: {user_info.org_id}")
print(f"Auth method: {user_info.auth_method}")  # "sso" or "api_key"
print(f"IdP: {user_info.idp_name}")  # "okta", "azure_ad", etc.

Enforcing SSO-Only Access

For organizations that require SSO, disable API key and password authentication:

admin.organizations.update(
    org_id="org_acme",
    require_sso=True,
    disable_api_key_auth=False,  # Keep API keys for agents
)

note

Even with require_sso=True, agent API keys continue to work. SSO enforcement applies to human users accessing the dashboard and control plane API.

---

Step 6: Verify SSO

Test the SSO integration:

# Check SSO connection status
curl https://api.hatidata.com/v1/organizations/org_acme/sso/status \
  -H "Authorization: Bearer <admin_jwt>"

{
  "sso_enabled": true,
  "provider": "okta",
  "connection_state": "active",
  "last_login": "2025-12-15T10:30:00Z",
  "total_sso_users": 42
}

---

Related Concepts

• SCIM Directory Sync -- Auto-provision users from your IdP
• Security Model -- Full authentication architecture
• Agent Identity Model -- Agent keys vs user auth
• SOC 2 Architecture -- Compliance controls
• PrivateLink & VPC -- Network-level security