Bind workflow tokens to foundational flow version and schema

What does this MR do and why?

When Rails mints a DWS workflow token, it now passes the resolved foundational flow version and schema version with the flow ID. DWS can then reject an executor that connects directly over gRPC and asks for another version or schema of the same flow, for example one behind a feature flag not enabled for the user. CI runs connect through the Workhorse websocket, whose token doesn't carry the version or schema claims yet (and carries the flow ID only for gitlab_hosted_runner_only flows). That's tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/633578.

Schema matters because the same ID and version can exist under v1 and experimental: fix_pipeline 1.0.0 exists in both, and fix_pipeline_experimental selects experimental.

Token and executor values come from the same resolved hash, so they cannot disagree.

Path Mint site
CI runtime (code review, workplan, readiness score, session continuations) Ai::DuoWorkflows::Runtimes::Ci
Workplan resume Ai::DuoWorkflows::ResumeWorkplanService
AI Catalog, flow triggers, messaging Ai::Catalog::ExecuteWorkflowService
POST /api/v4/ai/duo_workflows/workflows, foundational flow resume API::Helpers::DuoWorkflowHelpers

Unbound: non-foundational flows, the direct-access token endpoint, and inline catalog flows. Inline flows get no schema claim because only the caller-resolved schema is passed, not the 'v1' fallback.

Vendors gitlab-duo-workflow-service-client 0.16 (from 0.15), which adds GenerateTokenRequest fields flow_version (5) and flow_config_schema_version (6). Custom catalog flows resumed through Runtimes::Ci carry the flow config digest but no schema version claim, the same as inline flows started through ExecuteWorkflowService.

References

DWS/Rails Compatibility

Either MR can deploy first. Old Rails with new DWS works because tokens have no claims. New Rails with old DWS works because the optional fields are ignored. Only new with new blocks substitution.

DWS checks each claim only when present, then requires an exact string match. duo-cli already sends DUO_WORKFLOW_FLOW_VERSION and DUO_WORKFLOW_FLOW_CONFIG_SCHEMA_VERSION as flowVersion and flowConfigSchemaVersion.

Screenshots or screen recordings

Not applicable. No UI.

How to set up and validate locally

  1. Prerequisites: GDK on this branch, DWS from the DWS MR, Duo Agent Platform and Developer Flow enabled for a test project, and a runner tagged gitlab--duo.

  2. Turn DWS auth on. Without it every caller is a debug user and the checks are skipped. In gitlab-ai-gateway/.env set DUO_WORKFLOW_AUTH__ENABLED=true. With GDK's self-signed HTTPS, also set REQUESTS_CA_BUNDLE to a bundle that includes the GDK cert. Run gdk restart duo-workflow-service.

  3. If enforce_composite_identity_for_api_started_workflows is on, the flow's service account needs composite identity. Otherwise the start returns 403 A composite identity service account is required to start this workflow.

  4. Set:

    export GITLAB_URL="https://gdk.test:3443"   # or http://gdk.test:3000
    export GITLAB_TOKEN="<personal-access-token-with-api-scope>"
    export PROJECT_ID="<numeric-project-id>"
  5. Start Developer Flow:

    curl --request POST \
      --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
      --header "Content-Type: application/json" \
      --data "{
        \"project_id\": \"$PROJECT_ID\",
        \"workflow_definition\": \"developer/v1\",
        \"goal\": \"Create hello.txt containing hello\",
        \"start_workflow\": true
      }" \
      --url "$GITLAB_URL/api/v4/ai/duo_workflows/workflows"
  6. The job log prints developer, ^3.0.0, and v1.

  7. Decode the job's DUO_WORKFLOW_SERVICE_TOKEN to check the claims. The DWS GenerateToken log line shows flow_version=None regardless, so do not rely on it. The session runs to completion.

    JWT.decode(Ci::Build.find(<job_id>).variables.find { |v| v[:key] == 'DUO_WORKFLOW_SERVICE_TOKEN' }[:value], nil, false).first.slice('flow_config_id', 'flow_version', 'flow_config_schema_version')
    # => {"flow_config_id"=>"developer", "flow_version"=>"^3.0.0", "flow_config_schema_version"=>"v1"}
  8. Check enforcement. Run the Rails console with CLOUD_CONNECTOR_SELF_SIGN_TOKENS=1 (GDK sets it in env.runit), or minting fails with Forbidden by auth provider. Mint a bound token:

    user = User.find_by_username('root')
    project = Project.find(<numeric-project-id>)
    Ai::DuoWorkflows::WorkflowContextGenerationService.new(
      current_user: user, organization: project.organization, container: project
    ).generate_workflow_token(
      flow_config_id: 'fix_pipeline', flow_version: '1.0.0', flow_config_schema_version: 'experimental'
    ).payload[:token]

    Call DWS ExecuteWorkflow with it, for example through the gRPC stub of Ai::DuoWorkflow::DuoWorkflowService::Client with metadata bearer_token: token. With flowConfigId: fix_pipeline:

    • flowVersion: 1.0.0, flowConfigSchemaVersion: v1: PERMISSION_DENIED (schema version), before flow resolution.
    • flowVersion: 1.0.4, flowConfigSchemaVersion: experimental: PERMISSION_DENIED (version).
    • Exact match: allowed.
  9. Optional: run Fix Pipeline with fix_pipeline_experimental on, then off. Token and job carry experimental/1.0.0, then v1/1.0.4. Wait about a minute after each toggle, because flag values are cached per process for 1 minute. Workplan with workplan_score toggled resolves 1.1.0, then 1.0.0.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist.

  • Specs use real values, and the client spec checks fields 5 and 6.
  • All server-started foundational paths bind version and schema. Non-foundational, inline, and direct-access stay unbound.
Edited by Alper Akgun

Merge request reports

Loading
Loading