Access Control

Cordium does not implement an identity or access control system of its own. Every Cordium endpoint is an Octelium Service, every Cordium User is an Octelium User, and every request is authorized by Octelium Policies (read more about Policies here). On top of that, the Cordium API enforces the ownership of Workspaces and the roles of Space Members (read more here). This page explains how to authorize your Users, your administrators and your Workspaces.

Cordium Services

Cordium is exposed via the following Octelium Services:

Service	Description	Default access
`default.cordium`	The web portal and the Workspace applications.	Denied unless allowed by a Policy.
`default-cordium.octelium-api`	The Cordium gRPC API with its 3 gRPC services: `MainService` (Spaces, Templates, Workspaces, Secrets, Volumes, snapshots, etc.), `WorkspaceService` (terminals, `cordium exec` and log streaming) and `ManagementService` (the `ClusterConfig`).	`MainService` is allowed to all Users via the Service's inline Policy. `WorkspaceService` and `ManagementService` are denied unless allowed by a Policy.
`default-ssh.cordium`	The SSH endpoint used by `cordium ssh`, `cordium cp` and IDEs.	Allowed to all Users. The SSH server additionally checks that the User owns the target Workspace.

Services of other Regions follow the same naming (e.g. eu-west.cordium, eu-west-cordium.octelium-api and eu-west-ssh.cordium).

Authorizing Users

Here is an example of a Policy that grants the members of the engineering and ml Groups the full use of Cordium:

kind: Policy
metadata:
  name: cordium-users
spec:
  rules:
    - effect: ALLOW
      condition:
        any:
          of:
            - match: ctx.service.metadata.name == "default.cordium"
            - match: >-
                ctx.service.metadata.name == "default-cordium.octelium-api" &&
                ctx.request.grpc.serviceFullName == "octelium.api.main.cordium.v1.WorkspaceService"
---
kind: Group
metadata:
  name: engineering
spec:
  authorization:
    policies: ["cordium-users"]

You can apply it via octeliumctl apply (read more here). Workload Users (e.g. your CI or an orchestrator using the SDKs) are authorized in exactly the same way. A workload that only creates and stops Workspaces (e.g. with autoStop) only needs MainService, while a workload that runs commands inside them via Exec also needs WorkspaceService.

note

Remember that ALLOW rules are overridden by matching DENY rules. You can, for example, keep certain Users from using Cordium at all with a DENY rule on ctx.service.metadata.name == "default-cordium.octelium-api" and ctx.service.metadata.name == "default.cordium".

Cluster Administrators

The ManagementService of the Cordium API, which reads and updates the ClusterConfig, is only accessible to Users who are explicitly allowed by a Policy. Here is an example of a Policy that grants it to the platform-admins Group:

kind: Policy
metadata:
  name: cordium-admins
spec:
  rules:
    - effect: ALLOW
      condition:
        match: >-
          ctx.service.metadata.name == "default-cordium.octelium-api" &&
          ctx.request.grpc.serviceFullName == "octelium.api.main.cordium.v1.ManagementService"
---
kind: Group
metadata:
  name: platform-admins
spec:
  authorization:
    policies: ["cordium-users", "cordium-admins"]

note

Since the ManagementService is protected exclusively by Octelium Policies, Users who are granted broad access to the Cluster (e.g. via the allow-all Policy) are effectively Cordium administrators as well. Only grant such access to the Users who actually need it.

Restricting the Cordium API

Since every Cordium API call is an Octelium gRPC request, you can restrict specific operations via ctx.request.grpc.service and ctx.request.grpc.method, in addition to the User's identity and context. Here is an example that keeps contractors from creating Spaces and snapshots, and from running commands in their Workspaces via cordium exec:

kind: Policy
metadata:
  name: cordium-contractors
spec:
  rules:
    - effect: DENY
      condition:
        all:
          of:
            - match: ctx.service.metadata.name == "default-cordium.octelium-api"
            - match: ctx.request.grpc.method in ["CreateSpace", "CreateWorkspaceSnapshot", "Exec"]
---
kind: Group
metadata:
  name: contractors
spec:
  authorization:
    policies: ["cordium-users", "cordium-contractors"]

Every request is also logged by Octelium's access logs, including the gRPC method and the identity of the caller, which gives you a complete audit trail of all Cordium operations (read more here).

Policies for Workspace Sessions

Every Workspace run is an Octelium Session of the Workspace's owner. As a result, the processes running inside a Workspace, including the cordium, octelium and octeliumctl CLIs and any AI agent, act with the permissions of its owner. The Session of a Workspace, however, carries the identity of the Workspace, its Space and its Template in ctx.session.status.ext.cordium (read more here), which lets you grant Workspaces less than their owners.

Here is an example of a global Policy that keeps all Workspaces from managing the Cluster, i.e. from using the Octelium administration API and the Cordium ManagementService, even when their owners are administrators. A compromised dependency or an AI agent running inside an administrator's Workspace therefore cannot escalate to the Cluster's configuration. Note that the Octelium user API (i.e. octelium.api.main.user.v1.MainService) must remain accessible since it is used by octelium connect inside every Workspace:

kind: Policy
metadata:
  name: deny-workspace-administration
spec:
  rules:
    - effect: DENY
      condition:
        all:
          of:
            - match: '"ext" in ctx.session.status && "cordium" in ctx.session.status.ext'
            - any:
                of:
                  - match: >-
                      ctx.service.metadata.name == "default.octelium-api" &&
                      ctx.request.grpc.serviceFullName != "octelium.api.main.user.v1.MainService"
                  - match: >-
                      ctx.service.metadata.name == "default-cordium.octelium-api" &&
                      ctx.request.grpc.serviceFullName == "octelium.api.main.cordium.v1.ManagementService"

You can make it effective for all the requests of the Cluster by adding it to the global Policies of the Octelium ClusterConfig (read more here):

kind: ClusterConfig
spec:
  authorization:
    policies: ["deny-workspace-administration"]

Here is another example that only lets the Workspaces of the agents Template of the payments Space reach the Services of the staging Namespace, in addition to the APIs in the octelium-api Namespace that are needed by octelium connect and the cordium CLI:

kind: Policy
metadata:
  name: agents-staging-only
spec:
  rules:
    - effect: DENY
      condition:
        all:
          of:
            - match: >-
                "ext" in ctx.session.status && "cordium" in ctx.session.status.ext &&
                ctx.session.status.ext.cordium.templateRef.name == "agents.payments.cordium"
            - match: '!(ctx.namespace.metadata.name in ["staging", "octelium-api"])'

note

Combine such restrictions with the deny-workspace-administration Policy above, so that the exception for the octelium-api Namespace does not include the administration APIs.