Configuring JWT authentication for Jenkins with Teleport Application Access

[webvictim]

Here is a guide on how to configure JWT authentication with Jenkins so you can pass Teleport usernames and roles through to a Jenkins instance.

Prerequisites

• A working Teleport cluster
• A working Jenkins instance which can download plugins from the internet
• Teleport application access configured to proxy access to Jenkins

Teleport app access configuration

Here's a rough guide of what the Teleport app_service configuration should already look like:

app_service:
  enabled: "yes"
  debug_app: true
  apps:
  - name: jenkins
    description: "Jenkins server"
    uri: http://localhost:8080
    labels:
      app: jenkins
      env: docker
    rewrite:
      redirect:
        - localhost

This will make Jenkins available on a subdomain of your cluster, i.e. https://jenkins.teleport.example.com

Logging in here should already work correctly assuming you enter the correct username/password for a local Jenkins user. If this does not work correctly, fix it before continuing with this guide.

Example JWT token

This is a rough example of what a decrypted JWT token will look like when sent from Teleport. We will use this example to configure Jenkins appropriately.

{
  "aud": [
    "http://127.0.0.1:37491"
  ],
  "exp": 1667520826,
  "iat": 1667506428,
  "iss": "teleport.example.com",
  "nbf": 1667506418,
  "roles": [
    "access",
    "editor",
    "sysadmin",
    "allow-requests",
    "allow-user-root",
    "per-session-mfa",
    "allow-aws-readonly",
    "allow-mssql-access",
    "allow-mysql-access",
    "allow-postgres-access",
    "kubernetes-access-eks",
    "kubernetes-access-gke",
    "allow-request-approval",
    "windows-desktop-access",
    "allow-aws-ec2-fullaccess"
  ],
  "sub": "gus@example.com",
  "username": "gus@example.com"
}

Configuring Jenkins

1. Log into Jenkins as an administrator and install the "JWT Auth" plugin. This can be done under Manage Jenkins -> Manage Plugins -> Available Plugins. Enter "JWT Auth" into search, check the "Install" box next to the plugin and click "Download now and install after restart" at the bottom.

2. Restart Jenkins and log in again. Go to Manage Jenkins -> Configure Global Security.

3. Select "JWT Header Authentication Plugin" from the list of security realms.

Change the settings to match as follows:

Authentication

• Header name: Teleport-Jwt-Assertion
• Username claim name: sub
• Groups claim name: roles
• Groups claim list separator: ,
• JWKS JSON URL: https://teleport.example.com/.well-known/jwks.json # replace with your public Teleport URL

Authorization

Set this to "Logged-in users can do anything"

You can change and set permissions this in future after you've proven that users can sign in correctly.

JWKS URL tips

• Replace teleport.example.com here with the public address of your Teleport cluster.
• If the URL you use to access Jenkins is jenkins.customer.domain.com, your public URL is customer.domain.com
• If you are a Teleport cloud customer, this will be tenant.teleport.sh
• This URL is publicly accessible without authentication, so loading https://teleport.example.com/.well-known/jwks.json in your browser should output a JSON payload similar to this:

{"keys":[{"kty":"RSA","alg":"RS256","n":"ohCpCcv7VuvetyzNnFiPw79XMFm27OgJZMup7VSSSMpcRFcZtXkYvHWe_8H6VdKeb0AsnTfKrBKbNFc0h3uulLQq5a7kAJKwwTcS3KrgDfzzctnJkAJylWjYmOsw1VdSdJ_Ci0xjw8_jMFqRTvRt9PZj6bBq-hKTTW9nNNE20uO5wHhB6bqK6Fw26Vi--0-qXXOXGGHiuoZXIEp25MkC27c8eVxDWm8B_DOu_fHT08qeGxYwYnH_Xjm8DCOeEA7lyeQOr4Z66RFTxzXYj3D8Q8EpZeh6DJaKgWidvxkTDAD3IM_Oc6YV2sZ3WAkGe8RIyNQpU-3tGVfQkbstc-lfaw","e":"AQAB"}]}

4. Save the settings. You will probably be logged out of Jenkins.

Reloading the page should log you in as your Teleport username (as shown at the top right here)

Troubleshooting

If this does not work and you get "Authentication failed", check your Jenkins server logs. The chances are that you have misconfigured something:

2022-12-05 17:10:53.330+0000 [id=17]	SEVERE	i.j.p.j.JwtAuthSecurityRealm$1#getAuthFromToken: Could not decode the JWT
org.jose4j.jwt.consumer.InvalidJwtException: JWT (claims->{"aud":["http://localhost:8080"],"exp":1670273533,"iat":1670260108,"iss":"purple","nbf":1670260098,"roles":["access","editor","sysadmin","allow-requests","allow-user-root","per-session-mfa","allow-aws-readonly","allow-mssql-access","allow-mysql-access","allow-postgres-access","kubernetes-access-eks","kubernetes-access-gke","allow-request-approval","windows-desktop-access","allow-aws-ec2-fullaccess"],"sub":"gus@example.com","username":"gus@example.com"}) rejected due to invalid claims or other invalid content. Additional details: [[12] Issuer (iss) claim value (purple) doesn't match expected value of teleport.example.com]

You can edit the JWT auth configuration directly in your /var/lib/jenkins/config.xml file and then restart Jenkins to fix typos or other errors. If you can't fix it, you can get back in by disabling security globally (only on test instances!) and then restarting Jenkins:

Edit config.xml and change <useSecurity>true</useSecurity> to <useSecurity>false</useSecurity> and restart Jenkins.

Make sure to re-enable security afterwards!

[goodgoblin]

this is AWESOME - thank you!