In this post, we’ll show how to configure SSO between Jenkins and Keycloak, enabling users to log in once and access Jenkins.
· Prerequisites
· Overview
∘ What is a Single Sign-On (SSO)?
∘ Key Benefits of SSO?
∘ What is OpenID Connect
· Step-by-Step Integration
∘ Part 1: Keycloak Setup
∘ Part 2: Jenkins Setup
· Testing the SSO Flow
· Troubleshooting Common Issues
· Conclusion
· References
Prerequisites
This is the list of all the prerequisites:
- An installed Jenkins (v2.5+) and Keycloak (v26+) server
- Admin access to both Jenkins and Keycloak
- Docker / Docker compose installed (optional if you’ve already installed Jenkins and Keycloak)
- Basic knowledge of Jenkins and Keycloak
Overview
What is a Single Sign-On (SSO)?
Single Sign-On (SSO) is an authentication scheme that allows a user to log in with a single set of credentials (like a username and password) to access multiple, related, but independent software systems.
Instead of logging in separately to each application, the user authenticates once, and the system automatically grants access to all integrated services without requiring repeated logins.
Key Benefits of SSO?
- Single Authentication Point: Users log in once, typically through a central identity provider (IdP) like Keycloak, Okta, or Azure AD.
- Centralized Security Policies: Enforces strong password policies, Multi-Factor Authentication (MFA), and account lockout rules in one place (the IdP), which then applies to all connected apps.
- Improved User Experience: Users don’t need to remember multiple usernames and passwords. Reduces login friction and saves time.
- Faster De-provisioning: When an employee leaves, disabling their one central account immediately revokes their access to all integrated applications, reducing the risk of orphaned accounts.
What is OpenID Connect
OpenID Connect is an interoperable authentication protocol based on the OAuth 2.0 framework of specifications (IETF RFC 6749 and 6750). It simplifies the way to verify the identity of users based on the authentication performed by an Authorization Server and to obtain user profile information in an interoperable and REST-like manner.
OpenID Connect enables application and website developers to launch sign-in flows and receive verifiable assertions about users across Web-based, mobile, and JavaScript clients. And the specification suite is extensible to support a range of optional features such as encryption of identity data, discovery of OpenID Providers, and session logout. — https://openid.net/developers/how-connect-works/
Step-by-Step Integration
The integration is a two-part process: first, we configure Keycloak to recognize Jenkins as a client, and then we configure Jenkins to use Keycloak as its authentication provider
This post uses Docker containers to run Keycloak and Jenkins instances. Here is the full content of Docker Compose:
version: '3.8'
services:
keycloak:
image: quay.io/keycloak/keycloak:26.4
environment:
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: admin
KC_DB: postgres
KC_DB_URL_HOST: postgres
KC_DB_URL_DATABASE: keycloak
KC_DB_USERNAME: keycloak
KC_DB_PASSWORD: keycloak
KC_HOSTNAME_STRICT: false
KC_HTTP_ENABLED: true
ports:
- "8080:8080"
depends_on:
- postgres
command: start-dev
postgres:
image: postgres:15
environment:
POSTGRES_DB: keycloak
POSTGRES_USER: keycloak
POSTGRES_PASSWORD: keycloak
ports:
- "5433:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
jenkins:
image: jenkins/jenkins:latest
container_name: jenkins
restart: unless-stopped
user: root
ports:
- "8000:8080"
- "50000:50000"
volumes:
- jenkins_home:/var/jenkins_home
- /var/run/docker.sock:/var/run/docker.sock
- ./jenkins_home:/var/jenkins_home
environment:
- TZ=UTC
volumes:
postgres_data:
jenkins_home:Once containers are ready:
- Keycloak: http://localhost:8080
- Jenkins: http://localhost:8000
I will use the IP address of my home lab (192.168.1.137) instead of localhost.
Part 1: Keycloak Setup
Keycloak acts as the OIDC provider. We’ll create a realm, client, group, and user for Jenkins integration.
- Log in to Keycloak Admin Console
URL: http://192.168.1.137:8080
Username:admin
Password:admin
2. Create a New Realm, name it sandbox.
3. Create a Client for Jenkins
In the new realm, navigate to Clients in the left sidebar and click Create.
Fill in the details:
- Client ID:
jenkins(or your preferred identifier) - Client Protocol:
openid-connect - Click Save
On the Access settings section, configure:
- Valid Redirect URIs:
http://your-jenkins-url/securityRealm/finishLogin - Valid post logout redirect URIs:
http://your-jenkins-url/OicLogout - Web Origins:
https://your-jenkins-url
On the Capability config, configure:
Navigate to the Credentials tab and copy the Client Secret value — we’ll need this for Jenkins configuration
4. Create Users and Groups
Navigate to Groups and create a new group, e.g., jenkins-admin
Navigate to Users, add a new user, and set their credentials.
Here is the user summary data for this lab.
5. Create Client Scopes for Groups
To include user group information in OIDC tokens (e.g., for role-based authorization in Jenkins), create a client scope.
Go to Client Scopes → Create Client Scope.
Fill in the details:
- Name:
groups - Protocol:
openid-connect - Click Save.
After creating the scope, go to the Mappers tab for this Client scope and click on the “Add mapper” button, then select “By configuration” and in the list of available mappers select “Group Membership”
This mapper ensures that when a user belongs to a group in Keycloak, that group name will appear in the JWT token (OIDC token) as a claim.
6. Assign the Client Scope to Jenkins Client
Back in the client settings jenkins, go to the Client scopes tab and add groups scope to Assigned default client scopes.
7. Verify the Token
The “Evaluate” feature in Keycloak Client Scopes is a very handy built-in tool that lets you preview and verify what your generated tokens (ID token, access token, and userinfo) will look like before you integrate them into Jenkins.
We can view the “groups” attribute in the ID token.
Keycloak is now ready. The OIDC endpoints (e.g., http://your-keycloak/realms/sandbox/.well-known/openid-configuration) will be used in Jenkins.
Part 2: Jenkins Setup
- Install the Required Plugin
Jenkins needs the OIDC plugin to connect to Keycloak.
- In Jenkins, go to Manage Jenkins > Manage Plugins.
- Go to the Available tab and search for
OpenId Connect Authentication. - Select the plugin named “OpenId Connect Authentication Plugin” and install it. Restart Jenkins if prompted.
2. Configuring OIDC in Jenkins
Now navigate to “Manage Jenkins” > “Security” to authenticate using Keycloak OpenID Connect.
Under Security Realm, select “Login with Openid Connect”
With authentication working, we now need to control what users can do in Jenkins. We’ll use the powerful Matrix-based Authorization strategy, leveraging the groups we created in Keycloak.
Don’t forget to add your own user or group with admin rights before saving, or you might lock yourself out!
Testing the SSO Flow
- Log out of Jenkins.
2. Click Sign in. You should be redirected to Keycloak’s login page.
- Enter the credentials of a user you created in Keycloak.
- After successful authentication, Keycloak will redirect you back to Jenkins, where you will be logged in.
Troubleshooting Common Issues
Conclusion
🏁 Well done !!. In this post, we explored how to integrate Jenkins Single Sign-On (SSO) with Keycloak using OpenID Connect (OIDC) — from configuring realms and clients in Keycloak, to enabling OIDC in Jenkins and verifying tokens.
Support me through GitHub Sponsors.
Thank you for reading!! See you in the next post.
