RFC: Add OIDC authentication flow for Deployments (enable GitHub Actions / GitLab CI to deploy without static tokens)

[tomscholz]

Hello everyone,

I've been working with the hosted version of Mender Server and really like it so far. Today I'd like to propose a new feature: OIDC-based authentication for the community version of Mender Server.

The Problem

Currently, Mender users can only create traditional static API tokens for CI/CD systems (GitHub Actions, GitLab CI, etc.) to access the Mender Server API. This approach creates unnecessary security and operational risk. Static tokens are often forgotten about, leading to unexpected CI pipeline failures months later. They also require manual rotation and create lingering credentials that pose a security liability.

Short-lived tokens naturally solve these problems: they expire automatically after minutes, eliminating the need for manual rotation and reducing the window of exposure if compromised.

The Solution

I propose adding OIDC-based authentication to Mender. This would allow CI/CD systems to obtain short-lived tokens from the Mender server using an OIDC JWT issued by the CI provider, rather than relying on long-lived static tokens.

This is a well established pattern in the public cloud ecosystem (AWS, GCP, Azure, etc.) and has become the industry standard for authenticating temporary workloads. It eliminates the risk of having credentials lying around and removes the need for token rotation management.

How It Works

In practice, a CI job would request a short-lived deployment token from the Mender server using its OIDC JWT. The server would validate the JWT and return a token valid for a short period (e.g., 5–10 minutes). The CI job would then perform the deployment using that token. Once the token expires, it is automatically forgotten.

sequenceDiagram
    participant IdP as Identity Provider
    participant CI as CI/CD Job
    participant M as Mender Server

    CI->>IdP: Request OIDC JWT ID Token
    IdP->>CI: Return OIDC JWT ID Token
    CI->>M: Request short-lived token via OIDC JWT ID Token
    M->>M: Validate JWT ID token
    M->>CI: Return short-lived access token
    CI->>M: Upload artifact using short-lived access token
    CI->>M: Create release using short-lived access token

Loading

Example: GitHub Actions Workflow

Here's a practical example using GitHub Actions. A job requests a short-lived token via the GitHub Actions OIDC provider. The Mender server issues a token valid for five minutes, which the job uses to deploy. After the job finishes, the token expires automatically.

name: Mender example workflow
on:
  push
env:
  MENDER_SERVER_URL: https://eu.hosted.mender.io

permissions:
  id-token: write   # Required for requesting the JWT
  contents: read    # Required for actions/checkout

jobs:
  MenderArtifactUpload:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v5

      - name: Configure credentials
        uses: mendersoftware/mender-gh-action-setup@v1

      - name: Upload Mender Artifact to Mender server
        uses: mendersoftware/mender-gh-action-upload-artifact@f3e7dc6b54c2e84803891954f47b284f5cc1a1ee
        with:
          mender_uri: ${{ env.MENDER_SERVER_URL }}
          mender_artifact: production-image-raspberrypi5.signed.mender

Setting Up the Trust Relationship

To enable OIDC-based deployments, you would have to establish a trust relationship between your Mender server and GitHub Actions.

Here a modified version from depot.dev of what that could look like:

1. Navigate to your Mender server's settings or administration panel
2. Find the "OIDC Trust Relationships" or "CI Provider Configuration" section
3. Click "Add Trust Relationship"
4. Select GitHub Actions as the provider
5. Enter your GitHub organization or username
6. Enter the exact repository name where your workflow will run (e.g., firmware or mender-releases)
7. Optionally, restrict by workflow file or branch for additional security
8. Click "Add Trust Relationship" and note the configuration details

Why This Matters

It

• Reduces security risk by avoiding long-lived credentials
• Aligns with modern CI/CD security practices used across the industry
• Eliminates token rotation management overhead
• Provides a safer, simpler workflow for automated deployments

Request for Feedback

I am willing to put in the work to develop this feature. However before I invest the time, I would appreciate some feedback and confirmation from the maintainers that we can actually ship this feature.

Looking forward to hear from you! :)