> ## 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.

# SSO / SAML

> Connect an identity provider to Essal Access using SAML 2.0 or OIDC for single sign-on.

Essal Access supports enterprise single sign-on via **SAML 2.0** and **OpenID Connect (OIDC)**. Once configured, users from your identity provider can log into any Essal app without a separate Essal password.

## Supported Protocols

| Protocol | Use When                                                          |
| -------- | ----------------------------------------------------------------- |
| SAML 2.0 | Your IdP is Okta, ADFS, or any SAML-capable provider              |
| OIDC     | Your IdP is Google Workspace, Auth0, or any OIDC-capable provider |

## SAML 2.0 Setup Summary

1. Create an SSO connection in Essal Access:
   * `POST /v1/access/sso/connections` with `"protocol": "saml2"` and your IdP metadata URL
2. Configure your IdP with Essal's ACS URL (`https://access.essal.cloud/sso/saml/callback`) and entity ID
3. Map IdP group claims to Essal roles
4. Test with `POST /v1/access/sso/connections/{id}/test`
5. Activate: `PATCH` with `"status": "active"`

See the full walkthrough in [Set Up SSO](/guides/access/setup-sso).

## OIDC Setup Summary

1. Register Essal as an OAuth client in your IdP
2. Create an OIDC connection: `POST /v1/access/sso/connections` with `"protocol": "oidc"`, discovery URL, client ID, and secret
3. Map scopes and claims
4. Test and activate

## Enforcing SSO

Once active, enforce SSO to disable password-based login for your domain:

```bash theme={null}
PATCH /v1/access/sso/connections/{id}
{ "enforce": true }
```

<Note>
  Service accounts and API keys are not affected by SSO enforcement. Only interactive user logins are federated through the IdP.
</Note>

## JIT Provisioning

By default, Essal creates a new user account automatically when a known-domain user first logs in via SSO (Just-in-Time provisioning). Assign default roles for JIT-provisioned users:

```bash theme={null}
PATCH /v1/access/sso/connections/{id}
{
  "jit_provisioning": {
    "enabled": true,
    "default_roles": ["office:viewer", "project:viewer"]
  }
}
```