django-kc-auth 0.0.1

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

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 backend to your authentication backends:

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

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/*",
]

License

MIT License