Skip to main content
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. 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.
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.
For provider-specific, step-by-step instructions, see the guide for your identity provider: Authentik.

​
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.
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), 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":
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).