> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up SSO

> Configure SAML 2.0 or OIDC single sign-on in Essal Access, map identity provider claims to roles, and test the login flow.

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

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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"]
}
```

## Testing the Login Flow

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

```bash theme={null}
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.

<Note>
  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.
</Note>

## Enforcing SSO

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

```bash theme={null}
PATCH /v1/access/sso/connections/sso_01HXYZ1234
{ "status": "active", "enforce": true }
```