diff --git a/docs.json b/docs.json index 76a3ebf7a..97abb39f9 100644 --- a/docs.json +++ b/docs.json @@ -571,6 +571,7 @@ "icon": "building", "pages": [ "openhands/usage/cloud/organizations/overview", + "openhands/usage/cloud/organizations/configuring-organizations", "openhands/usage/cloud/organizations/managing-members", "openhands/usage/cloud/organizations/roles-permissions", "openhands/usage/cloud/organizations/settings", diff --git a/enterprise/vm-install/admin-console-configuration.mdx b/enterprise/vm-install/admin-console-configuration.mdx index 2052f18b0..e06be4c49 100644 --- a/enterprise/vm-install/admin-console-configuration.mdx +++ b/enterprise/vm-install/admin-console-configuration.mdx @@ -127,11 +127,13 @@ Changing this password restarts LiteLLM. Models added in LiteLLM appear in the O | Field | Description | |---|---| | `Enable Default OpenHands Organization` | Lets the first user who signs in create and own the default organization. | -| `Automatically Add Signed-In Users` | Adds authenticated users to the default organization as members. | -| `Hide Personal Workspaces` | Shows the default organization as the only workspace. Existing personal data is hidden, not deleted. | +| `Automatically Add Signed-In Users` | Adds authenticated users to the default organization as members. Checked by default once the default organization is enabled. | +| `Hide Personal Workspaces` | Shows the default organization as the only workspace. Existing personal data is hidden, not deleted. Checked by default once the default organization is enabled. | These settings are additive. Disabling them does not delete organizations, remove members, or demote users. +For what each setting does and how to move an existing installation to organizations, see [Configuring Organizations](/openhands/usage/cloud/organizations/configuring-organizations). + ## Authentication and Integrations The following groups appear independently and reveal additional required fields when enabled. @@ -284,7 +286,7 @@ If you use external PostgreSQL, create and grant access to the Automations datab | `Custom LLM Extra HTTP Headers (JSON)` | JSON object containing static string header values. Treat these values as secrets when they contain credentials. | | `Login Session Idle Timeout (seconds)` | Maximum inactivity period before a user must sign in again. | | `Login Session Max Duration (seconds)` | Maximum total login-session lifetime, regardless of activity. | -| `Enable OEM User Creation Flow` | Lets OEM deployments provision organizations and users through the supported OEM flow. | +| `Enable OEM User Creation Flow` | Lets OEM deployments provision organizations and users through the supported OEM flow. See [User Provisioning](/openhands/usage/cloud/organizations/configuring-organizations#user-provisioning). | Change advanced options only when the corresponding integration or deployment requirement is understood. diff --git a/openhands/usage/cloud/organizations/configuring-organizations.mdx b/openhands/usage/cloud/organizations/configuring-organizations.mdx new file mode 100644 index 000000000..92852df52 --- /dev/null +++ b/openhands/usage/cloud/organizations/configuring-organizations.mdx @@ -0,0 +1,164 @@ +--- +title: Configuring Organizations +description: Settings that control the default organization, personal workspaces, and user provisioning, and how to move an existing installation to organizations. +--- + + + These settings apply to self-hosted OpenHands Enterprise, not to OpenHands Cloud (SaaS). For the concepts + behind them, see the [Organizations Overview](/openhands/usage/cloud/organizations/overview#key-concepts). + + +## Settings and Defaults + +Out of the box, none of these settings are on. Every user has only a personal workspace, and an installation +that predates these settings keeps working that way until you change them. + +A VM install and a Kubernetes install are configured differently but set the same underlying values. The Admin +Console applies its options to the Helm chart's `env` values when you deploy. + + + + Set these in the Admin Console. The default organization options are under **Default OpenHands Organization** + and the provisioning option is under **Advanced Options**. Save the config and deploy the new version for a + change to take effect. See [Admin Console Configuration](/enterprise/vm-install/admin-console-configuration). + + | Setting | Admin Console option | Default | + |---|---|---| + | Default organization | `Enable Default OpenHands Organization` | Unchecked | + | Add users automatically | `Automatically Add Signed-In Users` | Checked, once the default organization is enabled | + | Hide personal workspaces | `Hide Personal Workspaces` | Checked, once the default organization is enabled | + | User provisioning | `Enable OEM User Creation Flow` | Unchecked | + + The default organization is named `Enterprise Org`. The name cannot be changed from the Admin Console, but the + owner can rename the organization in the app. + + + Checking `Enable Default OpenHands Organization` reveals `Automatically Add Signed-In Users` and + `Hide Personal Workspaces`, both already checked. If you save without changing them, every user is added to + the default organization and their personal workspace is hidden. To roll out gradually, uncheck + `Hide Personal Workspaces` before you deploy. + + + + Set these in the Helm `values.yaml`. Each one is off unless you set it. + + | Setting | Helm value | Default | + |---|---|---| + | Default organization | `env.OPENHANDS_DEFAULT_ORG_ENABLED` | Off | + | Add users automatically | `env.OPENHANDS_DEFAULT_ORG_AUTO_ADD_USERS` | Off | + | Hide personal workspaces | `env.HIDE_PERSONAL_WORKSPACES` and `env.OH_WEB_CLIENT_FEATURE_FLAGS_HIDE_PERSONAL_WORKSPACES` | Off | + | Default organization name | `env.OPENHANDS_DEFAULT_ORG_NAME` | `Enterprise Org` | + | User provisioning | `userProvisioning.enabled` | Off | + + ```yaml + env: + OPENHANDS_DEFAULT_ORG_ENABLED: "true" + OPENHANDS_DEFAULT_ORG_AUTO_ADD_USERS: "true" + OPENHANDS_DEFAULT_ORG_NAME: "Acme Engineering" # optional + # Optional. Set both to hide personal workspaces. + HIDE_PERSONAL_WORKSPACES: "true" + OH_WEB_CLIENT_FEATURE_FLAGS_HIDE_PERSONAL_WORKSPACES: "true" + + userProvisioning: + enabled: true + ``` + + Hide personal workspaces only together with the default organization and automatic membership, because users + need a workspace to land in. The Admin Console enforces this. Helm does not. + + + +## Default Organization + +Turning on `Enable Default OpenHands Organization` makes OpenHands set up the default organization the next time +a user signs in: + +- **No team organization exists.** The first user to sign in creates it, named `Enterprise Org` unless you set a + name on a Kubernetes install, and becomes its owner. +- **Exactly one team organization exists.** It is adopted as the default organization. No duplicate is created. +- **Two or more team organizations exist.** Nothing is created or adopted, because OpenHands cannot tell which one + is meant to be the default. + +The default organization is tracked by a flag, not by its name, so the owner can rename it in the app. + +### Automatically Add Signed-In Users + +With `Automatically Add Signed-In Users` on, every user who signs in is added to the default organization as a +`Member`. The first time a user is added, the default organization becomes their current organization. After +that, a user who switches back to their personal workspace stays there, unless personal workspaces are hidden. + +With it off, users join the default organization by invitation only. + +### Hide Personal Workspaces + +`Hide Personal Workspaces` is available only when the default organization and automatic membership are both on. +Turning either one off also turns hiding off. + +When it is on: + +- **The personal workspace disappears from the organization selector** for users who belong to at least one team + organization. A user whose only workspace is personal still sees it, so no one is left with nothing. +- **Users parked on a personal workspace are moved** to the default organization when they next sign in, if they + are a member of it. +- **Nothing is deleted.** Conversations, secrets, API keys, and automations in a personal workspace are hidden, + not removed. Turning the setting off shows them again. +- **Personal workspaces are still created** for new users. Hiding changes what users see, not what exists. + +### Turning Settings Off + +These settings are additive. Turning them off does not delete organizations, remove members, or demote users. +Users stay in the default organization, and hidden personal workspaces reappear. + +## User Provisioning + +`Enable OEM User Creation Flow` and `userProvisioning.enabled` both set `USER_PROVISIONING_ENABLED=true` on the +app server. This registers `POST /api/organizations/provision-user`, which lets a super admin, or an organization +owner or admin for their own organization, create a user with a password and an API key. While the setting is +off, that endpoint returns `404`. Creating organizations and managing super admins are always available to +super admins. + +On OpenHands Enterprise 1.62.0 or later, turning this setting on also lets any signed-in user list the super +admins. + + + User provisioning creates accounts with passwords and API keys. Turn it on only when you need to create users + without any user input, and turn it off again when you no longer do. + + +For a worked example, see [Provision Users](/cookbook/provision-users). + +## Moving an Existing Installation to Organizations + +An installation that predates organizations has only personal workspaces. You can move to team organizations +without interrupting anyone, because nothing in these steps deletes or hides data until you choose to hide +personal workspaces. + + + + Only a super admin can create organizations. Use the + [Super Admins and Organizations](/cookbook/org-admin) example to find yours and grant the role to more people. + + + A super admin creates the organization, then invites its first owner. An invited user who already has an + account is added at their next sign-in. If they were working in their personal workspace, they land in the new + organization and keep the personal one. + + + - **One shared organization for everyone.** Turn on `Enable Default OpenHands Organization` and + `Automatically Add Signed-In Users`. The team organization you created is adopted as the default + organization, and users are added to it as they sign in. On a VM install, uncheck + `Hide Personal Workspaces` before you deploy, because it is checked by default. + - **Several team organizations.** Leave the default organization off and invite people to the organization + they belong to. With two or more team organizations, the default organization is not set up. + + + Once users are in the default organization, turn on `Hide Personal Workspaces` if you want it to be the only + workspace users see. You can turn it off again at any time to bring personal workspaces back. + + + +## Next Steps + +- [Managing Members](/openhands/usage/cloud/organizations/managing-members) - Invite users and manage roles. +- [Roles and Permissions](/openhands/usage/cloud/organizations/roles-permissions) - Understand the permission levels. +- [Admin Console Configuration](/enterprise/vm-install/admin-console-configuration) - Every Admin Console option on a VM install. diff --git a/openhands/usage/cloud/organizations/overview.mdx b/openhands/usage/cloud/organizations/overview.mdx index d1df8a313..c77b2cd7b 100644 --- a/openhands/usage/cloud/organizations/overview.mdx +++ b/openhands/usage/cloud/organizations/overview.mdx @@ -24,6 +24,56 @@ Organizations provide the following capabilities: - **Default LLM Configuration** - Define the default model provider and LLM that all members can use. - **Git Organization Claiming** - Claim specific Git organizations to route OpenHands resolver requests to your organization. +## Key Concepts + +### Personal Workspaces and Team Organizations + +Every user has a **personal workspace**, created automatically the first time they sign in. It is a private +organization for one person. Conversations, secrets, API keys, and automations created while it is the current +organization belong to it. + +A **team organization** is one you create on purpose to share resources. It has members with +[roles](/openhands/usage/cloud/organizations/roles-permissions), a default LLM configuration, shared credits, +and optional Git organization claims. A user can belong to their personal workspace and any number of team +organizations at the same time. + +### Current Organization + +Each user has one **current organization**. It decides where new conversations are created and which settings +apply. Switch between organizations from the organization selector in the app. The selector is hidden when +there is only one organization to choose from. + +OpenHands remembers each user's last selection. Requests that do not name an organization use it, for example +API calls made with an API key that is not tied to an organization. + +### Super Admins + + + Super admins apply to OpenHands Enterprise. + + +A **super admin** is an instance-level role, separate from the organization roles `Owner`, `Admin`, and `Member`. +A super admin can create organizations, invite or provision users into them, grant or revoke the super admin +role, and set organization quotas. A super admin does not get organization-level permissions in organizations +it is not a member of, and is not added as a member of the organizations it creates. + +On OpenHands Enterprise, only super admins can create organizations. To find your super admin or add more, see +the [Super Admins and Organizations](/cookbook/org-admin) cookbook example. + +### Default Organization + + + The default organization applies to OpenHands Enterprise. + + +A **default organization** is an optional team organization that an administrator turns on for the whole +installation. It can add every user who signs in to the same organization as a member, and can hide personal +workspaces so it is the only workspace users see. + +Existing data is never deleted when you turn these settings on or off. See +[Configuring Organizations](/openhands/usage/cloud/organizations/configuring-organizations) for the settings, +what each one does, and how to move an existing installation to organizations. + ## Conversation Visibility By default, conversations remain **private to individual members** of an organization. Each user's conversations @@ -34,7 +84,7 @@ are only visible to them. To start using Organizations: 1. Subscribe to an OpenHands Cloud plan or OpenHands Enterprise. -2. Create a new organization from the OpenHands Cloud dashboard. +2. Create a new organization. In OpenHands Cloud, use the dashboard. In OpenHands Enterprise, a [super admin](#super-admins) creates it. See [Configuring Organizations](/openhands/usage/cloud/organizations/configuring-organizations). 3. [Invite team members](/openhands/usage/cloud/organizations/managing-members) to join your organization. 4. Configure your organization's [LLM settings](/openhands/usage/cloud/organizations/settings) and shared resources. @@ -43,3 +93,4 @@ To start using Organizations: - [Managing Members](/openhands/usage/cloud/organizations/managing-members) - Learn how to invite users and manage roles. - [Organization Settings](/openhands/usage/cloud/organizations/settings) - Configure LLM providers, credits, and Git organization claims. - [Roles and Permissions](/openhands/usage/cloud/organizations/roles-permissions) - Understand the different permission levels. +- [Configuring Organizations](/openhands/usage/cloud/organizations/configuring-organizations) - Settings for the default organization, personal workspaces, and user provisioning, and how to migrate an existing installation.