Jenkins SSO with Keycloak using OIDC

Introduction

Jenkins does not ship with OIDC support. You install the oic-auth plugin (OpenID Connect Authentication Plugin), configure it as the security realm, and Jenkins delegates authentication to Keycloak. From that point, users click a button on the Jenkins login page, authenticate in Keycloak, and land in Jenkins with an account created from the token claims.

This guide covers Jenkins LTS 2.x with Keycloak 24+. Both should run on HTTPS in production.

Prerequisites

• Keycloak 24+ with HTTPS
• Jenkins LTS with admin access
• Jenkins accessible at a fixed URL

Step 0 — Install Jenkins on Windows using the MSI

If you already have Jenkins running, skip to Step 1.

Running Jenkins as a Docker container is the fastest path — pull the image, map port 8080, done. But if you need Jenkins installed natively on Windows (for example, to run agents or jobs that depend on Windows-specific tooling), the MSI installer has a few steps that trip people up. This section covers that path.

1. Go to jenkins.io/download and download the Windows installer (.msi) for the LTS release.
2. Run the downloaded .msi file. The installer launches a setup wizard.

Jenkins MSI installer welcome screen on Windows showing the setup wizard start page

Screenshot coming soon

3. On the Service Logon Credentials screen, the default is to run the Jenkins service as Local System. For most local/dev setups this is fine. If your Jenkins needs to access network resources (a shared drive, a domain-joined SCM server) under a specific account, choose a custom domain/user account instead — Local System has no network identity beyond the machine account.

Jenkins MSI installer Service Logon Credentials screen with Local System account selected by default

Screenshot coming soon

4. On the Port screen, the default is 8080. Change it here if something else on your machine already listens on 8080 (a common conflict). You can also change this later by editing jenkins.xml in the install directory and restarting the service.

Jenkins MSI installer Port configuration screen with the default port 8080 field

Screenshot coming soon

5. Choose the Java installation Jenkins should use. If the installer doesn't detect a JDK, you'll need to install one first (Jenkins LTS 2.x requires Java 17 or 21) and point the installer at it.

Jenkins MSI installer Java installation selection screen

Screenshot coming soon

6. Finish the wizard. The installer registers Jenkins as a Windows service named Jenkins and starts it automatically.
7. Open http://localhost:8080 (or whichever port you chose) in a browser. Jenkins shows the Unlock Jenkins screen on first run.
8. Get the initial admin password from the file path shown on that screen — typically: C:\Program Files\Jenkins\secrets\initialAdminPassword Open it in a text editor, copy the value, and paste it into the Unlock screen.

Path varies if you chose a custom install directory during setup — use the exact path shown on your Unlock Jenkins screen.

9. On the next screens, click Install suggested plugins (the oic-auth plugin from Step 1 below isn't in this default set — you'll add it separately), then create your first admin user when prompted.

A few Windows-specific things worth knowing:

• Because Jenkins runs as a Windows service, plugin installs from Manage Jenkins → Plugins apply on the next service restart, not just a page reload — Jenkins will tell you when a restart is needed.
• To restart Jenkins without rebooting the machine: open Services (services.msc), find Jenkins, right-click → Restart. Or from an elevated PowerShell: Restart-Service Jenkins.
• JENKINS_HOME defaults to C:\Program Files\Jenkins\.jenkins unless changed during install — this is the directory referenced later in this guide's "Locked out" troubleshooting step (config.xml lives there).
• If Windows Firewall prompts you the first time Jenkins starts, allow access on private networks at minimum, or the setup screen won't load from another machine on the network.

Once Jenkins is up and you've logged into the dashboard, continue to Step 1.

Step 1 — Install the oic-auth plugin

In Jenkins:

1. Manage Jenkins → Plugins → Available plugins
2. Search for OpenID Connect Authentication Plugin (plugin ID: oic-auth)
3. Select it and click Install
4. Restart Jenkins when prompted

Jenkins Plugin Manager showing the OpenID Connect Authentication Plugin oic-auth in the Available plugins list with a checkbox selected and an Install button

Screenshot coming soon

Step 2 — Create the Keycloak confidential client

In the Keycloak admin console:

1. Clients → Create client
2. Client type: OpenID Connect
3. Client ID: jenkins
4. Click Next

Capability config:

• Client authentication: ON (confidential client)
• Standard flow: ON
• Direct access grants: OFF
• Click Next

Keycloak admin console Capability config screen for the jenkins client with Client authentication ON, Standard flow ON, and Direct access grants OFF

Screenshot coming soon

Login settings:

Replace jenkins.example.com with your actual Jenkins domain in all four fields below.

• Root URL: https://jenkins.example.com
• Valid redirect URIs: https://jenkins.example.com/securityRealm/finishLogin
• Valid post logout redirect URIs: https://jenkins.example.com/
• Web origins: https://jenkins.example.com

Keycloak admin console showing the jenkins client with Client authentication ON and Valid redirect URIs set to https://jenkins.example.com/securityRealm/finishLogin

Screenshot coming soon

2.1 — Copy the client secret

Clients → jenkins → Credentials → copy the client secret.

Keycloak admin console Credentials tab for the jenkins client showing the Client secret field and a copy button

Screenshot coming soon

Step 3 — Configure the security realm

In Jenkins:

1. Manage Jenkins → Security
2. Under Security Realm, select Login with OpenID Connect
3. Client id: jenkins
4. Client secret: (paste from Step 2.1)
5. Configuration mode: Automatic configuration (well-known)
6. Well-known configuration endpoint: https://keycloak.example.com/realms/YOUR_REALM/.well-known/openid-configuration

Replace YOUR_REALM with your realm name and keycloak.example.com with your Keycloak hostname.

7. Expand Advanced and set Override scopes to openid email profile.

Without this, login can fail or come back without the claims Jenkins needs. The oic-auth plugin doesn't always request the right scopes from the well-known config alone — setting them explicitly here ensures Keycloak returns the email and profile claims along with the base openid scope.

Jenkins security realm Advanced section showing the Override scopes field set to openid email profile

Screenshot coming soon

Click Test configuration to verify Jenkins can reach Keycloak's discovery document. A green result means Jenkins fetched the Keycloak realm metadata. A red result usually means a network or TLS issue between Jenkins and Keycloak.

Jenkins Configure Global Security page showing the OpenID Connect security realm selected with the well-known configuration endpoint field containing the Keycloak realm discovery URL and a green test result

Screenshot coming soon

Step 4 — Map user attributes

Scroll to Advanced in the security realm section. Fill in:

Field	Value
User name field name	preferred_username
Full name field name	name
Email field name	email
Groups field name	groups

Jenkins security realm Advanced section showing field mappings with preferred_username for username, name for full name, and email for email

Screenshot coming soon

Save the configuration.

Step 5 — Test the login

Open a private browser window and go to https://jenkins.example.com. Jenkins redirects to Keycloak for authentication instead of showing a local login form.

Keycloak login page displayed when accessing Jenkins in a browser

Screenshot coming soon

After login, Jenkins creates the user account and shows the main dashboard, with the Keycloak username (from the preferred_username claim mapped in Step 4) visible in the top-right menu.

Step 6 — Role-based access (optional)

By default, every authenticated user gets the same Jenkins permissions. To assign different permissions by Keycloak group, install the Role-based Authorization Strategy plugin (plugin ID: role-strategy) and configure it alongside oic-auth.

1. Install Role-based Authorization Strategy from Manage Jenkins → Plugins
2. Manage Jenkins → Security → Authorization → Role-Based Strategy
3. Manage and Assign Roles → Manage Roles → create roles and set permissions
4. Manage and Assign Roles → Assign Roles → assign Keycloak group names to roles

Jenkins Assign Roles screen under Manage and Assign Roles, showing a Global roles table with Anonymous, Authenticated Users, and Keycloak group names mapped to role checkboxes

Screenshot coming soon

The oic-auth plugin reads the groups claim from the token and registers each value as a Jenkins group. The Role Strategy plugin then maps those groups to roles. For this to work, the groups claim must be present in the token.

6.1 — Add the groups mapper in Keycloak

1. Clients → jenkins → Client scopes → jenkins-dedicated → Add mapper → By configuration
2. Select Group Membership
3. Token Claim Name: groups
4. Full group path: OFF
5. Add to ID token: ON
6. Save

Keycloak admin console showing the Group Membership mapper for the jenkins client with Token Claim Name set to groups and Full group path set to OFF

Screenshot coming soon

Troubleshooting common issues

"Invalid redirect_uri" from Keycloak after login

Jenkins sends https://jenkins.example.com/securityRealm/finishLogin as the redirect URI. If the Valid redirect URIs field on the Keycloak client doesn't match exactly, Keycloak rejects the request. Check the URI in Keycloak's error page and compare it character by character with what you entered.

403 after successful Keycloak login

If Jenkins shows a 403, the authorization strategy is blocking the user. If you're using Matrix-based security, the authenticated user or their group needs at least the Overall/Read permission. Switch temporarily to "Logged-in users can do anything" to confirm authentication works, then restore the real authorization policy.

Configuration test passes but login fails

The test button only checks that Jenkins can fetch the discovery document. It doesn't validate the client credentials. If the client secret is wrong, the token exchange at /securityRealm/finishLogin fails silently. Copy the secret again from Keycloak and save the security realm config.

If the secret is correct and login still fails (or you land back on the Keycloak login page repeatedly), check the Override scopes field under Advanced — it needs to be set to openid email profile. Without it, the scope Jenkins requests may not match what your realm expects, and the login round-trip doesn't complete.

Users can log in but their full name or email is blank

The claim names in Step 4 must match exactly what Keycloak sends. Enable Jenkins' system log (Manage Jenkins → System Log → add logger for hudson.security) and look for the raw claims during a login. The log shows each claim name — compare them to what you typed in the field mapping.

Remove the temporary logger after you're done debugging — it can log token claims, which may include sensitive identity data.

Locked out after changing the security realm

If the OIDC config breaks, Jenkins may block all access including the admin account. Stop the Jenkins service, edit $JENKINS_HOME/config.xml, set <useSecurity>false</useSecurity>, and restart. This disables security entirely so you can log in and fix the config. Re-enable security immediately after.

Production checklist

• HTTPS on both Jenkins and Keycloak
• Client secret stored in Jenkins' credentials store or passed as an environment variable, not typed into a UI form that gets exported
• preferred_username used for the username field — it maps to stable Keycloak usernames
• Authorization policy tested before disabling the local admin account
• Local admin account kept active as a fallback until SSO is confirmed stable
• Direct access grants disabled on the Keycloak client
• Jenkins restarted after plugin installation before configuring the security realm