Overview

Permissions are used to control the actions of users and establish a security model. You can control resources managed by Che and allow certain actions by assigning permissions to users.

Permissions can be applied to the following:

  • Workspace

  • Organization

  • Stack

  • System

Workspace permissions

The user who creates a workspace is the workspace owner. The workspace owner has the following permissions by default: read, use, run, configure, setPermissions, and delete. Workspace owners invite users into the workspace and control workspace permissions for each user.

The following permissions are associated with workspaces:

Permission Description

read

Allows reading the workspace configuration.

use

Allows using a workspace and interacting with it.

run

Allows starting and stopping a workspace.

configure

Allows defining and changing the workspace configuration.

setPermissions

Allows updating the workspace permissions for other users.

delete

Allows deleting the workspace.

Organization permissions

An organization is a named set of users.

The following permissions are applicable to organizations:

Permission Description

update

Allows editing of the organization settings and information.

delete

Allows deleting an organization.

manageSuborganizations

Allows creating and managing sub-organizations.

manageResources

Allows redistribution of an organization’s resources and defining the resource limits.

manageWorkspaces

Allows creating and managing all the organization’s workspaces.

setPermissions

Allows adding and removing users and updating their permissions.

System permissions

System permissions control aspects of the whole Che installation.

The following permissions are applicable to the organization:

Permission Description

manageSystem

Allows control of the system, workspaces, and organizations.

setPermissions

Allows updating the permissions for users on the system.

manageUsers

Allows creating and managing users.

monitorSystem

Allows for accessing endpoints used for monitoring the state of the server.

All system permissions will be granted to the administration user configured with the `CHE_SYSTEM_ADMIN__NAME` property (the default is admin). This happens at Che Server start. If the user is not present in the Che user database, it happens after the user’s login.

manageSystem permission

Users with the manageSystem permission have access to the following services:

Path HTTP Method Description

/resource/free/

GET

Get free resource limits

/resource/free/{accountId}

GET

Get free resource limits for given account

/resource/free/{accountId}

POST

Edit free resource limit for given account

/resource/free/{accountId}

DELETE

Remove free resource limit for given account

/installer/

POST

Add installer to the registry

/installer/{key}

PUT

Update installer in the registry

/installer/{key}

DELETE

Remove installer from the registry

/logger/

GET

Get logging configurations in Che Server

/logger/{name}

GET

Get configurations of logger by its name in Che Server

/logger/{name}

PUT

Create logging in Che Server

/logger/{name}

POST

Edit logging in Che Server

/resource/{accountId}/details

GET

Get detailed information about resources for given account

/system/stop

POST

Shutdown all system services, prepare Che to stop

/stacks

All methods

All Stack service methods

monitorSystem permission

Users with the monitorSystem permission have access to the following services:

Path HTTP Method Description

/activity

GET

Get workspaces in certain state for a certain amount of time

Super-privileged mode

The manageSystem permission can be extended to provide a super-privileged mode. This allows the user to perform advanced actions on any resources managed by the system. You can read and stop any workspaces with the manageSystem permission and assign permissions to users as needed.

The super-privileged mode is disabled by default. You can change to super-privileged mode by configuring the `CHE_SYSTEM_SUPER__PRIVILEGED__MODE` variable to true in the che.env file.

List of services that are enabled for users with manageSystems permissions and with super-privileged mode on:

Path HTTP Method Description

/workspace/namespace/{namespace:.*}

GET

Get all workspaces for given namespace.

/workspace/{id}

DELETE

Stop workspace

/workspace/{key:.*}

GET

Get workspace by key

/organization/resource/{suborganizationId}/cap

GET

Get resource cap for given organization

/organization/resource/{suborganizationId}/cap

POST

Set resource cap for given organization

/organization/{parent}/organizations

GET

Get child organizations

/organization

GET

Get user’s organizations

Stack permissions

A stack is a runtime configuration for a workspace. See stack definition for more information on stacks.

The following permissions are applicable to stacks:

Permission Description

search

Allows searching of the stacks.

read

Allows reading of the stack configuration.

update

Allows updating of the stack configuration.

delete

Allows deleting of the stack.

setPermissions

Allows managing permissions for the stack.

Permissions API

All permissions can be managed using the provided REST API. The APIs are documented using Swagger at [{host}/swagger/#!/permissions].

Listing permissions

To list the permissions that apply to a specific resources, run this command:

$ GET /permissions

The domain values are:

Domain

system

organization

workspace

stack

domain is optional. In this case, the API returns all possible permissions for all domains.

Listing permissions for a user

To list the permissions that apply to a user, run this command:

$ GET /permissions/{domain}

The domain values are:

Domain

system

organization

workspace

stack

Listing permissions for all users

You must have sufficient permissions to see this information.

To list the permissions that apply to all users, run this command:

GET /permissions/{domain}/all

The domain values are:

Domain

system

organization

workspace

stack

Assigning permissions

To assign permissions to a resource, run this command:

POST /permissions

The domain values are:

Domain

system

organization

workspace

stack

The following is a message body that requests permissions for a user with a userID to a workspace with a workspaceID:

{
  "actions": [
    "read",
    "use",
    "run",
    "configure",
    "setPermissions"
  ],
  "userId": "userID",
  "domainId": "workspace",
  "instanceId": "workspaceID"
}

The instanceId parameter corresponds to the ID of the resource that retrieves the permission for all users. The userId parameter corresponds to the ID of the user that has been granted certain permissions.

Sharing permissions

A user with setPermissions privileges can share a workspace and grant read, use, run, configure, or setPermissions privileges to other users.

To share workspace permissions:

  • Select a workspace in the user dashboard, navigate to the Share tab and enter emails of users. Use commas or space as separators if there are multiple emails.