[Unofficial] Enable Keycloak OAuth2 Login in Kiwi TCMS OSS Using social-auth-app-django

If you’re running the open-source version of Kiwi TCMS, you might have noticed that advanced authentication options like OAuth2 and LDAP are only available in the Enterprise Edition. According to Kiwi TCMS Features, the OSS edition officially supports only basic username/password login.

However, if you’re working on an internal deployment, a testing environment, or just want to experiment, it’s entirely possible to unofficially enable Keycloak login using open-source tools like social-auth-app-django.

In this guide, I’ll show you how to integrate Keycloak OAuth2 authentication into Kiwi TCMS OSS without touching any proprietary code, just standard Django configuration.

Disclaimer

This post demonstrates an unofficial customization of Kiwi TCMS OSS. It is:

• Not endorsed or supported by the Kiwi TCMS team
• Not intended to bypass the Enterprise Edition
• Intended for learning, development, and internal use only

For production-grade SSO, please consider Kiwi TCMS Enterprise.

Authentication Feature Comparison

Note: This guide is unofficial and not supported by the Kiwi TCMS maintainers. Use it at your own risk for internal/non-production use only.

What You’ll Need

• A running Kiwi TCMS OSS instance
• A Keycloak realm and client configured
• Access to your Kiwi TCMS codebase and settings
• Basic familiarity with Django

1. Install Required Package

Install social-auth-app-django via pip:

pip install social-auth-app-django

Or add it to your requirements/base.txt:

social-auth-app-django

Then restart your container or Django server to apply the changes.

2. Update Django Settings

Open tcms/settings/common.py and make the following changes.

Add the Keycloak backend

AUTHENTICATION_BACKENDS = [
    'social_core.backends.keycloak.KeycloakOAuth2',
    'django.contrib.auth.backends.ModelBackend',
    'guardian.backends.ObjectPermissionBackend',
]

Register the app and middleware

INSTALLED_APPS += ['social_django']

MIDDLEWARE += ['social_django.middleware.SocialAuthExceptionMiddleware']

Add Keycloak environment config

SOCIAL_AUTH_KEYCLOAK_KEY = os.environ.get("SOCIAL_AUTH_KEYCLOAK_KEY")
SOCIAL_AUTH_KEYCLOAK_SECRET = os.environ.get("SOCIAL_AUTH_KEYCLOAK_SECRET")
SOCIAL_AUTH_KEYCLOAK_REALM = os.environ.get("SOCIAL_AUTH_KEYCLOAK_REALM")
SOCIAL_AUTH_KEYCLOAK_AUTHORIZATION_URL = os.environ.get("SOCIAL_AUTH_KEYCLOAK_AUTHORIZATION_URL")
SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL = os.environ.get("SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL")
SOCIAL_AUTH_KEYCLOAK_USERINFO_URL = os.environ.get("SOCIAL_AUTH_KEYCLOAK_USERINFO_URL")
SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY = os.environ.get("SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY")

3. Modify the Login Page

In tcms/templates/registration/login.html, add the following inside the {% block custom_login %} block:

<div class="form-group">
  <div class="col-sm-offset-2 col-sm-10">
    <a href="{% url 'social:begin' 'keycloak' %}" class="btn btn-outline-dark btn-lg btn-block mt-3">
      <i class="fa fa-key"></i> Login with Keycloak
    </a>
  </div>
</div>

This will render a Login with Keycloak button below the default login form.

4. Add Social Auth Routes

In tcms/urls.py, register the social-auth routes:

from django.urls import re_path, include

urlpatterns.append(
    re_path(r"^", include("social_django.urls", namespace="social"))
)

This enables the OAuth2 login flow and callback URLs.

5. Define Environment Variables

Set these variables in your container or system environment:

SOCIAL_AUTH_KEYCLOAK_KEY=kiwi-tcms-client
SOCIAL_AUTH_KEYCLOAK_SECRET=your-secret
SOCIAL_AUTH_KEYCLOAK_REALM=your-realm
SOCIAL_AUTH_KEYCLOAK_AUTHORIZATION_URL=https://your-keycloak-domain/realms/your-realm/protocol/openid-connect/auth
SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL=https://your-keycloak-domain/realms/your-realm/protocol/openid-connect/token
SOCIAL_AUTH_KEYCLOAK_USERINFO_URL=https://your-keycloak-domain/realms/your-realm/protocol/openid-connect/userinfo
SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"

Replace the values with your actual Keycloak client and realm details.

What Happens After

Once configured:

• The login page will show a Login with Keycloak button.
• Clicking it redirects the user to Keycloak.
• On success, the user is authenticated in Kiwi TCMS and redirected back.

This coexists with the existing username/password login.

Use Case

This is great for:

• Labs, demos, or CI environments
• Internal teams using Keycloak for other tools
• Understanding how Kiwi TCMS integrates with Django authentication