Duo Workflow: Update sequence diagram with auth

Why is this change being made?

This update clarifies the authentication mechanisms in use for each request.

Related discussion: gitlab-org&16549 (comment 2321842620)

Author and Reviewer Checklist

Please verify the check list and ensure to tick them off before the MR is merged.

• Provided a concise title for this Merge Request (MR)
• Added a description to this MR explaining the reasons for the proposed change, per say why, not just what
  • Copy/paste the Slack conversation to document it for later, or upload screenshots. Verify that no confidential data is added, and the content is SAFE
• Assign reviewers for this MR to the correct Directly Responsible Individual/s (DRI)
  • If the DRI for the page/s being updated isn’t immediately clear, then assign it to one of the people listed in the Maintained by section on the page being edited
  • If your manager does not have merge rights, please ask someone to merge it AFTER it has been approved by your manager in #mr-buddies
  • The when to get approval handbook section explains the workflow in more detail
• For transparency, share this MR with the audience that will be impacted.
  • Team: For changes that affect your direct team, share in your group Slack channel
  • Department: If the update affects your department, share the MR in your department Slack channel
  • Division: If the update affects your division, share the MR in your division Slack channel
  • Company: If the update affects all (or the majority of) GitLab team members, post an update in #whats-happening-at-gitlab linking to this MR
    • For high-priority company-wide announcements work with the internal communications team to post the update in #company-fyi and align on a plan to circulate in additional channels like the "While You Were Iterating" Newsletter

Commits

• Duo Workflow: Update sequence diagram with auth

• Follow up to conversation here: gitlab-org&16549 (comment 2321842620)

---

content/handbook/engineering/architecture/design-documents/duo_workflow/_index.md

@@ -134,12 +134,14 @@ sequenceDiagram
      participant ai_gateway as AI Gateway
    end
    participant llm_provider as LLM Provider
-   ide->>gitlab_rails: Request AI Gateway JWT using OAuth token or PAT
-   ide->>executor: start executor with JWT
    user->>ide: trigger workflow from IDE
+   ide->>gitlab_rails: Create the workflow
+   gitlab_rails->>gitlab_rails: Create JWT for Duo Workflow Service
+   gitlab_rails->>gitlab_rails: Create ai_workflow scoped OAuth token
+   gitlab_rails->>gitlab_rails: Create the workflow
+   gitlab_rails->>ide: Return the workflow details and JWT and OAuth tokens
+   ide->>executor: start executor with workflow details and JWT and OAuth token
    executor->>+duo_workflow_service: Solve this issue (open grpc connection auth'd with AI Gateway JWT)
-   duo_workflow_service->>gitlab_rails: Request ai_workflow scoped OAuth token using AI Gateway JWT
-   duo_workflow_service->>gitlab_rails: Create the workflow (auth'd with ai_workflow OAuth token)
    duo_workflow_service->>llm_provider: Ask LLM what to do
    llm_provider->>duo_workflow_service: Run rails new my_new_app
    duo_workflow_service->>executor: execute `rails new my_new_app`
@@ -150,7+152,7 @@
    duo_workflow_service->>gitlab_rails: Save checkpoint and mark completed
    duo_workflow_service->>gitlab_rails: Revoke ai_workflow scoped OAuth token
    deactivate duo_workflow_service
    gitlab_rails->>user: Workflow done!
 ```
 
 #### With Remote (CI pipeline) execution
 
 ```mermaid
 sequenceDiagram
-   participant user as User
-   participant gitlab_rails as GitLab Rails
-   box CI-Runner
-      participant executor as Duo Workflow Executor
-   end
-   box AI-gateway service
-     participant duo_workflow_service as Duo Workflow Service
-     participant ai_gateway as AI Gateway
-   end
-   participant llm_provider as LLM Provider
-
-   user->>gitlab_rails: trigger workflow from Web UI
-   gitlab_rails->>executor: start executor (sends AI Gateway JWT with request)
-   executor->>+duo_workflow_service: Solve this issue (open grpc connection auth'd with AI Gateway JWT)
-   duo_workflow_service->>gitlab_rails: Request ai_workflow scoped OAuth token using AI Gateway JWT
-   duo_workflow_service->>gitlab_rails: Create the workflow (auth'd with ai_workflow OAuth token)
-   duo_workflow_service->>llm_provider: Ask LLM what to do
-   llm_provider->>duo_workflow_service: Run rails new my_new_app
-   duo_workflow_service->>executor: execute `rails new my_new_app`
-   executor->>duo_workflow_service: result `rails new my_new_app`
-   duo_workflow_service->>gitlab_rails: Save checkpoint
-   duo_workflow_service->>llm_provider: What's next?
-   llm_provider->>duo_workflow_service: You're finished
-   duo_workflow_service->>gitlab_rails: Save checkpoint and mark completed
-   duo_workflow_service->>gitlab_rails: Revoke ai_workflow scoped OAuth token
-   deactivate duo_workflow_service
-   gitlab_rails->>user: Workflow done!
+    autonumber
+    participant user as User
+    participant gitlab_rails as GitLab Rails
+    box CI-Runner #LightYellow
+        participant executor as Duo Workflow Executor
+    end
+    box AI-gateway service #LightBlue
+        participant duo_workflow_service as Duo Workflow Service
+        participant ai_gateway as AI Gateway
+    end
+    participant llm_provider as LLM Provider
+
+    note over user,gitlab_rails: User is logged in via web
+    user->>gitlab_rails: trigger workflow from Web UI
+    gitlab_rails->>gitlab_rails: Create JWT for Duo Workflow Service
+    gitlab_rails->>gitlab_rails: Create ai_workflow scoped composite identity OAuth token
+    gitlab_rails->>gitlab_rails: Create the workflow
+
+    gitlab_rails->>executor: start executor in CI pipeline with workflow details and JWT and composite identity OAuth token
+
+    note over executor,duo_workflow_service: AI Gateway JWT
+    executor->>+duo_workflow_service: Solve this issue (open gRPC connection)
+
+    note over duo_workflow_service,llm_provider: API Key (from env)
+    duo_workflow_service->>llm_provider: Ask LLM what to do
+    llm_provider-->>duo_workflow_service: Run rails new my_new_app
+
+    note over duo_workflow_service,executor: Authenticated gRPC
+    duo_workflow_service->>executor: execute `rails new my_new_app`
+    executor-->>duo_workflow_service: command result
+
+    note over duo_workflow_service,gitlab_rails: Composite OAuth token
+    duo_workflow_service->>gitlab_rails: Save checkpoint
+
+    note over duo_workflow_service,llm_provider: API Key (from env)
+    duo_workflow_service->>llm_provider: What's next?
+    llm_provider-->>duo_workflow_service: You're finished
+
+    note over duo_workflow_service,gitlab_rails: Composite OAuth token
+    duo_workflow_service->>gitlab_rails: Save checkpoint & mark completed
+    duo_workflow_service->>gitlab_rails: Revoke Composite OAuth token
+    deactivate duo_workflow_service
+
+    note over gitlab_rails,user: No Auth Required
+    gitlab_rails->>user: Workflow done!
 ```
 
 ### Self-managed architecture