Che 7: Securing Che

src/main/_data/sidebars/che_7_docs.yml

@@ -73,9 +73,9 @@ entries:
     - title: Tracing Che
       url: tracing-che.html
       output: web
-    #- title: Securing Che
-      #url: securing-che.html
-      #output: web
+    - title: Securing Che
+      url: securing-che.html
+      output: web
     #- title: Troubleshooting for Che administrators
       #url: troubleshooting-for-che-administrators.html
       #output: web

src/main/pages/che-7/administration-guide/assembly_authenticating-in-a-che-workspace.adoc

@@ -0,0 +1,23 @@
+// This assembly is included in the following assemblies:
+//
+// securing-che
+
+:parent-context-of-authenticating-in-a-che-workspace: {context}
+
+[id='authenticating-in-a-che-workspace_{context}']
+= Authenticating in a Che workspace
+
+:context: authenticating-in-a-che-workspace
+
+Workspace containers may contain services that must be protected with authentication. Such protected services are called *secure*. For this purpose, a machine authentication mechanism should be used. Machine tokens avoid the need to pass Keycloak tokens to workspace containers (which can be insecure). Also, Keycloak tokens may have a relatively shorter lifetime and require periodic renewals or refreshes, which is difficult to manage and keep in sync with the same user session tokens on clients.
+
+.Authentication inside a workspace
+image::security/authentication-inside-the-workspace.png[]
+
+include::proc_creating-secure-servers.adoc[leveloffset=+1]
+
+include::con_workspace-jwt-token.adoc[leveloffset=+1]
+
+include::con_machine-token-validation.adoc[leveloffset=+1]
+
+:context: {parent-context-of-authenticating-in-a-che-workspace}

src/main/pages/che-7/administration-guide/assembly_authenticating-to-the-che-server.adoc

@@ -0,0 +1,21 @@
+// This assembly is included in the following assemblies:
+//
+// securing-che
+
+:parent-context-of-authenticating-to-the-che-server: {context}
+
+
+[id='authenticating-to-the-che-server_{context}']
+= Authenticating to the Che server
+
+:context: authenticating-to-the-che-server
+
+include::proc_authenticating-to-the-che-server-using-openid.adoc[leveloffset=+1]
+
+include::proc_authenticating-to-the-che-server-using-other-authentication-implementations.adoc[leveloffset=+1]
+
+include::proc_authenticating-to-the-che-server-using-oauth.adoc[leveloffset=+1]
+
+include::proc_using-swagger-or-rest-clients-to-execute-queries.adoc[leveloffset=+1]
+
+:context: {parent-context-of-authenticating-to-the-che-server}

src/main/pages/che-7/administration-guide/assembly_authenticating-users.adoc

@@ -0,0 +1,23 @@
+// This assembly is included in the following assemblies:
+//
+// securing-che
+
+:parent-context-of-authenticating-users: {context}
+
+
+[id='authenticating-users_{context}']
+= Authenticating users
+
+:context: authenticating-users
+
+This document covers all aspects of user authentication in Eclipse Che, both on the Che server and in workspaces. This includes securing all REST API endpoints, WebSocket or JSON RPC connections, and some web resources.
+
+All authentication types use the link:https://jwt.io/introduction/[JWT open standard] as a container for transferring user identity information. In addition, Che server authentication is based on the link:https://openid.net/connect/[OpenID Connect] protocol implementation, which is provided by default by link:https://www.keycloak.org/[Keycloak].
+
+Authentication in workspaces implies the issuance of self-signed per-workspace JWT tokens and their verification on a dedicated service based on link:https://www.keycloak.org/[JWTProxy].
+
+include::assembly_authenticating-to-the-che-server.adoc[leveloffset=+1]
+
+include::assembly_authenticating-in-a-che-workspace.adoc[leveloffset=+1]
+
+:context: {parent-context-of-authenticating-users}

src/main/pages/che-7/administration-guide/assembly_authorizing-users.adoc

@@ -0,0 +1,40 @@
+// This assembly is included in the following assemblies:
+//
+// securing-che
+
+:parent-context-of-user-authorization: {context}
+
+[id='user-authorization_{context}']
+= User authorization
+
+:context: user-authorization
+
+User authorization in Che is based on the permissions model. Permissions are used to control the allowed actions of users and establish a security model. Every request is verified for the presence of the required permission in the current user subject after it passes authentication. You can control resources managed by Che and allow certain actions by assigning permissions to users.
+
+Permissions can be applied to the following entities:
+
+* Workspace
+* Organization
+* System
+
+All permissions can be managed using the provided REST API. The APIs are documented using Swagger at `[{host}/swagger/#!/permissions]`.
+
+include::con_che-workspace-permissions.adoc[leveloffset=+1]
+
+include::con_che-organization-permissions.adoc[leveloffset=+1]
+
+include::con_che-system-permissions.adoc[leveloffset=+1]
+
+include::ref_managesystem-permission.adoc[leveloffset=+1]
+
+include::ref_monitorsystem-permission.adoc[leveloffset=+1]
+
+include::con_super-privileged-mode.adoc[leveloffset=+1]
+
+include::proc_listing-che-permissions.adoc[leveloffset=+1]
+
+include::proc_assigning-che-permissions.adoc[leveloffset=+1]
+
+include::proc_sharing-che-permissions.adoc[leveloffset=+1]
+
+:context: {parent-context-of-user-authorization}

src/main/pages/che-7/administration-guide/assembly_securing-che.adoc

@@ -1,11 +1,11 @@
 ---
 title: Securing Che
-keywords: 
+keywords:
 tags: []
 sidebar: che_7_docs
 permalink: che-7/securing-che.html
 folder: che-7/administration-guide
-summary: 
+summary:
 ---
 
 :parent-context-of-securing-che: {context}
@@ -15,31 +15,9 @@ summary:
 
 :context: securing-che
 
+include::assembly_authenticating-users.adoc[leveloffset=+1]
 
-This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on. Can include more than one paragraph. Consider using the information from the user story.
+include::assembly_authorizing-users.adoc[leveloffset=+1]
 
-[id='prerequisites-{context}']
-== Prerequisites
-
-* A bulleted list of conditions that must be satisfied before the user starts following this assembly.
-* You can also link to other modules or assemblies the user must follow before starting this assembly.
-* Delete the section title and bullets if the assembly has no prerequisites.
-
-
-
-include::con_che-security-overview.adoc[leveloffset=+1]
-
-include::con_user-authentication-and-authorization.adoc[leveloffset=+1]
-
-include::con_permission-model-overview.adoc[leveloffset=+1]
-
-
-
-[id='related-information-{context}']
-== Related information
-
-* A bulleted list of links to other material closely related to the contents of the concept module.
-* For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
-* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 
 :context: {parent-context-of-securing-che}

src/main/pages/che-7/administration-guide/con_che-organization-permissions.adoc

@@ -0,0 +1,29 @@
+// Module included in the following assemblies:
+//
+// authorizing-users
+
+[id="che-organization-permissions_{context}"]
+= Che organization permissions
+
+An Che organization is a named set of users. The following permissions are applicable to organizations:
+
+.Che organization permissions
+[options="header",cols="2"]
+|===
+| 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.
+|===

src/main/pages/che-7/administration-guide/con_che-system-permissions.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// authorizing-users
+
+[id="che-system-permissions_{context}"]
+= Che system permissions
+
+Che system permissions control aspects of the whole Che installation. The following permissions are applicable to the system:
+
+.Che system permission
+[options="header",cols="2"]
+|===
+| 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 accessing endpoints used for monitoring the state of the server.
+|===
+
+All system permissions are granted to the administrative user who is configured in the `CHE_SYSTEM_ADMIN__NAME` property (the default is `admin`). The system permissions are granted when the Che server starts. If the user is not present in the Che user database, it happens after the first user’s login.

src/main/pages/che-7/administration-guide/con_che-workspace-permissions.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// authorizing-users
+
+
+[id="che-workspace-permissions_{context}"]
+= Che workspace permissions
+
+The user who creates a workspace is the workspace owner. By default, the workspace owner has the following permissions: `read`, `use`, `run`, `configure`, `setPermissions`, and `delete`. Workspace owners can invite users into the workspace and control workspace permissions for other users.
+
+The following permissions are associated with workspaces:
+
+.Che workspace permissions
+[options="header",cols="2"]
+|===
+| 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.
+|===

src/main/pages/che-7/administration-guide/con_machine-token-validation.adoc

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// authenticating-in-a-che-workspace
+
+[id="machine-token-validation_{context}"]
+= Machine token validation
+
+The validation of machine tokens is performed using a dedicated per-workspace service with `JWTProxy` running on it in a separate pod. When the workspace starts, this service receives the public part of the SHA key from the Che server. A separate verification endpoint is created for each secure server. When traffic comes to that endpoint, `JWTProxy` tries to extract the token from the cookies or headers and validates it using the public-key part.
+
+To query the Che server, a workspace server can use the machine token provided in the `CHE_MACHINE_TOKEN` environment variable. This token is the user's who starts the workspace. The scope of such requests is restricted to the current workspace only. The list of allowed operations is also strictly limited.

src/main/pages/che-7/administration-guide/con_super-privileged-mode.adoc

@@ -0,0 +1,22 @@
+// Module included in the following assemblies:
+//
+// user-authorization
+
+[id="super-privileged-mode_{context}"]
+= 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. A user can read and stop any workspace with the *manageSystem* permission and assign permissions to other users as needed.
+
+The *super-privileged* mode is disabled by default. To change to the *super-privileged* mode, set the `CHE_SYSTEM_SUPER__PRIVILEGED__MODE` variable to `true` in the `che.env` file. The following is a list of services that are enabled for users with the *manageSystems* permissions and with *super-privileged* mode on.
+
+[options="header"]
+|====
+|Path|HTTP Method|Description
+|/workspace/namespace/{namespace:.*}|GET|Get all workspaces for the given namespace.
+|/workspace/{id}|DELETE|Stop a workspace.
+|/workspace/{key:.*}|GET|Get a workspace by key.
+|/organization/resource/{suborganizationId}/cap|GET|Get a resource cap for the given organization.
+|/organization/resource/{suborganizationId}/cap|POST|Set the resource cap for a given organization.
+|/organization/{parent}/organizations|GET|Get the child organizations.
+|/organization|GET|Get the user's organizations.
+|====

src/main/pages/che-7/administration-guide/con_workspace-jwt-token.adoc

@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+//
+// authenticating-in-a-che-workspace
+
+[id="workspace-jwt-token_{context}"]
+= Workspace JWT token
+
+Workspace tokens are JSON web tokens (link:https://jwt.io/[JWT]) that contain the following information in their claims:
+
+* `uid`: The ID of the user who owns this token
+* `uname`: The name of the user who owns this token
+* `wsid`: The ID of a workspace which can be queried with this token
+
+Every user is provided with a unique personal token for each workspace. The structure of a token and the signature are different than they are in Keycloak. The following is an example token view:
+
+[source,json]
+----
+# 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": "RSASHA256(base64UrlEncode(header) + . +  base64UrlEncode(payload))"
+}
+----
+
+The SHA-256 cipher with the RSA algorithm is used for signing machine tokens. It is not configurable. Also, there is no public service that distributes the public part of the key pair with which the token is signed.