> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-docs-saml-authentik-screenshots.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SAML SSO

> Enable SAML single sign-on for OpenHands Enterprise and connect your corporate identity provider.

This guide explains how to let users sign in to an OpenHands Enterprise
installation with your corporate identity provider (for example Okta, Microsoft
Entra ID, Google Workspace, or ADFS) over SAML.

## Prerequisites

* An OpenHands Enterprise installation.
* Administrator access to your corporate identity provider, so you can create a
  SAML application and read its metadata.
* Your installation's Authentication hostname, which is
  `auth.<your-openhands-domain>` by default.

The URLs below use the default realm name, `allhands`.

## Step 1: Register OpenHands with Your Identity Provider

Create a SAML application in your identity provider with these values. Replace
`<your-auth-hostname>` with your Authentication hostname, for example
`auth.openhands.example.com`.

| Identity provider field                            | Value                                                                         |
| -------------------------------------------------- | ----------------------------------------------------------------------------- |
| Assertion Consumer Service (ACS) URL, or Reply URL | `https://<your-auth-hostname>/realms/allhands/broker/enterprise_sso/endpoint` |
| Entity ID, or Audience                             | `https://<your-auth-hostname>/realms/allhands`                                |
| Name ID format                                     | `persistent` (recommended) or `email`                                         |

Send these attribute statements with the SAML response:

* `email` (required)
* `firstName` and `lastName` (recommended)

Assign the application to the users and groups that should have access to
OpenHands. Then copy the application's SAML metadata URL, sometimes called the
entity descriptor or federation metadata URL. It must be an HTTPS URL served
with a certificate from a trusted certificate authority (OpenHands fetches the
metadata server-side and rejects untrusted or self-signed TLS certificates). You
need this URL in the next step.

<Warning>
  Your identity provider must **sign SAML assertions** and publish a **signing
  certificate** in its metadata. OpenHands validates the assertion signature, so
  the metadata must contain an entity ID, a single sign-on service URL, and a
  signing certificate. If the signing certificate is missing, OpenHands skips
  creating the SSO provider and users fall back to the built-in login page. Most
  identity providers include the signing certificate by default, but some
  require you to explicitly assign a signing certificate to the SAML
  application.
</Warning>

For provider-specific, step-by-step instructions, see the guide for your
identity provider: [Authentik](/enterprise/integrations/saml-providers/authentik).

## Step 2: Enable SAML SSO

Pick the path that matches how OpenHands Enterprise is deployed.

<Tabs>
  <Tab title="Replicated">
    Open the Replicated Admin Console for your OpenHands Enterprise
    installation and go to the application configuration page.

    In **Enterprise SSO (SAML) Authentication**:

    1. Enable **Enable Enterprise SSO Authentication**.
    2. Enter your identity provider's metadata URL in **SAML Metadata URL**.
    3. Optionally change the **Identity Provider Display Name**.
    4. Save and deploy the updated configuration.
  </Tab>

  <Tab title="Standalone Helm">
    In your `values.yaml` for the `openhands` chart:

    ```yaml theme={null}
    enterpriseSSO:
      enabled: true
      displayName: "Company SSO"
      idpMetadataUrl: "https://idp.example.com/saml/metadata"
    ```

    Then redeploy the `openhands` chart.
  </Tab>
</Tabs>

If your identity provider rotates its signing certificates, redeploy to pick up
the new metadata.

## Step 3: Verify Sign-In

1. Open `https://app.<your-openhands-domain>` in a private browser window.
2. Choose the Enterprise SSO button. Its label is the **Identity Provider
   Display Name** you configured (for example, `Company SSO`).
3. Complete sign-in with your identity provider.
4. Confirm you return to OpenHands signed in.

## Troubleshooting

### The SSO button shows the OpenHands login form instead of your identity provider

This means OpenHands did not create the SSO provider from your metadata. The
most common cause is a missing signing certificate in the identity provider's
SAML metadata. Confirm the metadata includes a signing certificate (see the
warning in [Step 1](#step-1-register-openhands-with-your-identity-provider)),
then save and deploy again.

You can inspect the metadata for a signing certificate by downloading it and
checking for an `X509Certificate` element inside a `KeyDescriptor` with
`use="signing"`:

```bash theme={null}
curl -sL "https://idp.example.com/saml/metadata" | grep -c X509Certificate
```

A result of `0` means no certificate is published, and SSO provisioning will
fail.

### OpenHands cannot fetch the metadata URL

OpenHands fetches the metadata URL server-side. Make sure the URL is reachable
from the cluster and is served with a certificate from a trusted certificate
authority. Self-signed or untrusted TLS certificates cause the fetch to fail.

### Sign-in succeeds but no account is created

The SAML response is missing the `email` attribute. Configure your identity
provider to release `email` (see [Step 1](#step-1-register-openhands-with-your-identity-provider)).