django-kc-auth 0.0.6

A comprehensive Django package for Keycloak authentication integration, providing seamless SSO, session management, and user synchronization between Django and Keycloak.

Django Keycloak Authentication (django-kc-auth)

A Django package for seamless integration with Keycloak authentication services.

Overview

Django Keycloak Authentication provides a complete solution for integrating Keycloak identity and access management with Django applications. This package handles user authentication, session management, and device tracking while providing customizable URLs and error messages.

Requirements

• Python 3.10+
• Django 5.0.1+
• A running Keycloak server with a configured realm and client

Installation

pip install django-kc-auth

Quick Setup

1. Add to INSTALLED_APPS in settings.py:

INSTALLED_APPS = [
    # ...
    'django_kc_auth',
    # ...
]

2. Configure Keycloak settings in your Django settings.py:

# Required Keycloak settings
KC_SERVER_URL = 'https://your-keycloak-server/auth'
KC_REALM = 'your-realm'
KC_CLIENT_ID = 'your-client-id'
KC_CLIENT_SECRET = 'your-client-secret'
# KC_VERIFYING_KEY is set programmatically during app initialization

3. Run migrations:

python manage.py migrate

4. Include URLs in your project's urls.py:

from django.urls import include, path

urlpatterns = [
    # ...
    path("kc/", include("django_kc_auth.urls")),
    # ...
]

URL Configuration

The package provides the following default URL paths:

Default Path	View	URL Name
/login/	LoginView	kc_auth_login
/callback/	CallbackView	kc_auth_callback
/logout/	LogoutView	kc_auth_logout
/remote-logout/	RemoteLogoutView	kc_auth_remote-logout
/logout-listener/	LogoutListenerView	kc_auth_logout-listener
/devices/	devices	kc_auth_devices
/api/devices/	DevicesAPIView	kc_auth_api_devices

Backend

Add this backend to your AUTHENTICATION_BACKENDS. You can also use your own adaptaion. Be sure to check how it is implemented here to override it.

AUTHENTICATION_BACKENDS = [
    "django_kc_auth.backends.KeycloakBackend",
    # ... other backends
]

Also set default groups in settings if using default backend.

KC_ROLES = [
    "employees",
    "admins",
    # ...
]

Customization Options

URL Paths

You can customize URL paths in your settings.py:

# URL path customization
KC_LOGIN_URL = "custom-login/"
KC_CALLBACK_URL = "custom-callback/"
KC_LOGOUT_URL = "custom-logout/"
KC_REMOTE_LOGOUT_URL = "custom-remote-logout/"
KC_LOGOUT_LISTENER_URL = "custom-logout-listener/"
KC_DEVICES_URL = "custom-devices/"
KC_DEVICES_API_URL = "custom-api/devices/"

Redirection Settings

Configure where users are redirected after login/logout:

# Redirection settings
KC_SUCCESSFUL_LOGIN_REDIRECT = "dashboard"  # Default: "home"
KC_LOGOUT_REDIRECT = "landing-page"         # Default: "home"

Error Messages

Customize error messages displayed to users:

# Custom error messages
KC_ERROR_MESSAGES = {
    "redirect_error": "There was a problem with the authentication service. Please try again.",
    "login_failed": "Login failed. Please check your credentials and try again.",
    "user_not_found": "User account not found.",
    "remote_logout_failed": "Failed to log out from remote session.",
}

Silent Authentication

Silent authentication allows automatic login for users with active Keycloak sessions in other applications.

To enable this feature:

1. Add the Keycloak middleware to your middlewares:

MIDDLEWARE = [
    #... previous, needs to go after:
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django_kc_auth.middleware.AutoKeycloakLoginMiddleware",
    # ...other
]

2. Configure silent login settings (optional):

# Silent login configuration
KC_SILENT_LOGIN_ALLOWED_ATTEMPTS = 5  # Maximum number of silent login attempts
KC_SILENT_LOGIN_TIMEOUT_SECONDS = 3   # Timeout between silent login attempts
KC_SILENT_LOGOUT_IGNORED_ROUTES = [   # Routes to ignore for silent login
    "/api/health-check/",
    "/static/*",
]

3. Soft logout If you are using soft logout(logout only from django app but not from keycloak), you should set request.session["soft_logout"] = True after logging out.

class SoftLogoutView(LoginRequiredMixin, View):
    def post(self, request):
        logout(request)
        request.session["soft_logout"] = True
        return redirect("home")

Devices

You can fetch devices and applications attached to current session with devices. There are API call and template return options. To use template option you need to put your devices.html template inside your root TEMPLATE directory.

Post logout

You can use your custom post logout logic catching the signal.
Example:

from django_kc_auth.signals import post_keycloak_login
from django.dispatch import receiver

@receiver(post_keycloak_login)
def handle_post_login(sender, request, user, access_token, **kwargs):
    # Your custom post-login logic here
    user.profile.last_login_source = 'keycloak'
    user.profile.save()
    
    # You can also perform other actions like:
    # - Update user metadata
    # - Sync user permissions from Keycloak roles
    # - Record login analytics
    # - Set up user-specific session data

License

MIT License