diff --git a/docs.json b/docs.json index 0e3b3c47..09aefffd 100644 --- a/docs.json +++ b/docs.json @@ -551,6 +551,7 @@ "enterprise/integrations/bitbucket-data-center", "enterprise/integrations/jira-cloud", "enterprise/integrations/jira-data-center", + "enterprise/integrations/saml-sso", "enterprise/integrations/slack", "enterprise/integrations/external-llm-gateways" ] diff --git a/enterprise/integrations/saml-sso.mdx b/enterprise/integrations/saml-sso.mdx new file mode 100644 index 00000000..14d1e303 --- /dev/null +++ b/enterprise/integrations/saml-sso.mdx @@ -0,0 +1,82 @@ +--- +title: SAML SSO +description: Enable SAML single sign-on for OpenHands Enterprise and connect your corporate identity provider. +icon: user-shield +--- + +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.` 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 +`` with your Authentication hostname, for example +`auth.openhands.example.com`. + +| Identity provider field | Value | +| --- | --- | +| Assertion Consumer Service (ACS) URL, or Reply URL | `https:///realms/allhands/broker/enterprise_sso/endpoint` | +| Entity ID, or Audience | `https:///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. + + + + 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. + + + + In your `values.yaml` for the `openhands` chart: + + ```yaml + enterpriseSSO: + enabled: true + displayName: "Company SSO" + idpMetadataUrl: "https://idp.example.com/saml/metadata" + ``` + + Then redeploy the `openhands` chart. + + + +If your identity provider rotates its signing certificates, redeploy to pick up +the new metadata. + +## Step 3: Verify Sign-In + +1. Open `https://app.` 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.