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

# Identity Provider

> Connect your HoneyHive deployment to an OIDC identity provider in a self-hosted or managed environment.

Connect HoneyHive to your own OIDC identity provider (IdP) so your team signs in with the accounts they already have. This page walks through configuring an OIDC IdP for a self-hosted deployment.

<Note>
  HoneyHive supports connecting your own custom identity provider across all deployment types: self-hosted, single-tenant SaaS, and multi-tenant SaaS. The setup differs by type:

  * **Self-hosted:** You configure a custom OIDC IdP directly in the control-plane Helm chart, using the steps on this page.
  * **Single-tenant and multi-tenant SaaS:** HoneyHive sets up a SAML SSO integration for you through our authentication provider. You share your IdP's SAML metadata with us rather than editing chart values. To get started, [Contact us](mailto:sales@honeyhive.ai) or reach out to your account team.
</Note>

## Prerequisites

* A self-hosted HoneyHive deployment installed with the control-plane Helm chart.
* An OIDC-capable identity provider where you can register an application, such as Keycloak, PingFederate, Ping One, Okta, Auth0, or Azure Entra ID.
* Permission to edit your deployment's Helm values and Kubernetes secrets.

## Step 1: Register an OIDC application in your IdP

<Info>
  These OIDC application and redirect/logout URI instructions apply to self-hosted deployments. On single-tenant or multi-tenant SaaS, you register a SAML application instead and share its metadata with HoneyHive.
</Info>

Create a new OIDC (OpenID Connect) application in your identity provider and configure these redirect URIs, replacing `app.your-domain.com` with the public URL of your HoneyHive app:

| Setting                 | Value                                           |
| ----------------------- | ----------------------------------------------- |
| Redirect / callback URI | `https://app.your-domain.com/api/auth/callback` |
| Logout redirect URI     | `https://app.your-domain.com/api/auth/logout`   |

After creating the application, note its **client ID** and **client secret**. You supply both to the control plane in the next steps.

Your IdP must expose the standard OIDC discovery document at:

```
https://<issuerDomain>/.well-known/openid-configuration
```

The control plane reads this endpoint to discover your IdP's authorization, token, and JWKS endpoints. `<issuerDomain>` is your issuer host and path without a scheme, for example `auth.example.com/oidc`.

## Step 2: Configure the control-plane chart

<Note>
  These chart values apply to self-hosted deployments only. On SaaS, HoneyHive manages this configuration and you provide SAML metadata instead.
</Note>

Set your IdP details under `common.auth` in the control-plane chart's values:

```yaml theme={null}
common:
  auth:
    issuerDomain: "auth.example.com/oidc"      # issuer host + path, no scheme
    frontendPublicUrl: "https://app.your-domain.com"
    clientId: "your-oidc-client-id"
    audience: "https://cp-backend"             # must match the audience / API identifier configured in your IdP
```

| Value                           | Description                                                                                                                  | Required |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- |
| `common.auth.issuerDomain`      | Your IdP's OIDC issuer host and path, without a scheme                                                                       | Yes      |
| `common.auth.frontendPublicUrl` | Public URL of your HoneyHive app                                                                                             | Yes      |
| `common.auth.clientId`          | Client ID of the OIDC application you registered                                                                             | Yes      |
| `common.auth.audience`          | OAuth audience the control plane expects for access tokens. Must match the audience or API identifier configured in your IdP | Yes      |

<Note>
  Although the control-plane chart leaves `audience` commented out by default, the application requires it. Set it, or the control plane fails to start.
</Note>

There is no separate switch to turn SSO on. Populating these values, along with the client secret in the next step, enables OIDC authentication.

## Step 3: Provide the client secret

The client secret is never set inline. Store it in a Kubernetes secret (named `auth-secrets` by default) and point the chart at it:

```yaml theme={null}
common:
  externalSecrets:
    auth:
      secretName: "auth-secrets"
      clientSecretKey: "client-secret"
      jwtPrivateKeyKey: "cp-jwt-private-key"
```

The `auth-secrets` secret holds two keys:

* `client-secret`: the client secret from your OIDC application.
* `cp-jwt-private-key`: an internal RSA private key the control plane uses to sign its own session tokens. You generate this, not your IdP.

You can let the chart's secrets component create this secret from your secret store, or create it directly in the cluster.

## Step 4: Trust an internal or self-signed CA (optional)

If your IdP presents a certificate signed by an internal or self-signed CA, add the CA so the control plane trusts it when it calls your IdP:

```yaml theme={null}
common:
  auth:
    customCA:
      enabled: true
      certificate: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
```

## Step 5: Apply and sign in

<Note>
  The `helm upgrade` step applies to self-hosted deployments only. On SaaS, HoneyHive applies the configuration for you.
</Note>

Run `helm upgrade` with your updated values. Once the control plane restarts, users sign in through your IdP.

New users are added by invitation, then authenticate through the OIDC application you configured.

## Connectivity and air-gapped deployments

Authentication traffic flows from the control plane and users' browsers directly to the OIDC issuer you configure, starting with the discovery endpoint. Nothing in the chart routes authentication through HoneyHive's cloud or any HoneyHive-hosted service.

Whether your deployment stays fully air-gapped depends on where your IdP runs:

* **IdP inside your environment** (in-cluster or on-premise, such as Keycloak or PingFederate): authentication needs no traffic outside your environment. Use the `customCA` option from Step 4 to trust an internal certificate.
* **Externally hosted IdP** (for example Auth0, Okta, or Ping One cloud): the control plane makes outbound HTTPS calls to that issuer on each sign-in. This traffic goes to your IdP, never to HoneyHive.

Enabling authentication adds no dependency on HoneyHive-hosted services.

<CardGroup cols={2}>
  <Card title="Role-based access control" icon="user-shield" href="/v2/workspace/roles">
    Manage roles and permissions across your organization, workspaces, and projects.
  </Card>

  <Card title="Security" icon="shield" href="/v2/setup/security">
    Review HoneyHive's authentication, access control, and data security model.
  </Card>
</CardGroup>