diff --git a/docs.json b/docs.json index 085b0c759..408d49a61 100644 --- a/docs.json +++ b/docs.json @@ -554,7 +554,13 @@ "enterprise/integrations/bitbucket-data-center", "enterprise/integrations/jira-cloud", "enterprise/integrations/jira-data-center", - "enterprise/integrations/saml-sso", + { + "group": "SAML SSO", + "pages": [ + "enterprise/integrations/saml-sso", + "enterprise/integrations/saml-providers/authentik" + ] + }, "enterprise/integrations/slack", "enterprise/integrations/external-llm-gateways", "enterprise/integrations/observability-platforms" diff --git a/enterprise/integrations/saml-providers/authentik.mdx b/enterprise/integrations/saml-providers/authentik.mdx new file mode 100644 index 000000000..cf53b4833 --- /dev/null +++ b/enterprise/integrations/saml-providers/authentik.mdx @@ -0,0 +1,202 @@ +--- +title: Authentik +description: Configure Authentik as a SAML identity provider for OpenHands Enterprise. +icon: key +--- + +This guide walks through configuring [Authentik](https://goauthentik.io/) as a +SAML identity provider for OpenHands Enterprise. It is a provider-specific +companion to the [SAML SSO](/enterprise/integrations/saml-sso) guide. Follow the +steps here first, then use the values from the [last section](#values-for-openhands) +to complete [Step 2 of the SAML SSO guide](/enterprise/integrations/saml-sso#step-2-enable-saml-sso). + +## Prerequisites + +- An Authentik instance reachable over HTTPS with a certificate from a trusted + certificate authority. OpenHands fetches the metadata server-side and rejects + untrusted or self-signed TLS certificates. +- Authentik administrator access. +- Your OpenHands Authentication hostname, which is `auth.` + by default. The examples below use `auth.openhands.example.com`. + +Authentik creates the application and its SAML provider together in a single +**New application** wizard. In the admin interface, go to **Applications → +Applications** and choose **Create with Wizard**. + +## Step 1: Configure the Application + +On the **Application** step, set the core application fields: + +| Field | Value | +| --- | --- | +| Application Name | `OpenHands` | +| Slug | `openhands` | +| Group | leave blank (optional) | +| Policy engine mode | `ANY` (default) | + +The slug becomes part of the metadata URL, so keep it consistent with the value +you use in the [last section](#values-for-openhands). + +### Configure the UI settings + +Expand **UI Settings**. These settings control how OpenHands appears on the +Authentik **User Dashboard**, the launch directory where users see the +applications available to them. Configuring them lets a user open OpenHands +directly from Authentik with one click, in addition to signing in from the +OpenHands sign-in page. + +1. **Set the Launch URL.** Enter your OpenHands URL so the dashboard tile links + to the application: + + ``` + https://app. + ``` + + If you leave this blank, Authentik tries to infer a launch URL from the + provider, which does not produce a usable link for this integration. + +2. **Upload an application icon.** The icon is shown next to OpenHands on the + User Dashboard, so users can recognize it at a glance. Download the OpenHands + icon below, save it to your machine, then upload it in the **Icon** field. + + + OpenHands icon + + + [Download the OpenHands icon](/enterprise/integrations/saml-providers/images/openhands-icon.png) + + + Uploading an icon requires authentik to have media storage configured, + which is the default for standard installations. If your instance cannot + store uploaded files, you can instead set the icon to a publicly reachable + image URL. + + +Choose **Next**. + +## Step 2: Choose a Provider Type + +Select **SAML Provider**, then choose **Next**. + + + Choose **SAML Provider**, not **SAML Provider from Metadata**. The + metadata option is for importing an existing provider's metadata, which is not + what you want here. + + +## Step 3: Configure the SAML Provider + +Fill in the provider details: + +| Field | Value | +| --- | --- | +| Name | `Provider for OpenHands` | +| Authorization Flow | `default-provider-authorization-implicit-consent (Authorize Application)` | +| ACS URL (under **Protocol settings**) | `https://auth.openhands.example.com/realms/allhands/broker/enterprise_sso/endpoint` | +| Audience | `https://auth.openhands.example.com/realms/allhands` | +| SLS URL | leave blank (optional) | + + + `enterprise_sso` and `allhands` are fixed values that OpenHands expects. Do + not change them. Replace only the `auth.openhands.example.com` hostname with + your Authentication hostname. + + +Expand **Advanced protocol settings** and configure: + +| Field | Value | +| --- | --- | +| Signing Certificate | select a certificate, for example `authentik Self-signed Certificate` | +| Property mappings | keep the defaults (7 mappings are selected, including Email, Name, and Username) | +| Service Provider Binding | `Post` | +| Default NameID Policy | `Persistent` | +| Digest algorithm | `SHA256` (default) | +| Signature algorithm | `SHA256` (default) | + + + You must set the **Signing Certificate**. Authentik leaves this field blank by + default, and without it the published metadata contains no signing + certificate. OpenHands then refuses to create the SSO provider and users fall + back to the built-in login page. This is the most common cause of a failed + Authentik integration. + + +Selecting a signing certificate reveals four signing toggles. Leave them at +their defaults: + +| Toggle | Setting | +| --- | --- | +| Sign assertions | **On** (default) | +| Sign responses | Off (default) | +| Sign logout requests | Off (default) | +| Sign logout response | Off (default) | + + + OpenHands validates the signature on the SAML **assertion**, so **Sign + assertions** must stay on — it is enabled by default once you select a signing + certificate, so no change is needed. You do not need to enable **Sign + responses**; leave the other toggles off. + + + + OpenHands provisions accounts from the SAML assertion and requires an email + address. The default property mappings already include + `authentik default SAML Mapping: Email`, so leave the selection as-is unless + you have customized it. + + +Choose **Next**. + +## Step 4: Configure Bindings (Optional) + +The **Configure Bindings** step controls which users can access the application. +By default there are no bound policies, which allows all Authentik users to sign +in — convenient for initial testing. To restrict access, choose **Bind existing +policy/group/user** and bind the group(s) that should have access. + +Choose **Next**. + +## Step 5: Review and Submit + +Review the application and provider details, then choose **Create Application**. + +## Create a Test User + +SSO authenticates against Authentik, so you need at least one Authentik user +with an email address. + +1. Go to **Directory → Users** and choose **Create**. +2. Set a username and an **email address** (required for account provisioning in + OpenHands). +3. Set a password for the user, or use the existing `akadmin` account. + +## Values for OpenHands + +Use these values to complete +[Step 2 of the SAML SSO guide](/enterprise/integrations/saml-sso#step-2-enable-saml-sso). +Replace the hostname and slug with your own. + +| OpenHands setting | Value | +| --- | --- | +| SAML Metadata URL | `https:///application/saml/openhands/metadata/` | +| Identity Provider Display Name | e.g. `Company SSO (via Authentik)` | + + + Use the bare `.../metadata/` URL. OpenHands fetches it server-side, where + Authentik serves the raw XML directly, so no `?download` suffix is needed. If + you open that URL in a browser you may be redirected to the Authentik login; + that redirect does not affect OpenHands' server-side fetch. + + +To inspect the metadata yourself and confirm it contains a signing certificate, +add `?download` and follow redirects: + +```bash +curl -sL "https:///application/saml/openhands/metadata/?download" \ + | grep -c X509Certificate # expect >= 1 +``` diff --git a/enterprise/integrations/saml-providers/images/openhands-icon.png b/enterprise/integrations/saml-providers/images/openhands-icon.png new file mode 100644 index 000000000..efa92f7b7 Binary files /dev/null and b/enterprise/integrations/saml-providers/images/openhands-icon.png differ diff --git a/enterprise/integrations/saml-sso.mdx b/enterprise/integrations/saml-sso.mdx index 43d1eb1cb..7605f2dc3 100644 --- a/enterprise/integrations/saml-sso.mdx +++ b/enterprise/integrations/saml-sso.mdx @@ -53,6 +53,9 @@ need this URL in the next step. application. +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.