Add GitLab Workload Identity Federation design doc

---

title: "GitLab Workload Identity Federation"

status: proposed

creation-date: "2025-03-21"

authors: [ "@grzesiek" ]

approvers: [ "@maw" ]

owning-stage: "~devops::sec"

toc_hide: true

---

{{< engineering/design-document-header >}}

## Summary

Currently, the primary method for machine-type identities to interact with GitLab is through

Personal Access Tokens (PATs). Since PATs are relatively long-lived, there is a significant

risk of them being leaked or stolen by malicious actors.

While users sometimes use OAuth access tokens for shorter-lived credentials, this approach is not

ideal. A widely adopted alternative in the industry is [workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation),

which is built on top of OpenID Connect (OIDC). GitLab users already use this method to authenticate

with platforms like Google Cloud Platform and AWS, but there is no way to authenticate with GitLab

using identity federation.

This design document outlines the path toward implementing GitLab Workload Identity Federation.

This will enable GitLab users to grant access to a GitLab instance to external identities by

mapping external principals to GitLab identities and defining rules for their authentication

and authorization.

## Goals

The main goal is to add support for GitLab to recognize external identities and map them to

GitLab principals using OIDC identity tokens from external identity providers.

## Requirements

1. GitLab users can define a list of external identity providers that are allowed to access

   GitLab resources within configured groups and projects.

1. GitLab users can map external identities onto GitLab service accounts.

1. GitLab users can define rules for the mapping using claims from external identity tokens.

1. GitLab users can audit access granted to external identities through audit logs.

1. External identity tokens can be used to authenticate with GitLab APIs, provided the external

   identity provider is properly configured in GitLab.

## Proposal

The proposed solution is to build a token exchange service that reads GitLab Workload Identity

Federation rules from the GitLab API. Based on this metadata, the service will recognize and

validate identity tokens from external identity providers. The claims in these tokens will be

used to map an external identity to a GitLab principal. After a successful mapping, the GitLab

Secure Token Service (STS) will mint a new token that client SDKs can use to interact with

GitLab APIs.

```mermaid

sequenceDiagram

    participant External Identity Provider

    participant Client

    participant GitLab STS as GitLab Secure Token Service

    participant GitLab Rails

    External Identity Provider->>External Identity Provider: Mint identity token

    External Identity Provider->>Client: Provide external identity token

    Client->>GitLab STS: Send external token

    GitLab STS->>GitLab Rails: Verify if external IdP is allowed

    GitLab Rails-->>GitLab STS: Confirm IdP is allowed

    GitLab STS->>External Identity Provider: Request JWKs

    External Identity Provider-->>GitLab STS: Return JWKs

    GitLab STS->>GitLab STS: Validate external token signature

    GitLab STS->>GitLab Rails: Request identity mapping metadata

    GitLab Rails-->>GitLab STS: Return identity mapping metadata

    GitLab STS->>GitLab STS: Mint new token including mapped principal

    GitLab STS-->>Client: Return new token

    Client->>GitLab Rails: Authenticate with new token

    GitLab Rails-->>Client: Process authenticated request

```

## Decisions

1. [STS-001: Open-source the GLGO service built for GCP integration.](./decisions/001_open_source_glgo.md)

1. [STS-002: Merge GLGO into IAM service.](./decisions/002_merge_glgo_into_iam_service.md)

1. STS-003: Implement mapping from external identities to GitLab service accounts.

1. STS-004: Add support for accessing GitLab APIs with JWTs minted by the GitLab STS.

---

title: 'GitLab WLIF: STS-001 Open-Source GLGO'

toc_hide: true

---

## Context

We developed GLGO as an identity translation layer between GitLab and cloud providers like

Google Cloud Platform and AWS. We now plan to extend it into a general-purpose

GitLab Secure Token Service (STS). This service will be responsible for minting tokens that

users can use to authenticate with GitLab APIs.

## Decision

We have decided to make GLGO an open-source project under a permissive license.

## Consequences

Making GLGO open-source will allow the community to audit the code and contribute to its

development.

## Alternatives

Keeping GLGO as a closed-source project would limit its availability in GitLab distribution

packages. This could hinder our plans to deliver GitLab Workload Identity Federation and other

engineering projects that depend on GLGO's availability.

While we could build this functionality directly into GitLab Rails, it would not provide

sufficient isolation for authentication data and signing materials from the rest of the

GitLab monolith.

---

title: 'GitLab WLIF: STS-002 Merge GLGO into IAM Service'

toc_hide: true

---

## Context

GLGO was created as a specialized identity translation layer between GitLab and

external cloud providers. We are now building a new, centralized Identity and

Access Management (IAM) service in Go. This service is intended to become the

authoritative source for identity and access management code at GitLab.

To avoid code duplication, consolidate our services, and make identity features

available to self-managed customers, we need to decide where the functionality

of GLGO should live long-term.

## Decision

We will merge the functionality of the GLGO service into the new IAM service.

The IAM service will incorporate and expand upon GLGO's capabilities, including

the Secure Token Service (STS) for Workload Identity Federation.

## Consequences

**Positive:**

* **Codebase Consolidation:** Merging GLGO into the IAM service centralizes

    our identity management logic, reducing maintenance overhead.

* **Availability for Self-Managed:** Integrating this functionality into a

    core service like IAM makes it easier to package and deliver to

    self-managed GitLab customers.

* **Unified Architecture:** It establishes the IAM service as the single

    place for identity-related features, creating a clearer and more

    maintainable architecture.

**Negative:**

* **Migration Effort:** This decision requires a migration effort to move

    existing GLGO functionality into the new IAM service codebase.

## Alternatives

1. **Keep GLGO as a Standalone Service:** We could continue to develop GLGO as

a separate service. However, this would lead to code duplication and increased

maintenance complexity. It would also complicate efforts to bring this

functionality to self-managed instances.

2. **Integrate GLGO into GitLab Rails:** This is not a viable alternative

because it would not provide sufficient isolation for sensitive authentication

data and signing materials from the rest of the GitLab monolith.