Skip to content

redfish redirection architecture

Jump to bottom
Pola, Sudhir edited this page May 25, 2026 · 1 revision

Redfish Redirection Architecture

Architectural Design for Intel AMT Redirection over Redfish - KVM and SOL Control and WebSocket Streaming

Covers ComputerSystem Redfish modeling for both KVM (GraphicalConsole) and SOL (SerialConsole), including control-plane state management and the WebSocket streaming pathway for live sessions.

Reference: DMT Architecture Overview

Executive Summary

The DMT Console currently provides KVM and SOL through proprietary DMT RESTful APIs, limiting integration to purpose-built clients and blocking use with standard Redfish management tooling. This architecture adds Redfish-standard redirection support to remove that barrier so any Redfish-capable management platform or tool can discover capabilities and establish live KVM or SOL sessions against a managed Intel AMT device without proprietary API dependencies.

Solution Overview

Redfish standards define redirection support at the discovery and state level (GraphicalConsole for KVM and SerialConsole for SOL), but do not prescribe how the live stream is established or secured. Given this, the solution is structured as two loosely coupled, independent planes: this makes the integration expectations explicit for third-party management software integrating the DMT Console Redfish implementation, and enables them to embed a streaming client directly into their manageability software. The Data Plane intentionally reuses the existing DMT Redirect infrastructure (RedirectRoutes / Redirector) - no new streaming path is introduced; only the Redfish Control Plane and token-based authentication are added on top.

Control Plane - Redfish ComputerSystem API over HTTPS:

  • Single endpoint GET /redfish/v1/Systems/{SystemId} for KVM and SOL capability discovery: GraphicalConsole reports KVM readiness and SerialConsole reports SOL readiness.
  • Intel AMT-specific KVM state (ControlMode, KVMStatus, UserConsentStatus) is exposed under GraphicalConsole.Oem.Intel.AMT.
  • Standard SOL service/capability fields are read from SerialConsole (for example WebSocket.ServiceEnabled, MaxConcurrentSessions, and WebSocket.ConsoleURI).
  • Intel AMT-specific SOL state (ControlMode, SOLStatus, UserConsentStatus) is exposed under SerialConsole.Oem.Intel.AMT.
  • For CCM devices, each protocol uses three OEM actions for consent: KVM (RequestKVMConsent, SubmitKVMConsentCode, CancelKVMConsent) and SOL (RequestSOLConsent, SubmitSOLConsentCode, CancelSOLConsent). These actions drive the IPS_OptInService consent flow without exposing WS-Man details to the caller.
  • KVM enable/disable is handled via PATCH /redfish/v1/Systems/{SystemId} updates to GraphicalConsole.ServiceEnabled.
  • SOL enable/disable is handled via PATCH /redfish/v1/Systems/{SystemId} updates to SerialConsole.WebSocket.ServiceEnabled.
  • GenerateRedirectionToken OEM action issues short-lived tokens for WebSocket authentication; for CCM devices, the token is obtained after consent is granted.

Data Plane - Live KVM and SOL streams over WebSocket, served by the existing DMT Redirect infrastructure:

  • WebSocket route /relay/webrelay.ashx; clients derive the full URL from the Console base URL (ws:// or wss:// depending on TLS configuration).
  • Authenticated via a short-lived redirection token (RedirectionToken) passed in Sec-WebSocket-Protocol; the token must be refreshed periodically during an active session.
  • KVM mode relays keyboard/mouse input and encoded video frames (VNC-RFB / RLE).
  • SOL mode relays bidirectional serial terminal input/output frames.

DMT Console - Protocol bridge between the two planes:

  • Translates Redfish control requests into AMT WS-Man calls (IPS_KVMRedirectionSettingData, AMT_RedirectionService, CIM_KVMRedirectionSAP).
  • Relays KVM and SOL frames over CIRA (for devices behind NAT/firewalls that establish an outbound tunnel) or Direct LAN (for locally reachable devices; TLS configurable per device via UseTLS).

KVM Overall Solution Flow

sequenceDiagram
    autonumber
    participant KVMClient as Streaming Client
    participant Client as Redfish Client (for control)
    participant ConsoleService as DMT Console
    participant AMTEN as AMT Device

    Note over Client,ConsoleService: Step 1 - Session Authentication

    Client->>ConsoleService: POST /redfish/v1/SessionService/Sessions/
    ConsoleService-->>Client: 201 Created — X-Auth-Token + session URI

    Note over Client,AMTEN: Step 2 - Capability Discovery & OEM KVM State

    Client->>ConsoleService: GET /redfish/v1/Systems/{SystemId}
    rect rgb(240, 248, 255)
        Note over ConsoleService,AMTEN: WS-Man queries to AMT device:<br/>GET IPS_KVMRedirectionSettingData → Is5900PortEnabled, OptInPolicy, SessionTimeout<br/>GET AMT_RedirectionService → EnabledState, ListenerEnabled<br/>GET CIM_KVMRedirectionSAP → VNC-RFB protocol, SAP state
    end
    ConsoleService-->>Client: 200 OK — GraphicalConsole {ServiceEnabled, ConnectTypesSupported}<br/>+ Oem.Intel.AMT {ControlMode, KVMStatus, UserConsentStatus} + Action targets

    alt KVMStatus=Disabled (from Step 2)
        Note over Client,ConsoleService: Step 3 - Enable KVM (required if disabled)

        Client->>ConsoleService: PATCH /redfish/v1/Systems/{SystemId} {"GraphicalConsole":{"ServiceEnabled":true}}
        rect rgb(240, 248, 255)
            Note over ConsoleService,AMTEN: WS-Man KVM enable path:<br/>Set KVM listener state (enableKVM=true)<br/>AMT_RedirectionService listener enabled
        end
        ConsoleService-->>Client: 200 OK — GraphicalConsole.ServiceEnabled: true, KVMStatus: Enabled
    else KVMStatus=Enabled
        Note over Client: Step 3 skipped — KVM already enabled
    end

    Note over Client,AMTEN: Step 4 - Control Mode Decision

    alt ACM — Admin Control Mode (ControlMode=ACM, UserConsentStatus=NotRequired)
        Note over Client: No consent required — proceed directly to Step 5
    else CCM — Client Control Mode (ControlMode=CCM, consent required)
        Note over Client,AMTEN: Step 4.1 - Trigger consent prompt on device screen
        Client->>ConsoleService: POST /redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.RequestKVMConsent
        rect rgb(240, 248, 255)
            Note over ConsoleService,AMTEN: WS-Man: IPS_OptInService::StartOptIn → ReturnValue=0 (SUCCESS)
        end
        rect rgb(245, 245, 245)
            Note over AMTEN: AMT Device Screen<br/>Displays 6-digit consent code
        end
        ConsoleService-->>Client: 200 OK — UserConsentStatus: Requested

        Note over Client,AMTEN: Step 4.2 - Poll until local user responds

        loop GET /redfish/v1/Systems/{SystemId} while UserConsentStatus=Requested
            Client->>ConsoleService: GET /redfish/v1/Systems/{SystemId}
            ConsoleService-->>Client: 200 OK — KVMStatus: PendingConsent, UserConsentStatus: Requested
        end

        Note over Client,AMTEN: Step 4.3 - Submit 6-digit code obtained from local user

        Client->>ConsoleService: POST /redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.SubmitKVMConsentCode {"ConsentCode": 482916}
        rect rgb(240, 248, 255)
            Note over ConsoleService,AMTEN: WS-Man: IPS_OptInService::SendOptInCode(482916) → ReturnValue=0 (SUCCESS)
        end
        ConsoleService-->>Client: 200 OK — UserConsentStatus: Granted
    end

    Note over KVMClient,ConsoleService: Step 5 - Generate redirection token

    KVMClient->>ConsoleService: POST /redfish/v1/Systems/{SystemId}/Actions/Oem/IntelComputerSystem.GenerateRedirectionToken
    ConsoleService-->>KVMClient: 200 OK — RedirectionToken {token, expirationTime}

    Note over KVMClient,ConsoleService: Step 6 - WebSocket Stream Establishment

    KVMClient->>ConsoleService: WebSocket Upgrade: GET /relay/webrelay.ashx?host={SystemId}&mode={Mode} + Sec-WebSocket-Protocol: {RedirectionToken}
    rect rgb(240, 248, 255)
        Note over ConsoleService,AMTEN: WS-Man commands to enable KVM session:<br/>AMT_RedirectionService::RequestStateChange(32771) → redirection service enabled<br/>CIM_KVMRedirectionSAP::RequestStateChange(2) → KVM SAP enabled, VNC-RFB channel ready
    end
    ConsoleService-->>KVMClient: 101 Switching Protocols — WebSocket tunnel open

    Note over KVMClient,AMTEN: Step 7 — Live KVM Session (binary relay over /relay/webrelay.ashx)

    loop Until user closes session
        KVMClient->>ConsoleService: WebSocket binary: keyboard / mouse input frame
        ConsoleService->>AMTEN: Relay binary frame — AMT Redirection Protocol TCP (port 16994/16995)
        AMTEN->>ConsoleService: Push encoded video frame (RLE 8 / RLE 16)
        ConsoleService-->>KVMClient: WebSocket binary: video frame — client decodes and renders
    end

    loop Periodic token refresh (before RedirectionToken expires)
        KVMClient->>ConsoleService: POST /redfish/v1/Systems/{SystemId}/Actions/Oem/IntelComputerSystem.GenerateRedirectionToken
        ConsoleService-->>KVMClient: 200 OK — RedirectionToken {newToken, expirationTime}
    end

    Note over KVMClient,AMTEN: Step 8 — Session Termination

    KVMClient->>ConsoleService: Close KVM window — WebSocket close frame (code 1000)
    rect rgb(240, 248, 255)
        Note over ConsoleService,AMTEN: WS-Man: IPS_KVMRedirectionSettingData::TerminateSession() → session terminated
    end
    ConsoleService-->>KVMClient: WebSocket close acknowledged

    alt Optional: Client wants to disable KVM after session ends
        Note over Client,ConsoleService: Step 9 - Disable KVM (optional — cleanup)

        Client->>ConsoleService: PATCH /redfish/v1/Systems/{SystemId} {"GraphicalConsole":{"ServiceEnabled":false}}
        rect rgb(240, 248, 255)
            Note over ConsoleService,AMTEN: WS-Man KVM disable path:<br/>Set KVM listener state (enableKVM=false)<br/>AMT_RedirectionService listener disabled when no redirection services remain enabled
        end
        ConsoleService-->>Client: 200 OK — GraphicalConsole.ServiceEnabled: false, KVMStatus: Disabled
    else KVM remains available for future sessions
        Note over Client: Step 9 skipped — KVM stays enabled for reuse
    end
    KVMClient->>KVMClient: Clear token from memory
Loading

SOL Overall Solution Flow

sequenceDiagram
    autonumber
    participant SOLClient as Streaming Client
    participant Client as Redfish Client (control)
    participant ConsoleService as DMT Console
    participant AMTEN as AMT Device

    Note over Client,ConsoleService: Step 1 - Session Authentication

    Client->>ConsoleService: POST /redfish/v1/SessionService/Sessions/
    ConsoleService-->>Client: 201 Created - X-Auth-Token + session URI

    Note over Client,AMTEN: Step 2 - SerialConsole Capability Discovery

    Client->>ConsoleService: GET /redfish/v1/Systems/{SystemId}
    rect rgb(240, 248, 255)
        Note over ConsoleService,AMTEN: WS-Man read path:<br/>GET AMT_RedirectionService -> EnabledState, ListenerEnabled<br/>plus platform policy and limits mapping
    end
    ConsoleService-->>Client: 200 OK - SerialConsole (WebSocket) + Oem.Intel.AMT (ControlMode, SOLStatus, UserConsentStatus) + Actions.Oem targets

    alt SerialConsole.WebSocket.ServiceEnabled=false (from Step 2)
        Note over Client,ConsoleService: Step 3 - Enable SOL (required when disabled)

        Client->>ConsoleService: PATCH /redfish/v1/Systems/{SystemId} {"SerialConsole":{"WebSocket":{"ServiceEnabled":true}}}
        rect rgb(240, 248, 255)
            Note over ConsoleService,AMTEN: WS-Man write path:<br/>RequestAMTRedirectionServiceStateChange(ider=false, sol=true)<br/>SetAMTRedirectionService(listenerEnabled=true)
        end
        ConsoleService-->>Client: 200 OK - SerialConsole.WebSocket.ServiceEnabled: true
    else SerialConsole.WebSocket.ServiceEnabled=true
        Note over Client: Step 3 skipped - SOL already enabled
    end

    Note over Client,AMTEN: Step 4 - Control Mode Decision

    alt ACM - Admin Control Mode (ControlMode=ACM, UserConsentStatus=NotRequired)
        Note over Client: No consent required - proceed directly to Step 5
    else CCM - Client Control Mode (ControlMode=CCM, consent required)
        Note over Client,AMTEN: Step 4.1 - Trigger SOL consent prompt on device screen
        Client->>ConsoleService: POST /redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.RequestSOLConsent
        rect rgb(240, 248, 255)
            Note over ConsoleService,AMTEN: WS-Man: IPS_OptInService::StartOptIn -> ReturnValue=0 (SUCCESS)
        end
        rect rgb(245, 245, 245)
            Note over AMTEN: AMT Device Screen<br/>Displays 6-digit consent code
        end
        ConsoleService-->>Client: 200 OK - UserConsentStatus: Requested

        Note over Client,AMTEN: Step 4.2 - Poll until local user responds

        loop GET /redfish/v1/Systems/{SystemId} while UserConsentStatus=Requested
            Client->>ConsoleService: GET /redfish/v1/Systems/{SystemId}
            ConsoleService-->>Client: 200 OK - SOLStatus: PendingConsent, UserConsentStatus: Requested
        end

        Note over Client,AMTEN: Step 4.3 - Submit 6-digit code obtained from local user

        Client->>ConsoleService: POST /redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.SubmitSOLConsentCode {"ConsentCode": 482916}
        rect rgb(240, 248, 255)
            Note over ConsoleService,AMTEN: WS-Man: IPS_OptInService::SendOptInCode(482916) -> ReturnValue=0 (SUCCESS)
        end
        ConsoleService-->>Client: 200 OK - UserConsentStatus: Granted
    end

    Note over SOLClient,ConsoleService: Step 5 - Obtain redirection token

    SOLClient->>ConsoleService: POST /redfish/v1/Systems/{SystemId}/Actions/Oem/IntelComputerSystem.GenerateRedirectionToken
    ConsoleService-->>SOLClient: 200 OK - RedirectionToken {token, expirationTime}

    Note over SOLClient,ConsoleService: Step 6 - WebSocket Stream Establishment

    SOLClient->>ConsoleService: WebSocket Upgrade: GET /relay/webrelay.ashx?host={SystemId}&mode=sol + Sec-WebSocket-Protocol: {RedirectionToken}
    rect rgb(240, 248, 255)
        Note over ConsoleService,AMTEN: WS-Man commands to open SOL session:<br/>AMT_RedirectionService::RequestStateChange(enableSOL=true) -> SOL redirection channel open
    end
    ConsoleService-->>SOLClient: 101 Switching Protocols - WebSocket tunnel open

    Note over SOLClient,AMTEN: Step 7 - Live SOL Session (text relay over /relay/webrelay.ashx)

    loop Until user closes terminal
        SOLClient->>ConsoleService: WebSocket binary: keyboard input
        ConsoleService->>AMTEN: Relay serial input frame - AMT Redirection Protocol TCP (port 16994/16995)
        AMTEN->>ConsoleService: Serial console output frame
        ConsoleService-->>SOLClient: WebSocket binary: terminal output
    end

    loop Periodic token refresh (before RedirectionToken expires)
        SOLClient->>ConsoleService: POST /redfish/v1/Systems/{SystemId}/Actions/Oem/IntelComputerSystem.GenerateRedirectionToken
        ConsoleService-->>SOLClient: 200 OK - RedirectionToken {newToken, expirationTime}
    end

    Note over SOLClient,AMTEN: Step 8 - Session Termination

    SOLClient->>ConsoleService: Close terminal - WebSocket close frame (code 1000)
    rect rgb(240, 248, 255)
        Note over ConsoleService,AMTEN: AMT_RedirectionService session terminated
    end
    ConsoleService-->>SOLClient: WebSocket close acknowledged

    alt Optional: Client wants to disable SOL after session ends
        Note over Client,ConsoleService: Step 9 - Disable SOL (optional - cleanup)

        Client->>ConsoleService: PATCH /redfish/v1/Systems/{SystemId} {"SerialConsole":{"WebSocket":{"ServiceEnabled":false}}}
        rect rgb(240, 248, 255)
            Note over ConsoleService,AMTEN: WS-Man write path:<br/>RequestAMTRedirectionServiceStateChange(ider=false, sol=false)<br/>SetAMTRedirectionService(listenerEnabled depends on other active redirection modes)
        end
        ConsoleService-->>Client: 200 OK - SerialConsole.WebSocket.ServiceEnabled: false
    else SOL remains available for future sessions
        Note over Client: Step 9 skipped - SOL stays enabled for reuse
    end
    SOLClient->>SOLClient: Clear token from memory
Loading

High-Level Design

The architecture follows a layered approach with clear separation between Redfish control callers, redirection streaming clients for both KVM and SOL, and AMT device communication:

graph TD
    subgraph L1[Client]
        CTRLCLIENT[Redfish Control Client<br/><i>curl / Redfish tools</i>]
        KVMCLIENT[KVM Streaming Client]
        SOLCLIENT[SOL Streaming Client]
    end

    subgraph L3[Console]
        CONSOLE[Redfish Redirection Component<br/><i>redfish</i>]
        REDIRGATEWAY[Redirection Stream Gateway<br/><i>RedirectRoutes</i>]
        STREAMBACKEND[Redirection Stream Backend<br/><i>Redirector</i>]
    end

    subgraph L4[AMT Edge Node]
        AMTEN[AMT EN]
    end

    CTRLCLIENT <-->|Redfish control calls and responses| CONSOLE
    KVMCLIENT <-->|KVM frames and input events| REDIRGATEWAY
    SOLCLIENT <-->|Serial terminal input/output| REDIRGATEWAY
    REDIRGATEWAY <-->|Session auth and routing| CONSOLE
    REDIRGATEWAY <-->|Stream context and data| STREAMBACKEND
    CONSOLE <-->|CIRA WS-Management| AMTEN
    STREAMBACKEND <-->|KVM and SOL forwarding| AMTEN

    classDef client fill:#fff3e0
    classDef proxy fill:#c8e6c9
    classDef core fill:#e3f2fd
    classDef edge fill:#ffecb3

    class CTRLCLIENT client
    class KVMCLIENT client
    class SOLCLIENT client
    class REDIRGATEWAY proxy
    class STREAMBACKEND proxy
    class CONSOLE core
    class AMTEN edge
Loading

Component Descriptions

Client Layer: Client Layer defines who initiates Redfish control operations and who consumes real-time KVM or SOL streaming.

Control Path:

  • Redfish Control Client: curl commands or Redfish tools used for control-plane operations (for example capability/status checks and control actions)

Data Path(2 options):

  1. Separate clients for KVM and SOL: Use a dedicated KVM streaming client for video/input and a separate SOL streaming client for serial terminal traffic. Both clients connect through the same redirection gateway and authenticate with a redirection token in Sec-WebSocket-Protocol.
  2. DMT UI Toolkit React App Client: Use the existing browser-based UI toolkit app adapted to drive both KVM and SOL flows through the Redfish APIs.

DMT Console Components:

  • Redfish Redirection Component (redfish): Control-plane HTTP handlers for ComputerSystem.GraphicalConsole, ComputerSystem.SerialConsole, and OEM actions. Translates Redfish requests to AMT WS-Man calls and back.
  • Redirection Stream Gateway (RedirectRoutes): WebSocket entry point at /relay/webrelay.ashx. The client constructs the full ws:// or wss:// URL from the Console base URL. The handler validates the token supplied in Sec-WebSocket-Protocol and uses query parameters host and mode to route either KVM or SOL sessions.
  • Redirection Stream Backend (Redirector): Manages the AMT-side WS-Man redirection connection (RedirectConnect, RedirectSend, RedirectListen, RedirectClose) and relays KVM or SOL traffic over CIRA or Direct LAN.

Device Layer:

  • Intel AMT Device: Target devices with AMT firmware supporting KVM and SOL redirection via CIRA and WS-Management protocols

KVM Streaming API Flow (Client-Facing)

  1. Session Authentication (Control Plane)

    • POST /redfish/v1/SessionService/Sessions/
    • Client obtains X-Auth-Token and a session URI before accessing any protected Redfish or KVM stream endpoint.

  2. Capability Discovery & OEM KVM State (Control Plane)

    • GET /redfish/v1/Systems/{SystemId}
    • Client checks GraphicalConsole.ServiceEnabled, Port, MaxConcurrentSessions, and ConnectTypesSupported.
    • OEM KVM state is read from GraphicalConsole.Oem.Intel.AMT: ControlMode (ACM/CCM), KVMStatus, and UserConsentStatus.
    • OEM action targets for KVM consent are advertised under Actions.Oem.

  3. KVM Service Control (Control Plane — conditional based on KVMStatus)

    • Required when KVMStatus=Disabled: PATCH /redfish/v1/Systems/{SystemId} with GraphicalConsole.ServiceEnabled=true enables the KVM listener.
    • Optional when KVMStatus=Enabled: KVM is already available; proceed to Step 4.
    • PATCH /redfish/v1/Systems/{SystemId} with GraphicalConsole.ServiceEnabled=false can be called after session termination to stop accepting new KVM connections (cleanup step).

  4. CCM User Consent Flow (Control Plane — CCM devices only)

    • Required when ControlMode=CCM and UserConsentStatus is not Granted.
    • POST .../Actions/Oem/ComputerSystem.RequestKVMConsent — triggers IPS_OptInService::StartOptIn; device displays a 6-digit code on screen. Response: UserConsentStatus=Requested.
    • Poll GET /redfish/v1/Systems/{SystemId} until UserConsentStatus transitions out of Requested.
    • POST .../Actions/Oem/ComputerSystem.SubmitKVMConsentCode with {"ConsentCode": <6-digit>} — submits the code via SendOptInCode. Response: UserConsentStatus=Granted.
    • POST .../Actions/Oem/ComputerSystem.CancelKVMConsent — aborts the consent request at any point via CancelOptIn.

  5. Generate redirection token (Control Plane)

    • POST /redfish/v1/Systems/{SystemId}/Actions/Oem/IntelComputerSystem.GenerateRedirectionToken
    • Called by the streaming client using the X-Auth-Token from Step 1.
    • Returns a short-lived RedirectionToken and its ExpirationTime; used for WebSocket authentication instead of the session token.
    • For CCM devices, call this only after UserConsentStatus=Granted (Step 4 — Control Mode Decision).
    • Token must be refreshed periodically during streaming before it expires.

  6. Direct WebSocket Stream Establishment (Data Plane)

    • WebSocket upgrade to the registered route /relay/webrelay.ashx
    • Construct the full client URL from the Console base URL:
      • ws://{ConsoleHost}/relay/webrelay.ashx when Console TLS is disabled
      • wss://{ConsoleHost}/relay/webrelay.ashx when Console TLS is enabled
    • Include query parameters: ?host={SystemId}&mode={Mode}
    • The RedirectionToken from Step 5 is presented in Sec-WebSocket-Protocol: <RedirectionToken> for authentication.

  7. Session Termination

    • Client closes WebSocket with a close frame (code 1000), or the server terminates the stream on timeout, policy change, or error.

SOL Streaming API Flow (Client-Facing)

  1. Session Authentication (Control Plane)

    • POST /redfish/v1/SessionService/Sessions/
    • Client obtains X-Auth-Token and a session URI before accessing any protected Redfish or SOL stream endpoint.

  2. SerialConsole Capability Discovery (Control Plane)

    • GET /redfish/v1/Systems/{SystemId}
    • Client checks SerialConsole.WebSocket.ServiceEnabled and MaxConcurrentSessions.
    • OEM SOL state is read from SerialConsole.Oem.Intel.AMT: ControlMode (ACM/CCM), SOLStatus, and UserConsentStatus.
    • OEM action targets for SOL consent and token generation are advertised under Actions.Oem.

  3. SOL Service Control (Control Plane - conditional based on SOLStatus)

    • Required when SerialConsole.WebSocket.ServiceEnabled=false: PATCH /redfish/v1/Systems/{SystemId} with SerialConsole.WebSocket.ServiceEnabled=true enables the SOL listener.
    • Optional when SerialConsole.WebSocket.ServiceEnabled=true: SOL is available; proceed to Step 4.
    • PATCH /redfish/v1/Systems/{SystemId} with SerialConsole.WebSocket.ServiceEnabled=false can be called after session termination to stop accepting new SOL connections (cleanup step).

  4. CCM User Consent Flow (Control Plane — CCM devices only)

    • Required when ControlMode=CCM and UserConsentStatus is not Granted.
    • POST .../Actions/Oem/ComputerSystem.RequestSOLConsent - triggers IPS_OptInService::StartOptIn; device displays a 6-digit code on screen. Response: UserConsentStatus=Requested.
    • Poll GET /redfish/v1/Systems/{SystemId} until UserConsentStatus transitions out of Requested.
    • POST .../Actions/Oem/ComputerSystem.SubmitSOLConsentCode with {"ConsentCode": <6-digit>} - submits the code via SendOptInCode. Response: UserConsentStatus=Granted.
    • POST .../Actions/Oem/ComputerSystem.CancelSOLConsent - aborts the consent request at any point via CancelOptIn.

  5. Generate redirection token (Control Plane)

    • POST /redfish/v1/Systems/{SystemId}/Actions/Oem/IntelComputerSystem.GenerateRedirectionToken
    • Called by the streaming client using the X-Auth-Token from Step 1.
    • Returns a short-lived RedirectionToken and its ExpirationTime; used for WebSocket authentication instead of the session token.
    • For CCM devices, call this only after UserConsentStatus=Granted (Step 4 - Control Mode Decision).
    • During active SOL streaming, fetch a fresh token before expiration to keep the session authenticated.
    • Note: The Redfish ComputerSystem model does not define a standard SerialConsole.Connect action; token issuance is provided through an Intel OEM action.

  6. Direct WebSocket Stream Establishment (Data Plane)

    • WebSocket upgrade to the registered route /relay/webrelay.ashx
    • Construct the full client URL from the Console base URL:
      • ws://{ConsoleHost}/relay/webrelay.ashx when Console TLS is disabled
      • wss://{ConsoleHost}/relay/webrelay.ashx when Console TLS is enabled
    • Include query parameters: ?host={SystemId}&mode=sol
    • The RedirectionToken from Step 5 is presented in Sec-WebSocket-Protocol: <RedirectionToken> for authentication.

  7. Session Termination

    • Client closes WebSocket with a close frame (code 1000), or the server terminates the stream on timeout, policy change, or error.
    • Optionally disable SOL via PATCH /redfish/v1/Systems/{SystemId} setting SerialConsole.WebSocket.ServiceEnabled=false.

API Examples

Common API Examples

Generate redirection token - POST #Oem.Intel.AMT.GenerateRedirectionToken

Called by the streaming client before establishing the WebSocket connection.

POST /redfish/v1/Systems/{SystemId}/Actions/Oem/IntelComputerSystem.GenerateRedirectionToken
X-Auth-Token: {token}
Content-Type: application/json

{}

Response (200 OK):

{
    "RedirectionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "ExpirationTime": "2026-04-10T12:30:45Z"
}

Use RedirectionToken in Sec-WebSocket-Protocol for WebSocket upgrade.

Token refresh during live session

POST /redfish/v1/Systems/{SystemId}/Actions/Oem/IntelComputerSystem.GenerateRedirectionToken
X-Auth-Token: {token}
Content-Type: application/json

{}
{
    "RedirectionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...new...",
    "ExpirationTime": "2026-04-10T12:45:45Z"
}

Refresh before ExpirationTime to maintain streaming continuity.

KVM API Examples for the Mode Detection and CCM Consent Flow

Mode Detection: GET /redfish/v1/Systems/{SystemId} is the primary endpoint for KVM capability checks. OEM KVM state is surfaced under GraphicalConsole.Oem.Intel.AMT as three read-only fields. OEM action targets for the CCM consent flow are advertised under Actions.Oem.

ACM example (ControlMode=ACM - no consent required):

{
    "@odata.type": "#ComputerSystem.v1_26_0.ComputerSystem",
    "Id": "AMT-{DeviceGUID}",
    "Model": "Intel AMT",
    "PowerState": "On",
    "Status": { "State": "Enabled" },
    "GraphicalConsole": {
        "ServiceEnabled": true,
        "Port": 5900,
        "MaxConcurrentSessions": 4,
        "ConnectTypesSupported": ["KVMIP"],
        "Oem": {
            "Intel": {
                "AMT": {
                    "ControlMode": "ACM",
                    "KVMStatus": "Enabled",
                    "UserConsentStatus": "NotRequired"
                }
            }
        }
    },
    "Actions": {
        "Oem": {
            "#Oem.Intel.AMT.RequestKVMConsent": {
                "target": "/redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.RequestKVMConsent"
            },
            "#Oem.Intel.AMT.SubmitKVMConsentCode": {
                "target": "/redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.SubmitKVMConsentCode"
            },
            "#Oem.Intel.AMT.CancelKVMConsent": {
                "target": "/redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.CancelKVMConsent"
            }
        }
    }
}

CCM Consent Flow (ControlMode=CCM - three-step consent sequence):

Step CCM-1: Trigger consent prompt - POST #Oem.Intel.AMT.RequestKVMConsent

Request:

POST /redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.RequestKVMConsent
X-Auth-Token: {token}
Content-Type: application/json

{}

Response (200 OK):

{
    "GraphicalConsole": {
        "Oem": {
            "Intel": {
                "AMT": {
                    "KVMStatus": "PendingConsent",
                    "UserConsentStatus": "Requested"
                }
            }
        }
    }
}

The AMT device displays a 6-digit code on the physical screen. The local user must read and relay this code to the remote operator.

Step CCM-2: Poll for consent status - GET /redfish/v1/Systems/{SystemId}

Poll until UserConsentStatus transitions out of Requested:

GET /redfish/v1/Systems/{SystemId}
X-Auth-Token: {token}

Response while waiting (200 OK):

{
    "GraphicalConsole": {
        "Oem": {
            "Intel": {
                "AMT": {
                    "KVMStatus": "PendingConsent",
                    "UserConsentStatus": "Requested"
                }
            }
        }
    }
}

Step CCM-3: Submit the 6-digit code - POST #Oem.Intel.AMT.SubmitKVMConsentCode

Request:

POST /redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.SubmitKVMConsentCode
X-Auth-Token: {token}
Content-Type: application/json

{ "ConsentCode": 482916 }

Response on accepted (200 OK):

{
    "GraphicalConsole": {
        "Oem": {
            "Intel": {
                "AMT": {
                    "KVMStatus": "Enabled",
                    "UserConsentStatus": "Granted"
                }
            }
        }
    }
}

After Granted, proceed to generate a redirection token (Step 5), then WebSocket upgrade (Step 6).

Cancel consent (optional) - POST #Oem.Intel.AMT.CancelKVMConsent

Can be sent at any point during the pending-consent window:

POST /redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.CancelKVMConsent
X-Auth-Token: {token}
Content-Type: application/json

{}

Response (200 OK):

{
    "GraphicalConsole": {
        "Oem": {
            "Intel": {
                "AMT": {
                    "KVMStatus": "Enabled",
                    "UserConsentStatus": "NotRequired"
                }
            }
        }
    }
}

Enable KVM service (Step 3 - when disabled)

Request:

PATCH /redfish/v1/Systems/{SystemId}
X-Auth-Token: {token}
Content-Type: application/json

{
    "GraphicalConsole": {
        "ServiceEnabled": true
    }
}

Response (200 OK):

{
    "GraphicalConsole": {
        "ServiceEnabled": true,
        "Oem": {
            "Intel": {
                "AMT": {
                    "KVMStatus": "Enabled"
                }
            }
        }
    }
}

Disable KVM service (optional cleanup)

Request:

PATCH /redfish/v1/Systems/{SystemId}
X-Auth-Token: {token}
Content-Type: application/json

{
    "GraphicalConsole": {
        "ServiceEnabled": false
    }
}

Response (200 OK):

{
    "GraphicalConsole": {
        "ServiceEnabled": false,
        "Oem": {
            "Intel": {
                "AMT": {
                    "KVMStatus": "Disabled"
                }
            }
        }
    }
}

KVM Dynamic Behavior: GraphicalConsole.Oem.Intel.AMT fields drive the client decision logic:

ControlMode UserConsentStatus KVMStatus Client action
ACM NotRequired Enabled Generate redirection token (Step 5), then WebSocket upgrade (Step 6)
CCM NotRequired Enabled Generate redirection token (Step 5), then WebSocket upgrade (Step 6)
CCM Requested PendingConsent Poll GET /Systems/{SystemId} until status changes
CCM Granted Enabled Generate redirection token (Step 5), then WebSocket upgrade (Step 6)
CCM Denied or Timeout Enabled Re-trigger consent (RequestKVMConsent) or abort
Any Any Disabled Enable KVM first via PATCH (GraphicalConsole.ServiceEnabled=true), then proceed

SOL API Examples

SOL State Discovery

GET /redfish/v1/Systems/{SystemId}
X-Auth-Token: {token}
{
    "@odata.type": "#ComputerSystem.ComputerSystem",
    "Id": "AMT-{DeviceGUID}",
    "Model": "Intel AMT",
    "PowerState": "On",
    "Status": { "State": "Enabled" },
    "SerialConsole": {
        "MaxConcurrentSessions": 1,
        "WebSocket": {
            "ServiceEnabled": true,
            "ConsoleURI": "wss://{ConsoleHost}/relay/webrelay.ashx?host={SystemId}&mode=sol",
            "Interactive": true
        },
        "Oem": {
            "Intel": {
                "AMT": {
                    "ControlMode": "ACM",
                    "SOLStatus": "Enabled",
                    "UserConsentStatus": "NotRequired"
                }
            }
        }
    },
    "Actions": {
        "Oem": {
            "#Oem.Intel.AMT.RequestSOLConsent": {
                "target": "/redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.RequestSOLConsent"
            },
            "#Oem.Intel.AMT.SubmitSOLConsentCode": {
                "target": "/redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.SubmitSOLConsentCode"
            },
            "#Oem.Intel.AMT.CancelSOLConsent": {
                "target": "/redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.CancelSOLConsent"
            },
            "#Oem.Intel.AMT.GenerateRedirectionToken": {
                "target": "/redfish/v1/Systems/{SystemId}/Actions/Oem/IntelComputerSystem.GenerateRedirectionToken"
            }
        }
    }
}

SOL CCM consent flow (required in CCM mode)

Step SOL-CCM-1: Trigger consent prompt - POST #Oem.Intel.AMT.RequestSOLConsent

POST /redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.RequestSOLConsent
X-Auth-Token: {token}
Content-Type: application/json

{}

Response (200 OK):

{
    "SerialConsole": {
        "Oem": {
            "Intel": {
                "AMT": {
                    "SOLStatus": "PendingConsent",
                    "UserConsentStatus": "Requested"
                }
            }
        }
    }
}

Step SOL-CCM-2: Poll for consent status - GET /redfish/v1/Systems/{SystemId}

Poll until UserConsentStatus transitions out of Requested:

GET /redfish/v1/Systems/{SystemId}
X-Auth-Token: {token}

Response while waiting (200 OK):

{
    "SerialConsole": {
        "Oem": {
            "Intel": {
                "AMT": {
                    "SOLStatus": "PendingConsent",
                    "UserConsentStatus": "Requested"
                }
            }
        }
    }
}

Step SOL-CCM-3: Submit the 6-digit code - POST #Oem.Intel.AMT.SubmitSOLConsentCode

POST /redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.SubmitSOLConsentCode
X-Auth-Token: {token}
Content-Type: application/json

{ "ConsentCode": 482916 }

Response (200 OK):

{
    "SerialConsole": {
        "Oem": {
            "Intel": {
                "AMT": {
                    "SOLStatus": "Enabled",
                    "UserConsentStatus": "Granted"
                }
            }
        }
    }
}

Cancel SOL consent (optional) - POST #Oem.Intel.AMT.CancelSOLConsent

POST /redfish/v1/Systems/{SystemId}/Actions/Oem/ComputerSystem.CancelSOLConsent
X-Auth-Token: {token}
Content-Type: application/json

{}

Response (200 OK):

{
    "SerialConsole": {
        "Oem": {
            "Intel": {
                "AMT": {
                    "SOLStatus": "Enabled",
                    "UserConsentStatus": "NotRequired"
                }
            }
        }
    }
}

For CCM devices, generate a redirection token only after UserConsentStatus=Granted.

Enable WebSocket serial console (Step 3 - when disabled)

PATCH /redfish/v1/Systems/{SystemId}
X-Auth-Token: {token}
Content-Type: application/json

{
    "SerialConsole": {
        "WebSocket": {
            "ServiceEnabled": true
        }
    }
}

Response (200 OK):

{
    "SerialConsole": {
        "WebSocket": {
            "ServiceEnabled": true
        }
    }
}

WebSocket Upgrade (data plane)

GET /relay/webrelay.ashx?host={SystemId}&mode=sol HTTP/1.1
Host: {ConsoleHost}
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: {base64-random}
Sec-WebSocket-Protocol: {RedirectionToken}
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Protocol: {RedirectionToken}

Disable WebSocket serial console (optional cleanup)

PATCH /redfish/v1/Systems/{SystemId}
X-Auth-Token: {token}
Content-Type: application/json

{
    "SerialConsole": {
        "WebSocket": {
            "ServiceEnabled": false
        }
    }
}

SOL Dynamic Behavior

ControlMode UserConsentStatus SerialConsole.WebSocket.ServiceEnabled Client action
ACM NotRequired true Get token (Step 5), then open WebSocket to SerialConsole.WebSocket.ConsoleURI
CCM Requested true Poll GET /Systems/{SystemId} until consent status changes
CCM Granted true Get token (Step 5), then open WebSocket to SerialConsole.WebSocket.ConsoleURI
CCM Denied or Timeout true Re-trigger consent (RequestSOLConsent) or abort
Any Any false Enable SOL first via PATCH (Step 3), then proceed to Step 4

References

Architectural Standards

  1. Clean Architecture

  2. DMTF Redfish Specification v1.22.0

  3. ComputerSystem Graphical Console Schema

  4. DMTF Redfish Schema Catalog

Implementation Resources

  1. AMT User Consent Behavior (Intel)

  2. Device Management Toolkit Console

  3. Intel AMT WS-Management Messages

Console Wiki

ADRs

Clone this wiki locally