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

# SSO with a custom IdP

> Connect any OpenID Connect or SAML 2.0 identity provider to Enclave — the generic field mappings that apply to Ping, ADFS, Auth0, Keycloak, OneLogin, and others.

Enclave is **IdP-agnostic** — any standards-compliant **OpenID Connect** or **SAML 2.0** provider works (Ping, ADFS, Auth0, Keycloak, OneLogin, JumpCloud, …). This page gives the generic mappings; for named providers see [Okta](/organization/sso/okta), [Entra ID](/organization/sso/entra-id), or [Google Workspace](/organization/sso/google-workspace).

<Info>
  **Where:** **Organization → Single Sign-On** in Enclave (Owner role). One email domain maps to one connection.
</Info>

## OIDC

<Steps>
  <Step title="Register a Web application at your IdP">
    * **Redirect URI:** `https://<your-enclave-host>/api/auth/oidc/callback`
    * **Scopes:** `openid`, `profile`, `email`
    * Note the **Client ID** and **Client Secret**.
  </Step>

  <Step title="Add the connection in Enclave">
    **Add Connection → OIDC** → **Custom**:

    | Field                     | Value                                                                                            |
    | ------------------------- | ------------------------------------------------------------------------------------------------ |
    | Domain                    | your email domain                                                                                |
    | Issuer URL                | your IdP's issuer — Enclave discovers endpoints from `{issuer}/.well-known/openid-configuration` |
    | Client ID / Client Secret | from the previous step                                                                           |
  </Step>
</Steps>

<Note>
  Enclave resolves the user's email from `email`, falling back to `preferred_username` then `upn` (both must contain `@`). Ensure your IdP releases one of these in the ID token.
</Note>

## SAML 2.0 — the generic field mapping

SAML config is entered field-by-field. The two mappings that trip people up: a **URL is not an Entity ID**, on both sides.

| Value                       | Where it comes from                                                                                        | Enclave field / IdP field          |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| **SSO URL**                 | your IdP's single sign-on endpoint                                                                         | Enclave **SSO URL**                |
| **IdP Entity ID / Issuer**  | the `entityID` in your IdP's metadata (**not** the metadata URL)                                           | Enclave **IdP Entity ID / Issuer** |
| **X.509 Certificate**       | your IdP's signing certificate (PEM)                                                                       | Enclave **X.509 Certificate**      |
| **ACS / Reply URL**         | `https://<your-enclave-host>/api/auth/saml/acs`                                                            | set at your IdP                    |
| **Audience / SP Entity ID** | the connection's **per-connection metadata URL** (`https://<host>/api/auth/saml/metadata/<connection-id>`) | set at your IdP                    |

<Warning>
  Two mirror-image gotchas: at your **IdP**, use the `entityID` value (not its metadata
  URL) for **IdP Entity ID / Issuer**; at Enclave's **SP** side, the Audience your IdP
  must send is the **per-connection metadata URL** (with the connection id), shown on
  the connection card. Both are shown/derivable from the connection card and the IdP's
  metadata.
</Warning>

### Signing & format

* Sign the **assertion** (or response) with **RSA-SHA256** / **SHA256 digest**.
* **Do not encrypt** the assertion (unencrypted only).
* **NameID:** `emailAddress` works for most IdPs; if yours rejects it (some ADFS/Entra setups), set the connection's **NameID Format** to **Persistent** or **Unspecified**.
* **SP certificate:** generate it one-click on the connection card, then import the per-connection **SP metadata URL** at your IdP.
* Multiple concatenated PEM certs are accepted in the certificate field to cover IdP **signing-key rotation**.

## Shared steps & troubleshooting

[Domain verification](/organization/sso/okta#verify-your-domain), SP-certificate generation, provisioning mode, Require-fresh-sign-in, and Single Logout are the same for every IdP — see [Authentication](/organization/authentication). The [troubleshooting table](/organization/sso/okta#troubleshooting) (audience / issuer / signature / timing / InResponseTo reasons) is provider-agnostic.