Chapter 7. Managing users

Machines may contain services that must be protected with authentication, e.g. agents like workspace agent and terminal. For this purpose, machine authentication mechanism should be used. Machine tokens were introduced to avoid passing the Keycloak tokens to the machine side (which can be potentially insecure). Another reason is that Keycloak tokens may have relatively small lifetime and require periodical renewal/refresh which is hard to manage and keep in sync with same user session tokens on clients etc.

As agents cannot be queried using Keycloak token, there is only Machine Token option. Machine token can be also passed in header or query parameter.

# Header
{
  "alg": "RS512",
  "kind": "machine_token"
}
# Payload
{
  "wsid": "workspacekrh99xjenek3h571",
  "uid": "b07e3a58-ed50-4a6e-be17-fcf49ff8b242",
  "uname": "john",
  "jti": "06c73349-2242-45f8-a94c-722e081bb6fd"
}
# Signature
{
  "value": "RSASHA512(base64UrlEncode(header) + . +  base64UrlEncode(payload))"
}

7.9.2.2. Authentication schema

The way how CodeReady Workspaces master interacts with agents with enabled authentication mechanism is the following:

Machine token verification on agents is done by the following components:

• org.eclipse.che.multiuser.machine.authentication.agent.MachineLoginFilter - doing basically the same as the appropriate filter on a master, the only thing that is different it’s a way how agent obtains the public signature part. The public key for the signature check is placed in a machine environment, with algorithm description.
• auth.auth.go - the entry point for all request that is proceeding on go agents side, the logic of token verification is similar with MachineLoginFilter.

User’s Keycloak token is used to execute queries to secured API on his behalf through REST clients. A valid token must be attached as request header or query parameter - ?token=$token. CodeReady Workspaces Swagger can be accessed from http://che_host:8080/swagger. A user must be signed-in through Keycloak so that access token is included in request headers.

By default, swagger loads swagger.json from CodeReady Workspaces master.

To work with WS Agent, a URL to its swagger.json should be provided. It can be retrieved from Workspace Runtime, by getting URL to WS Agent server endpoint and adding api/docs/swagger.json to it. Also, to authenticate on WS Agent API, user must include Machine Token, which can be found in Workspace Runtime as well.

To use Swagger for a workspace agent, user must do following steps:

"wsagent/http": {
  "url": "http://172.19.20.180:32777/api",
  "attributes": {},
  "status": "RUNNING"
}

"machineToken": "eyJhbGciOiJSUzUxMiIsImtpbmQiOiJtYWNoaW5lX3Rva2VuIn0.eyJ3c2lkIjoid29ya3NwYWNlMzEiLCJ1aWQiOiJ1c2VyMTMiLCJ1bmFtZSI6InRlc3RVc2VyIiwianRpIjoiOTAwYTUwNWYtYWY4ZS00MWQxLWFhYzktMTFkOGI5OTA5Y2QxIn0.UwU7NDzqnHxTr4vu8UqjZ7-cjIfQBY4gP70Nqxkwfx8EsPfZMpoHGPt8bfqLWVWkpp3OacQVaswAOMOG9Uc9FtLnQWnup_6vvyMo6gchZ1lTZFJMVHIw9RnSJAGFl98adWe3NqE_DdM02PyHb23MoHqE_xd8z3eFhngyaMImhc4",

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

Permissions can be applied to the following:

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:

An organization is a named set of users.

The following permissions are applicable to organizations:

System permissions control aspects of the whole CodeReady Workspaces installation.

The following permissions are applicable to the organization:

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 CodeReady Workspaces Server start. If the user is not present in the CodeReady Workspaces user database, it happens after the user’s login.

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

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

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:

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

The following permissions are applicable to stacks:

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

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

$ GET /permissions

The domain values are:

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

$ GET /permissions/{domain}

The domain values are:

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

GET /permissions/{domain}/all

The domain values are:

To assign permissions to a resource, run this command:

POST /permissions

The domain values are:

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.

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:

Organizations allow administrators to group CodeReady Workspaces users and allocate resources. The system administrator controls and allocates resources and permissions within the administrator dashboard.

CHE_MAIL_PORT=465
CHE_MAIL_HOST=smtp.gmail.com
CHE_MAIL_SMTP_STARTTLS_ENABLE=true
CHE_MAIL_SMTP_AUTH=true
CHE_MAIL_SMTP_AUTH_USERNAME=no-reply@gmail.com
CHE_MAIL_SMTP_AUTH_PASSWORD=password

The Resource API manages the resources that are utilized by CodeReady Workspaces users. The CodeReady Workspaces administrators set the limits on the amount of resources available for each resource type and each user.

There are two kinds of accounts used in CodeReady Workspaces:

Resource usage mostly refers to resources used by workspaces and runtimes in the development flow.

CodeReady Workspaces supports the following types of resources:

Total resources

GET resource/${accountId}: Gets the list of total resources an account can use;

Used resources

GET resource/{accountId}/used: Gets the resources used by an account;

Available resources

GET resource/${accountId}/available: Gets the resources that are available and not used by an account. If no resources are used, the available resources equal total resources. If resources are used, the available resources equals total resources minus used resources.

Resource details

GET resource/{accountId}/details: Gets detailed information about the resources available for an account. The detailed information includes: resource providers, resource-usage start time, and resource-usage end time.

For more information about the response objects and required parameters, see the Swagger page at ${che-host}/swagger/#/resource.

The following are ways to distribute resources to an account:

The CodeReady Workspaces administrator can limit how workspaces are created and the resources that these workspaces consume. Detailed information about each property can be found in the che.env file.

The unit has the following formats:

The Resource-free API manages the free resources that are provided by the system configuration. You can override resources for an account.

Free Resources

GET resource/free: Gets the resources that are available.

GET resource/free/{accountId}: Gets the resources that are available for this account.

Set Free Resources

POST resource/free: Sets the maximum amount of resources available for the user organization account. This number overrides the Сhe configuration. It will be used in all further operations with resources.

Remove Free Resources

DELETE resource/free/{accountId}: Deletes the number of resources available for the user and organization account. The system configuration defines the amount of resources available.

For more information on response objects and required parameters, see the Swagger page at {che-host}/swagger/#/resource-free.

Distributed Organization Resources

GET organization/resource/{organizationId}: Gets the resources that the parent organization provides to the sub-organization.

Sub-Organization Resources Cap

GET organization/resource/{suborganizationId}/cap: Gets the maximum amount of resources that are available for a sub-organization; By default, sub-organizations can use all the resources of the parent organization.

Set Sub-Organization Resources Cap

POST organization/resource/{suborganizationId}/cap: Sets the maximum amount of resources for a sub-organization. This limits the usage of shared resources by the sub-organization.

See the Swagger page at {che-host}/swagger/#/organization-resource for more detailed specification of response objects and required parameters.