> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/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, and you
need it in the next step.

## 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 **Connect to Enterprise SSO**.
3. Complete sign-in with your identity provider.
4. Confirm you return to OpenHands signed in.