How do I set up SSO/SAML and RBAC in OpenHands Enterprise for multiple teams?

Single-sign-on and role-based access control only pay off if they’re wired into the same runtime that actually executes your agents. In OpenHands Enterprise, SSO/SAML and RBAC aren’t bolt-ons; they’re how you decide who can spin up autonomous agents, what repos they can touch, and which environments they can run in—across multiple teams and business units.

Quick Answer: In OpenHands Enterprise, you configure SSO/SAML with your identity provider (IdP), then map IdP groups or attributes into OpenHands roles and team scopes. From there, you define RBAC policies that control which users and groups can access specific projects, repositories, runtimes, and integrations—so each team gets autonomy inside a sandbox you control.

Why This Matters

If you’re rolling out cloud coding agents across more than one team, identity and access design becomes a production concern, not an IT afterthought. With SSO/SAML and RBAC wired into OpenHands Enterprise, you can give each engineering group scoped autonomy: agents that can open PRs, fix tests, and upgrade dependencies—but only in the repos, environments, and integrations they’re supposed to touch.

Without this, you get one of two failure modes: either a “god mode” agent that can see everything (and scares security), or a handful of bespoke, hardcoded setups that no one can safely scale. Centralized SSO and fine-grained RBAC let you scale OpenHands from a single pilot to a fleet of agents across multiple teams while keeping auditability, least-privilege access, and compliance intact.

Key Benefits:

Centralized identity with SSO/SAML: Use your existing IdP (Okta, Azure AD, etc.) so engineers sign in with the same corporate identity and lifecycle you already manage.
Least-privilege autonomy via RBAC: Precisely control which teams, repos, and runtimes each user and agent can access, instead of giving blanket permissions.
Scalable multi-team governance: Standardize roles and policies once, then reuse them across projects and business units as you expand OpenHands adoption.

Core Concepts & Key Points

Concept	Definition	Why it's important
SSO/SAML Integration	Connecting OpenHands Enterprise to your Identity Provider using SAML-based single sign-on.	Centralizes authentication, enforces MFA and session policies, and removes local password management.
RBAC (Role-Based Access Control)	A policy model where permissions are assigned to roles, and users/groups are mapped to those roles.	Enforces least privilege by mapping “who” (users/groups) to “what” (OpenHands capabilities and resources).
Team & Project Scoping	Structuring OpenHands into orgs, teams, and projects mapped to your actual engineering org chart and codebase.	Lets you give each team autonomous agents and sandboxed access to their repos and runtimes without cross-team bleed.

How It Works (Step-by-Step)

At a high level, setting up SSO/SAML and RBAC for multiple teams in OpenHands Enterprise follows a predictable pattern:

Connect OpenHands Enterprise to your IdP with SAML.
Map IdP groups or attributes to OpenHands roles and teams.
Apply RBAC policies to repos, runtimes, and integrations for each team.

Below is how I’d approach it as an engineering lead rolling this out across multiple groups.

1. Prepare Your Identity & Group Model

Before touching OpenHands, align identity and groups in your IdP:

Identify the scope of rollout.
Decide which engineering teams are in your initial wave (e.g., “Platform”, “Payments”, “Data Platform”).
Create or confirm IdP groups per team and function.
In Okta/Azure AD/GSuite, you’ll typically end up with something like:
- eng-platform-devs
- eng-payments-devs
- eng-data-devs
- eng-openhands-admins
- eng-openhands-observers (for auditors/security)
Define role semantics upfront.
Don’t let every group become a bespoke role. A simple, scalable pattern:
- Org Admin: Configures SSO, connections, runtimes, global RBAC policies.
- Team Lead / Project Admin: Manages team projects, repo bindings, and local policies.
- Engineer (Contributor): Can run agents, create PRs, fix tests within their team’s scope.
- Observer: Read-only; can view runs, diffs, and logs, but not execute agents.

These groups and their semantics are what you’ll map into OpenHands Enterprise.

2. Configure SSO/SAML with Your IdP

The specifics vary by IdP, but the flow is consistent: you create a SAML app for OpenHands, exchange metadata, and test login.

Create a new SAML application in your IdP.
In Okta, Azure AD, or similar, add a new “SAML 2.0” app:
- App name: OpenHands Enterprise
- Application type: SAML / SAML 2.0
Set the SAML endpoints using OpenHands Enterprise settings.
In OpenHands Enterprise (admin view), you’ll have SSO configuration fields like:
- Assertion Consumer Service (ACS) URL (a.k.a. SSO URL)
- Entity ID / Audience URI
- RelayState or default redirect URL (optional)
Copy these into your IdP app configuration.
Define SAML attributes and group claims.
In your IdP, configure the SAML assertion to include:
- email → user’s corporate email
- name / displayName → full name
- groups or a custom attribute (e.g., roles) listing IdP groups (eng-platform-devs, eng-openhands-admins, etc.)
Make sure the group names follow a consistent prefix or pattern; it simplifies mapping later.
Upload IdP metadata to OpenHands Enterprise.
From your IdP, download the SAML metadata XML (or copy:
- IdP Entity ID
- SSO URL
- x509 certificate)
In OpenHands Enterprise:
- Navigate to Admin > Authentication / SSO.
- Choose SAML as the provider.
- Paste or upload the metadata details.
- Map email and name attributes to OpenHands user fields.
Test SSO with a pilot admin account.
- Assign yourself to eng-openhands-admins in the IdP.
- Log out of OpenHands.
- Click “Sign in with SSO”.
- Confirm:
  - You’re redirected to IdP.
  - After login, you’re returned as an authenticated user.
  - Your role in OpenHands reflects the expected mapping (we wire this up in the next step).

Only once SSO is stable should you consider disabling local accounts or enforcing “SSO-only.”

3. Map IdP Groups to OpenHands Roles

Now you bind identity (groups) to capability (roles) inside OpenHands.

Define a role mapping strategy.
In OpenHands Enterprise admin settings, you’ll typically create mappings like:
- eng-openhands-admins → Org Admin
- eng-platform-devs → Team: Platform, Role: Engineer
- eng-payments-devs → Team: Payments, Role: Engineer
- eng-data-devs → Team: Data, Role: Engineer
- eng-openhands-observers → Org Observer
Configure group-to-role mappings.
In Admin > Authentication / SSO > Group Mappings:
- Add a new mapping rule:
  - If SAML group contains: eng-openhands-admins
  - Assign role: Org Admin
- Repeat for each team group:
  - If SAML group contains: eng-platform-devs
  - Assign team: Platform
  - Assign role: Engineer
Where possible, use pattern-based rules (e.g., eng-(.*)-devs) rather than hundreds of static entries; you can map pattern captures to teams.
Set a default role (optional but important).
For unrecognized groups, you may want:
- Default role: Observer or No access
- This prevents accidental elevation if group mapping fails.
Verify mapping with test users.
- Create test accounts in your IdP for each role.
- Login via SSO and check:
  - Org Admins see global admin controls.
  - Team Engineers see only their team’s projects and repos.
  - Observers can see runs/diffs but can’t execute agents.

4. Design Your Team & Project Structure in OpenHands Enterprise

RBAC is only as clear as your resource model. Align OpenHands structure with your org:

Create teams that mirror real org units.
In OpenHands Enterprise:
- Platform
- Payments
- Data Infrastructure
- Security / DevSecOps (if they’ll run vulnerability and dependency upgrades)
Within each team, define projects.
Projects should map to cohesive codebases or problem domains:
- Platform → ci-infra, internal-tooling, developer-portal
- Payments → payments-api, billing-service, ledger-service
- Data → data-pipelines, ml-platform
Bind repositories and environments to projects.
For each project:
- Connect the corresponding GitHub/GitLab repos.
- Define the sandboxed runtime(s) (Docker/Kubernetes environments) that agents can use.
- Attach CI/CD and Slack integrations where agents will post outputs or kick off pipelines.

This structure becomes the anchor for your RBAC rules.

5. Implement RBAC Policies Per Team and Project

With SSO and group mappings in place, you can now shape what each role can do.

Define organization-wide roles and capabilities.
In Admin > Roles / Permissions, confirm capabilities for:
- Org Admin: Manage SSO, connections, runtimes, global policies, and all projects.
- Team Admin / Lead: Add repos to their team, configure project-level policies, manage local credentials.
- Engineer (Contributor): Run agents, approve agent plans, create/merge PRs (if allowed), trigger CI runs.
- Observer: View runs, logs, and diffs; cannot execute or modify agents/runtimes.
Create project-level RBAC rules.
For each project:
- Grant Team Engineers:
  - read/write access to agent runs and artifacts in that project.
  - execute permission on the defined runtimes.
  - repo:read and repo:write for the bound repositories (PR creation, commits, branch pushes).
- Restrict cross-team access:
  - Platform engineers should not see or run agents in Payments projects, unless explicitly required.
- Allow Security or DevSecOps team:
  - “Maintenance-only” rights (e.g., run vulnerability and dependency upgrade agents) across designated repos without full developer privileges.
Apply fine-grained controls for high-risk resources.
For production-adjacent repos or sensitive services:
- Require explicit approval (from Team Lead or Org Admin) for:
  - Agents that modify infra-as-code (Terraform, Helm, Kustomize).
  - Agents that touch production config or secrets.
- Limit agent runtimes:
  - Use separate runtimes for production vs non-prod work.
  - Ensure production runtimes have tighter network egress and credentials.
Lock down credentials and integrations.
- Attach repo tokens, CI/CD tokens, and other scoped credentials to projects, not to individual users.
- Use RBAC to control:
  - Who can add or rotate credentials.
  - Which agents and roles can use specific credentials.

6. Test Governance with Real Workflows

Once RBAC is configured, run real tasks as validation, not just theoretical checks:

Use “happy path” scenarios:
- Platform engineer runs OpenHands from the terminal to:
  - Fix a failing test in ci-infra.
  - Push a PR and trigger CI.
- Payments engineer uses the Web GUI to:
  - Summarize open PRs and apply review feedback.
  - Generate release notes from merged PRs.
Test boundary conditions:
- Payments engineer tries to access Platform projects → should be blocked.
- Observer attempts to run an agent → should be denied with a clear message.
- Security engineer runs a dependency upgrade agent across multiple repos:
  - Should be allowed only in the repos you permit.
Review audit logs and artifacts:
- Validate that:
  - Every agent run is associated with an authenticated user via SSO identity.
  - Logs show which repos were touched and what diffs were generated.
  - You can re-run tasks deterministically from the same configuration.

This is where OpenHands’ “autonomy with observability” matters: you’re not trusting a black box, you’re inspecting concrete diffs and run traces tied back to SSO identities.

Common Mistakes to Avoid

Treating SSO/SAML as “just login”:
If you don’t propagate IdP groups into roles and teams, you lose most of the governance value. Always wire group/attribute-based mappings into OpenHands roles.
Using one giant “engineers” group:
A single broad group makes it impossible to scope access by team or project. Define at least per-team IdP groups and align them with OpenHands teams and RBAC.
Mixing personal and shared credentials:
Don’t paste user-specific tokens into OpenHands. Use project-scoped credentials managed by admins, and bind them via RBAC to specific agent runtimes and repos.
Skipping test runs before enforcing SSO-only:
Don’t disable local login until multiple test users and roles have validated SSO and mapping behavior.

Real-World Example

A regulated fintech’s platform team rolled out OpenHands Enterprise across three groups: Platform, Payments, and Risk. They already used Okta with well-defined engineering groups, so they:

Created a SAML app for OpenHands, exposed email, name, and groups in the assertion.
Mapped eng-openhands-admins to Org Admin, and eng-{team}-devs patterns to team-scoped Engineer roles in OpenHands.
Structured OpenHands into three teams with separate projects, repos, and runtimes.
Gave the Risk/Security team a “maintenance” role that allowed running vulnerability-remediation and dependency-upgrade agents across selected repos, but not touching application code paths outside that scope.

The result: the Payments team could use OpenHands headlessly in CI to fix flaky tests and maintain dependencies, while Platform used the Web GUI for shared triage and PR review automation. Security had full observability into every agent run and diff, with identities anchored in SSO, and audit logs they could pull into their SIEM.

Pro Tip: Start with one or two “golden path” workflows per team (e.g., “fix failing tests in this repo,” “generate release notes from PRs”), and design your RBAC policies around those. Once those paths are governed and observable, you can safely expand to more autonomous tasks.

Summary

To set up SSO/SAML and RBAC for multiple teams in OpenHands Enterprise, you wire your IdP into the platform, map IdP groups into OpenHands roles and teams, and then apply project-level policies that govern which agents can touch which repos and runtimes. The outcome isn’t just central login—it’s a governance layer that lets Platform, Payments, and Security each run autonomous cloud coding agents inside a sandbox you control, with full visibility into every run and diff.

When you can inspect the diff, trace the run, and re-run it deterministically, SSO and RBAC become more than compliance boxes; they become the backbone of safe, scalable autonomy across your engineering org.

Next Step

Get Started