Skip to main content

Setup SSO with Okta

Arcane supports Okta SAML 2.0 single sign-on (SSO) for organisation authentication. When SSO is enabled, users sign in with their Okta credentials instead of email and password. This feature requires an Arcane Enterprise license.

Overview​

With SSO enabled, users sign in via Okta instead of email and password. The login page shows a Sign in with SSO button, and invite emails direct new users to sign in with their organisation account.

Prerequisites​

  • Arcane Enterprise license (ARCANE_ENTERPRISE_LICENSE env var)
  • Okta admin account
  • Backend and frontend accessible (or local dev environment)

Step 1: Create an Okta SAML application​

  1. Log in to Okta Admin Console.

  2. Go to Applications → Create App Integration.

  3. Choose SAML 2.0 and click Next.

  4. Configure the app:

    • App name: e.g. Arcane
    • Single sign-on URL: https://your-backend-domain.com/api/auth/sso/saml2/sp/acs
    • Audience URI (SP Entity ID): https://your-backend-domain.com/api/auth/sso/saml2/sp/metadata
    • Name ID format: EmailAddress (recommended)
    • Application username: Email

  5. Save and continue. On the Assignments tab, assign groups or users who should have access.

  6. Note the Sign on URL and Issuer from the app’s Sign On tab; you’ll need these for Step 2.

Step 2: Get Okta metadata values​

From your Okta SAML app:

Okta fieldUsed as
Sign on URL (Single sign-on URL)OKTA_SSO_ENTRY_POINT
Issuer (Entity ID)OKTA_ENTITY_ID
X.509 Certificate (copy the certificate block)OKTA_SAML_CERT
Okta domain (e.g. https://your-org.okta.com)OKTA_ISSUER_URL

Step 3: Configure the backend​

Set these environment variables on the backend (or in .env for local runs):

VariableRequiredDescription
OKTA_SSO_ENABLEDYestrue to enable Okta SSO
OKTA_SSO_ENTRY_POINTYesOkta Single sign-on URL
OKTA_ENTITY_IDYesOkta Issuer / Entity ID
OKTA_SAML_CERTYesOkta X.509 certificate (PEM format). Use \n for newlines in env vars
OKTA_ISSUER_URLNoOkta domain (e.g. https://your-org.okta.com) — used for trusted origins
OKTA_SSO_CALLBACK_URLNoCallback path after SSO. Default: /organisations
BETTER_AUTH_SSO_DOMAINNoDomain for SSO (e.g. localhost:3000 for dev, app.example.com for prod)

Example .env (values are placeholders):

OKTA_SSO_ENABLED=true
OKTA_SSO_ENTRY_POINT=https://your-org.okta.com/app/abc123/sso/saml
OKTA_ENTITY_ID=https://your-org.okta.com/app/abc123/sso/saml/metadata
OKTA_SAML_CERT=-----BEGIN CERTIFICATE-----\nMIIE...\n-----END CERTIFICATE-----
OKTA_ISSUER_URL=https://your-org.okta.com
BETTER_AUTH_SSO_DOMAIN=app.example.com

Run migrations to create SSO tables:

npx @better-auth/cli migrate

Step 4: Configure Okta with Arcane SP metadata​

Arcane acts as a SAML Service Provider (SP). Its metadata URL is:

{BETTER_AUTH_URL}/api/auth/sso/saml2/sp/metadata

Example: https://api.example.com/api/auth/sso/saml2/sp/metadata

In Okta, configure your SAML app to use this as the SP metadata or manually set:

  • Single sign-on URL = {BETTER_AUTH_URL}/api/auth/sso/saml2/sp/acs
  • Audience URI = {BETTER_AUTH_URL}/api/auth/sso/saml2/sp/metadata

The login page when SSO is enabled​

When SSO is enabled:

  • The login page shows: Sign in with your organisation account.
  • Only the Sign in with SSO button is visible.
  • Email and password fields are hidden.
  • Sign up link is hidden.

When SSO is disabled:

  • The login page shows: Enter your email and password to continue.
  • Email and password form plus Sign in and Sign up links are shown.

Invite emails with SSO​

When SSO is enabled, organisation invite emails look different:

  • The message says: “You’ve been invited by [admin] to join [organisation]. We’re excited to have you on board! Sign in with your organisation account to join.”
  • The button reads Sign in instead of Accept Invitation
  • Clicking it takes users to the login page, where they sign in with SSO

Deployment (Docker Compose)​

If using arcane-deployment, add the Okta variables to your .env and ensure they are passed to the backend service. The base and trace compose files do not include Okta vars by default; add them as needed:

OKTA_SSO_ENABLED=true
OKTA_SSO_ENTRY_POINT=https://your-org.okta.com/app/xxx/sso/saml
OKTA_ENTITY_ID=https://your-org.okta.com/app/xxx/sso/saml/metadata
OKTA_SAML_CERT=-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----
OKTA_ISSUER_URL=https://your-org.okta.com
BETTER_AUTH_SSO_DOMAIN=your-frontend-domain.com
ARCANE_ENTERPRISE_LICENSE=your-enterprise-license

Then add these to the backend environment block in your docker-compose file, or use an env file:

backend:
  env_file: .env
  # ... rest of service config

Troubleshooting​

IssuePossible causeAction
"Sign in with SSO" button not visibleBackend not configured for SSOEnsure backend has OKTA_SSO_ENABLED=true, valid license, and Okta env vars set; check /api/config response
SSO fails with "invalid entity"Mismatch between Okta and Arcane metadataVerify OKTA_ENTITY_ID and OKTA_SSO_ENTRY_POINT match Okta app settings
Certificate errorIncorrect OKTA_SAML_CERT formatUse PEM format; replace real newlines with \n in env vars
Backend fails to start with Okta enabledMissing env vars or invalid licenseEnsure OKTA_SSO_ENTRY_POINT, OKTA_SAML_CERT, OKTA_ENTITY_ID are set and ARCANE_ENTERPRISE_LICENSE is valid
  • RBAC — Role-based access control for organisations and projects
  • Deployment — Docker Compose deployment
  • Managing Users — Invite users to organisations