Set Up SSO

Essal Access supports single sign-on via SAML 2.0 and OpenID Connect (OIDC). Once configured, users authenticate through your identity provider (IdP) and are automatically provisioned or matched to existing Essal accounts.

Supported Identity Providers

Essal Access has pre-built connection templates for common IdPs:

Okta
Microsoft Entra ID (Azure AD)
Google Workspace
Auth0
Generic SAML 2.0
Generic OIDC

Configuring SAML 2.0

Step 1: Create the Connection in Essal

POST /v1/access/sso/connections
{
  "name": "Acme Okta",
  "protocol": "saml2",
  "domain": "acme-corp.com",
  "metadata_url": "https://acme-corp.okta.com/app/exk123/sso/saml/metadata"
}

Essal will parse the metadata URL and extract the IdP certificate, SSO URL, and entity ID automatically.

Step 2: Configure Your IdP

In your IdP, create a new SAML application and set:

Field	Value
ACS URL	`https://access.essal.cloud/sso/saml/callback`
Entity ID	`https://access.essal.cloud`
Name ID Format	`EmailAddress`

Step 3: Map Claims to Roles

Define how IdP claims translate to Essal roles:

PATCH /v1/access/sso/connections/sso_01HXYZ1234
{
  "claim_mappings": [
    { "claim": "groups", "value": "essal-office-editors", "role": "office:editor" },
    { "claim": "groups", "value": "essal-project-admins", "role": "project:admin" }
  ]
}

Configuring OIDC

POST /v1/access/sso/connections
{
  "name": "Acme Google",
  "protocol": "oidc",
  "domain": "acme-corp.com",
  "discovery_url": "https://accounts.google.com/.well-known/openid-configuration",
  "client_id": "YOUR_GOOGLE_CLIENT_ID",
  "client_secret": "YOUR_GOOGLE_CLIENT_SECRET",
  "scopes": ["openid", "email", "profile"]
}

Use the SSO test endpoint to trigger a login flow without affecting production sessions:

POST /v1/access/sso/connections/sso_01HXYZ1234/test

This returns a test login URL you can open in a browser to validate the end-to-end flow.

SSO connections are not activated until you set "status": "active" on the connection object. This allows you to fully test before enabling SSO for your workspace.

Enforcing SSO

Once the connection is validated, enforce SSO for your domain so that password-based login is disabled:

PATCH /v1/access/sso/connections/sso_01HXYZ1234
{ "status": "active", "enforce": true }

Getting Started

Platform Concepts

App Guides — Office

App Guides — Access

App Guides — Sales

App Guides — Careers

App Guides — Project

App Guides — Guard

Integrations

Security & Compliance

Supported Identity Providers

Configuring SAML 2.0

Step 1: Create the Connection in Essal

Step 2: Configure Your IdP

Step 3: Map Claims to Roles

Configuring OIDC

Enforcing SSO

​Supported Identity Providers

​Configuring SAML 2.0

​Step 1: Create the Connection in Essal

​Step 2: Configure Your IdP

​Step 3: Map Claims to Roles

​Configuring OIDC

​Testing the Login Flow

​Enforcing SSO

Supported Identity Providers

Configuring SAML 2.0

Step 1: Create the Connection in Essal

Step 2: Configure Your IdP

Step 3: Map Claims to Roles

Configuring OIDC

Testing the Login Flow

Enforcing SSO