Communication Flows

This document describes the flow between SSH CLI, SSH Proxy, Identity, Provisioner, and k8shelld.Please refer to the architecture overview for component details.

The flow is divided into three phases:

1. User Discovery and Onboarding
2. Workspace Provisioning
3. User Interaction

User Discovery and Onboarding

Users connect to SSH Proxy using a user string that contains their username and configuration parameters like blueprint name or repository details (see User string specification for details). SSH Proxy parses this user string to extract the username and parameters, then looks up the corresponding internal user identity.

When no user identity is found, SSH Proxy checks whether the user can be onboarded through available identity providers. If onboarding is supported, it automatically initiates the onboarding process.

The following diagram shows the communication flow for user discovery and onboarding.

sequenceDiagram
    autonumber
    participant C as SSH CLI
    participant P as SSH Proxy
    participant I as Identity Service
    participant G as Identity Provider<br/>(GitHub)

    C->>P: Open SSH connection (handshake)
    note right of P: Parse login (user~bp@addr)

    %% Find user 
    P->>I: Find user
    alt User found
        I-->>P: User
    else User not found
        P->>I: Start onboarding (e.g. GitHub Device Flow)
        I-->G: Request OAuth device code
        G-->>I: Return device code, user code, verification URL
        I-->>P: Return onboarding info (user code, URL)
        P-->>C: SSH keyboard-interactive<br/>(show user code, URL) 
        alt Onboarding successful
            G-->>I: Token (polling)
            I-->>P: User created
        else Onboarding failed
            I-->>P: No user
            P-->>C: Access denied
        end
    end

    %% Key verification with GitHub
    P->>I: Auth public key
    I->>G: Verify with GitHub
    G-->>I: Verification result
    I-->>P: Auth result

    P-->>C: Access granted / denied

Loading

SSH Proxy calls the following Identity Service APIs.

Method	Endpoint	Description
GET	/users/{username}	Finds the internal user identity for the given username
GET	/users/{username}/onboardcap	Retrieves the onboarding capabilities for the user
POST	/users/{username}/onboard	Starts the onboarding process for the user
GET	/users/{username}/authpublickey	Checks if the provided SSH public key is authorized for the user

Workspace Provisioning

Users can request workspace access through the user string in two ways: by specifying a blueprint name, or by specifying a Git repository name (for users onboarded via identity providers like GitHub). The Provisioner service manages workspace blueprints and retrieves blueprint definitions from Git repositories. SSH Proxy uses the user string to check if the requested workspace is running and requests to provision it when necessary.

The following diagram shows the communication flow for workspace provisioning. For more details on how the Provisioner service retrieves blueprint information and provisions workspaces, see the Provisioner service documentation.

sequenceDiagram
    autonumber
    participant C as SSH CLI
    participant P as SSH Proxy
    participant R as Provisioner
    participant K8s as Kubernetes API

    P->>R: Get workspace for user and blueprint
    R->>K8s: Find workspace
    K8s-->>R: Workspace details
    alt Workspace exists
        R-->>P: Workspace status
    else Workspace missing
        P->>R: Provision workspace (user string)
        R->>K8s: Create workspace resources
    end

    note over P,K8s: Workspace provisioning events (stream)
    alt Failure
        R-->>P: Failed {reason}
        P-->>C: Report failure & close
    else Running
        K8s-->>R: Pod Ready, IP, TLS cert
        R-->>P: Running {ip, tlsCert}
    end

Loading

SSH Proxy calls the following Provisioner Service APIs.

Method	Endpoint	Description
GET	/workspaces?username={user}&blueprint={bp}	Finds a workspace
GET	/workspaces/{workspace}/status	Retrieves the workspace status
POST	/workspaces?userStr={userStr}	Provisions the workspace for the given user string

User interaction

TODO