Jenkins Integration

Jenkins can authenticate users from headers set by an upstream proxy using the Reverse Proxy Auth plugin, and it can map the Groups in those headers to permissions using the Role-Based Strategy plugin. Together they let Twingate Identity Firewall drive both authentication and authorization in Jenkins with no code changes. You only add three plugins and a configuration file.

For the architecture and the full list of headers the Gateway can inject, see the Identity Firewall for Web Apps overview. For the shared security model behind trusted-header integrations, see Web App Integrations.

Prerequisites

• A Jenkins instance you administer (this guide was verified against jenkins/jenkins:lts-jdk17).
• Administrator access to install plugins and apply configuration.
• A Twingate Web App Resource for Jenkins, network-isolated so the Gateway is the only path to it.

Install Plugins

Install these three plugins from Manage Jenkins → Plugins, or bake them into your image:

• configuration-as-code applies the security and authorization config below declaratively.
• reverse-proxy-auth-plugin provides the trusted-header security realm that reads the user and Groups.
• role-strategy maps Groups to named roles and permissions.

Configure Jenkins (JCasC)

Apply the following Configuration as Code file. It declares the security realm (authentication) and the authorization strategy in one place:

jenkins:
  securityRealm:
    reverseProxy:
      forwardedUser: "X-Forwarded-User"
      headerGroups: "X-Forwarded-Groups"
      headerGroupsDelimiter: ","
      disableLdapEmailResolver: true

  authorizationStrategy:
    roleBased:
      roles:
        global:
          - name: "admin"
            description: "Full administrative access (mapped from the 'jenkins-admin' group)."
            permissions:
              - "Overall/Administer"
            entries:
              - group: "jenkins-admin"
          - name: "viewer"
            description: "Read-only access (mapped from the 'jenkins-viewer' group)."
            permissions:
              - "Overall/Read"
              - "Job/Read"
              - "View/Read"
            entries:
              - group: "jenkins-viewer"

A few field names matter here:

• forwardedUser is the header Jenkins reads the username from. Users provision on first request, so you don’t pre-create accounts.
• headerGroups is the header carrying the Group list. Use headerGroups, not forwardedGroups. The forwarded* attributes are for display name and email.
• entries is how Role Strategy assigns a Group to a role. The older assignments form is rejected as deprecated.

Configure the Twingate Gateway

On the Jenkins Web App Resource, add request headers so the Gateway injects the identity and the user’s Groups on every request:

Map Groups to Roles

The entries in the JCasC file connect a Twingate Group name to a Jenkins role:

Name your Twingate Groups to match the entries values (jenkins-admin, jenkins-viewer), or edit the JCasC file to match your existing Group names. Naming them for the app they authorize keeps them clear in your identity provider and avoids clashing with the Group names the Gateway always sends (see the note below). To add a tier, add another role block with its own permissions and entries.

How It Works

On each request, the Gateway injects X-Forwarded-User and X-Forwarded-Groups, then forwards to Jenkins. The Reverse Proxy Auth realm reads the username from X-Forwarded-User and the Group list from X-Forwarded-Groups, exposing the Groups as Jenkins “authorities.” Role-Based Strategy then matches those authorities against the entries in each role and grants the role’s permissions.

Because permissions come from the Group header, moving a user between Twingate Groups changes their Jenkins access on the next request. A user in jenkins-admin gets Manage Jenkins, while a user in jenkins-viewer gets read-only access with the admin menus hidden.

Security

Trusted-header realms normally make you hand-roll the guarantee that the header can only come from your proxy. With Twingate you don’t. The Jenkins Resource is reachable only through the Gateway, and the Gateway overwrites any client-supplied X-Forwarded-User or X-Forwarded-Groups, so a forged header never reaches Jenkins. See Web App Integrations for the full model.

Next Steps

• Grafana integration guide for another trusted-header app
• Web App Integrations for the shared trusted-header pattern
• Identity Firewall for Web Apps overview for all available header template variables

Join us in the community subreddit to share your setup or ask questions.