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 MR: gitlab-org/modelops/applied-ml/code-suggestions/ai-assist!7350 (merged)
- Issue: gitlab-org/modelops/applied-ml/code-suggestions/ai-assist#2851 (closed)
- AppSec review item 2: !253227 (comment 3813076767)
- Prior flow ID binding: !253227 (merged) and gitlab-org/modelops/applied-ml/code-suggestions/ai-assist!6430 (merged)
- Websocket follow-up: https://gitlab.com/gitlab-org/gitlab/-/work_items/633578
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
-
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. -
Turn DWS auth on. Without it every caller is a debug user and the checks are skipped. In
gitlab-ai-gateway/.envsetDUO_WORKFLOW_AUTH__ENABLED=true. With GDK's self-signed HTTPS, also setREQUESTS_CA_BUNDLEto a bundle that includes the GDK cert. Rungdk restart duo-workflow-service. -
If
enforce_composite_identity_for_api_started_workflowsis on, the flow's service account needs composite identity. Otherwise the start returns 403A composite identity service account is required to start this workflow. -
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>" -
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" -
The job log prints
developer,^3.0.0, andv1. -
Decode the job's
DUO_WORKFLOW_SERVICE_TOKENto check the claims. The DWSGenerateTokenlog line showsflow_version=Noneregardless, 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"} -
Check enforcement. Run the Rails console with
CLOUD_CONNECTOR_SELF_SIGN_TOKENS=1(GDK sets it inenv.runit), or minting fails withForbidden 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
ExecuteWorkflowwith it, for example through the gRPC stub ofAi::DuoWorkflow::DuoWorkflowService::Clientwith metadatabearer_token: token. WithflowConfigId: 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.
-
Optional: run Fix Pipeline with
fix_pipeline_experimentalon, then off. Token and job carryexperimental/1.0.0, thenv1/1.0.4. Wait about a minute after each toggle, because flag values are cached per process for 1 minute. Workplan withworkplan_scoretoggled resolves1.1.0, then1.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.