ContextQMD
Back to Gitlabhq

Composite identity

doc/user/duo_agent_platform/composite_identity.md

18.11.25.6 KB
Original Source

{{< history >}}

  • Introduced in GitLab 18.3 with a flag named duo_workflow_use_composite_identity.
  • Generally available in GitLab 18.8.
  • Composite identity automatically included in GitLab Duo Agent Platform and setting to turn composite identity on or off removed in GitLab 18.9.

{{< /history >}}

Composite identity is an authentication and authorization mechanism that combines two identities into a single token:

  • A service account. The machine user that performs the actual actions.
  • A human user. The person who initiated the request.

Composite identity is automatically included in GitLab Duo Agent Platform.

This dual-identity approach solves a critical challenge: agents need to act with access that does not exceed the access of the user who triggered them, or the access that the service account was granted, while maintaining a distinct identity that clearly shows the action was performed by an agent, not directly by the human user.

Why composite identity matters

The composite identity is important because it helps ensure:

  • Traceability: All agent activities are clearly attributed to a service account, making it easy to identify automated actions in audit logs and commit histories.
  • Security: The agent can perform actions that only the service account and the triggering user have access to do. This intersectional access prevents privilege escalation.
  • Accountability: The human user's identity is embedded in the token, creating an audit trail that links agent actions back to the person who initiated them.

For example, when you ask an agent to create tests for your code, the resulting commits will show they were created by the service account on your behalf.

Where composite identity is used

Composite identity is used when flows and agents execute on runners. This list includes:

  • Foundational flows.
  • Custom flows.
  • External agents.
  • Any flow started through the endpoint api/v4/ai/duo_workflows/workflows.

Composite identity does not apply to GitLab Duo Agentic Chat in the UI and IDE.

How composite identity works

The token that authenticates requests is a composite of two identities:

  • Primary author: The human user who started the agent or flow. The human user's id is included in the scopes of the token by using a dynamic scope.
  • Secondary author: A service account, which is the owner of the token and has the Developer role.

This composite identity ensures that any activities authored by the GitLab Duo Agent Platform are attributed to the human user, while preventing privilege escalation by either the human user or the service account.

Composite identity workflow

The composite identity is part of the workflow.

  1. Create a flow in the AI Catalog.
    • No composite identity-related changes occur.
  2. Enable the flow for a project.
    • A service account is created in the top-level group. (The name is similar to ai-flowname-groupname.)
    • The service account is added to the project with the Developer role.
  3. A user executes the flow.

    • The flow is executed by a one-time composite identity. This identity has a combination of the user's role and the service account's Developer role, whichever is more restrictive. So if the user is a Maintainer, but the service account is a Developer, the Developer role is used.

    • The flow has access to all projects that both:

      • The user has access to.
      • The service account has been added to.

      For example, if the service account has been added to other projects, and the user has access to those projects the flow can access those projects even if the user has not used the flow there before.

Token permissions for AI Catalog flows

AI Catalog flows use different token types with different permission scopes:

  • OAuth tokens used for composite identity in AI workflows have access restricted to the ai_workflows and mcp scopes. This OAuth token is passed to the AI Gateway to run the flow.
  • CI job tokens that are triggered as part of the flow have permissions further restricted by the available job token permissions.

Because these are different token types with different scopes, the CI/CD job has different permissions than the OAuth token.

Compliance considerations for merge requests

When a flow creates a merge request, the merge request is attributed to the human user who triggered the flow instead of the service account. This is done to adhere to compliance frameworks that require segregation of duties, including:

  • SOC 2 (System and Organization Controls 2)
  • SOX (Sarbanes-Oxley Act)
  • ISO 27001 (Information Security Management)
  • FedRAMP (Federal Risk and Authorization Management Program)

These frameworks typically require that a user cannot author code changes and approve those changes for production deployment.

Understanding the attribution model

Even though the service account creates the commits and opens the merge request, the human user is considered the author because:

  • The human user directed the service account to create the changes.
  • From a compliance perspective, prompting an AI system to write code is equivalent to writing the code yourself.
  • The service account acts as a proxy for the human user's intent.