Introduction
As businesses scale their operations, centralised identity management becomes crucial to ensure security and operational efficiency. Keycloak, a powerful open-source Identity and Access Management (IAM) solution, simplifies this by offering Single Sign-On (SSO) and centralized authentication. This guide will walk you through integrating Keycloak with Grafana, GitLab, and Jenkins, streamlining user management and authentication.
In this guide, we will:
-
- Configure Keycloak as the Identity Provider (IdP).
- Set up OAuth2/OpenID Connect (OIDC) for Grafana, GitLab, and Jenkins.
- Provide detailed troubleshooting tips and insights to avoid common pitfalls.
By following this guide, you’ll have a unified authentication system, ensuring that users can access Grafana, GitLab, and Jenkins with one set of credentials.
Keycloak Overview
Keycloak is an open-source Identity and Access Management (IAM) solution that provides SSO with modern security standards such as OpenID Connect, OAuth2, and SAML. It supports various identity providers (e.g., LDAP, Active Directory) and provides a rich user interface for managing realms, users, roles and permissions.
Architecture Diagram
This diagram illustrates the integration of Keycloak as a central identity and access management system. It facilitates Single Sign-On (SSO) for various external identity providers (IDPs) and internal applications.
Components:
-
- Keycloak
- Acts as the core Identity Provider (IdP) for the architecture.
- Manages authentication, authorization, and user sessions across connected services.
- Facilitates Single Sign-On (SSO), allowing users to log in once and access multiple services seamlessly.
- External Identity Providers (IDPs)
- Keycloak integrates with external IDPs for user authentication.
- OpenID Connect (OIDC) and SAML protocols for federated identity management.
- Google and Microsoft for social and enterprise logins.
- Keycloak redirects user login requests to these external providers as configured, enabling users to authenticate with their existing credentials.
- Internal Applications
- Keycloak
-
-
- Keycloak provides SSO support for internal services.
- GitLab for source code management.
- Jenkins for continuous integration/continuous delivery (CI/CD) pipelines.
- SonarQube for static code analysis and quality monitoring.
- These applications delegate authentication to Keycloak. When users access these services, they are redirected to Keycloak for login.
-
Workflow:
-
- Authentication with External IDPs:
- A user trying to log in to any service is redirected to Keycloak.
- If configured, Keycloak can redirect the user to an external provider (e.g., Google or Microsoft) to authenticate.
- Once authenticated, the user is granted access to the requested service
- Single Sign-On (SSO):
- Keycloak generates and manages an SSO session after successful authentication.
- Users only need to log in once. All other integrated services (e.g., GitLab, Jenkins, SonarQube) can reuse the same session for access.
- Authorization:
- Authentication with External IDPs:
-
-
- Keycloak ensures proper access control by assigning roles and permissions.
- Applications fetch user roles and permissions from Keycloak to enforce fine-grained authorization.
-
Keycloak's Key Features
-
- Single Sign-On (SSO): Users log in once to access multiple services.
- Centralized Authentication: Manage authentication for various services from a central location.
- Federated Identity: Keycloak can authenticate users from LDAP, Active Directory or other identity providers.
- Role-based Access Control (RBAC): Assign users specific roles and permissions across services.
Prerequisites
Before beginning, ensure you have the following:
-
- Keycloak: Installed and running. You can deploy Keycloak using Docker, Kubernetes, or install it manually.
- Grafana: Installed and running.
- GitLab: Installed and running (either self-hosted or GitLab.com).
- Jenkins: Installed and running.
- SSL Certificates: It’s highly recommended to secure your services with SSL to ensure secure communication.
Ensure you have administrative access to each service for configuration purposes.
Part 1: Keycloak Setup
Step 1: Install and Access Keycloak
Keycloak can be deployed via Docker, Kubernetes, or manually on a server.
For Docker:
docker run -d \
-p 8080:8080 \
-e KEYCLOAK_USER=admin \
-e KEYCLOAK_PASSWORD=admin \
quay.io/keycloak/keycloak:latest
For Kubernetes, you can deploy Keycloak with Helm or a custom Kubernetes manifest. Make sure Keycloak is accessible to Grafana, GitLab, and Jenkins, either through DNS or IP.
Step 2: Create a New Realm
A Realm in Keycloak is a space where you manage users, roles, clients, and groups. Each realm is isolated, meaning users and configurations don’t overlap between realms.
-
- From the Keycloak admin console, click on the top-left dropdown and select Add Realm.
- Name the realm (e.g., DevOpsRealm) and click Create.
- Ensure you select an appropriate Display Name and Internationalization settings if your user base spans different regions.
Step 3: Add Users and Assign Roles
You can now create users and assign them roles:
-
- Navigate to Users -> Add User.
- Fill in the user details and click Save.
- After the user is created, go to the Credentials tab and set the password.
- You can also manage roles under the Role Mappings tab to define custom permissions.
Step 4: Configure Clients (Grafana, GitLab, Jenkins)
Clients in Keycloak represent the applications that will use Keycloak for authentication. For each service (Grafana, GitLab, Jenkins), we’ll create a client that uses the OIDC protocol.
-
- Grafana Client Setup:
-
-
- Go to Clients -> Create.
- Set the Client ID to grafana, and choose OpenID Connect as the protocol.
- Set the Root URL to http://<grafana-host>, and the Redirect URIs to http://<grafana-host>/login/generic_oauth.
- Enable the following flows: Standard Flow, Implicit Flow (if needed), and Direct Access Grants.
- Save the client and navigate to the Credentials tab to copy the generated Client Secret.
-
-
- GitLab Client Setup:
- Go to Clients -> Create.
- Set the Client ID to gitlab and choose OpenID Connect.
- Set the Redirect URI to http://<gitlab-host>/users/auth/openid_connect/callback.
- Enable Standard Flow and Implicit Flow if GitLab requires it.
- Save the client and copy the Client Secret from the Credentials tab.
- Jenkins Client Setup:
- GitLab Client Setup:
-
-
- Add a new client for Jenkins, following the same steps as above.
- Set the Redirect URI to http://<jenkins-host>/securityRealm/finishLogin.
- Export the client-json file from client actions to configure in the next steps.
- Export the json file as shown below.
-
Part 2: Integrating Keycloak with Grafana
Step 1: Configure Grafana for OAuth2
Grafana supports OAuth2 natively, and Keycloak uses OpenID Connect as the protocol for OAuth2.
-
- Grafana’s Configuration: Locate the grafana.ini file (or environment variables for a Docker container) and configure OAuth2 settings:
[auth.generic_oauth]
enabled = true
client_id = grafana
client_secret = <Grafana_Client_Secret>
auth_url = http://<keycloak-host>/realms/<Your_Realm>/protocol/openid-connect/auth token_url = http://<keycloak-host>/realms/<Your_Realm>/protocol/openid-connect/token
api_url = http://<keycloak-host>/realms/<Your_Realm>/protocol/openid-connect/userinfo scopes = openid profile email
-
- Restart Grafana: After updating the configuration, restart Grafana:
For Manual:
systemctl restart grafana-server
For Docker:
docker restart <grafana-container-name>
Part 3: Integrating Keycloak with GitLab
GitLab supports OIDC natively for SSO, making it straightforward to integrate with Keycloak.
Step 1: Configure GitLab for OpenID Connect
- GitLab Configuration: Open GitLab’s gitlab.rb configuration file and enable OIDC:
gitlab_rails[‘omniauth_enabled’] = true
gitlab_rails[‘omniauth_providers’] = [
{
name: “openid_connect”,
label: “Keycloak”,
args: {
name: “openid_connect”,
scope: [“openid”, “profile”, “email”],
response_type: “code”,
issuer: “http://<keycloak-host>/realms/<Your_Realm>”,
discovery: true,
uid_field: “preferred_username”,
client_auth_method: “basic”,
client_options: {
identifier: “<GitLab_Client_ID>”,
secret: “<GitLab_Client_Secret>”,
redirect_uri: “http://<gitlab-host>/users/auth/openid_connect/callback”
}
}
}
]
- Reconfigure GitLab: After editing gitlab.rb, run:
For Manual:
sudo gitlab-ctl reconfigure
For Docker:
docker restart <gitlab-container-name>
Step 2: Test the Integration
Log out of GitLab, then visit the login page. You should see a “Sign in with Keycloak” option. Clicking it will redirect you to Keycloak for authentication, and once logged in, you’ll be redirected back to GitLab.
Troubleshooting GitLab Integration:
-
- Invalid UID Field: If authentication succeeds but user data is incorrect, check that uid_field in the gitlab.rb configuration is set to preferred_username.
- Client Secret Mismatch: Ensure the client_secret in GitLab matches the secret in Keycloak’s client settings.
-
- Invalid Token Response: If you get errors related to invalid tokens, ensure your GitLab instance is reachable from Keycloak and that your OAuth2 flow is configured correctly in Keycloak.
Part 4: Integrating Keycloak with Jenkins
Step 1: Install and Configure Keycloak Plugin
-
- Install the Plugin: In Jenkins, go to Manage Jenkins -> Manage Plugins, search for the Keycloak OpenID Connect Plugin, and install it.
- Configure Keycloak in Jenkins:
- Go to Manage Jenkins -> Configure Security.
- Under Security Realm, choose Keycloak Authentication.
- Upload the client-json file which is exported from the client configuration step.
- Upload the json file in keycloak json field.
-
- Save and Test the Configuration: Log out of Jenkins and test the login with Keycloak.
Troubleshooting Jenkins Integration:
-
- Redirect URI Mismatch: Double-check that the redirect URI set in Keycloak matches Jenkins’ redirect path (/securityRealm/finishLogin).
- Access Denied Errors: Ensure users have been assigned roles in Keycloak that map to appropriate Jenkins permissions.
- Plugin Issues: If the plugin behaves unexpectedly, verify you have the latest version installed and that Jenkins’ logs provide more detailed errors.
Note: All the 3 apps are now integrated with keycloak. So if you login to any service with keycloak, automatically you’ll be logged into all the 3 apps.
Conclusion
Integrating Keycloak with Grafana, GitLab, and Jenkins provides a unified and secure authentication system. This setup reduces complexity, enhances security, and improves user experience by enabling SSO across your DevOps tools.
Simplify authentication and enhance security across your systems. Get started today!
