Metadata-Version: 2.4
Name: django-kc-auth
Version: 0.0.1
Summary: A comprehensive Django package for Keycloak authentication integration, providing seamless SSO, session management, and user synchronization between Django and Keycloak.
Author-email: Juraj Perić <juraj.peric@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/perkeje/django-kc-auth
Project-URL: Issues, https://github.com/perkeje/django-kc-auth/issues
Keywords: django,keycloak,authentication,sso,session-management
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: Django>=5.0.1
Requires-Dist: djangorestframework>=3.15.2
Requires-Dist: python-keycloak>=4.5.0
Requires-Dist: jwt>=1.3.1

# 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

```shell 
pip install django-kc-auth
```

## Quick Setup

1. **Add to `INSTALLED_APPS` in ``settings.py``**:

```python
INSTALLED_APPS = [
    # ...
    'django_kc_auth',
    # ...
]
```
2. **Configure Keycloak settings in your Django ``settings.py``**:

```python
# 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**:

```shell
python manage.py migrate
```
4. **Include URLs in your project's `urls.py`**:

```python
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`:

```python
# 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:**

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

## Error Messages

**Customize error messages displayed to users:**

```python
# 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:

```python
AUTHENTICATION_BACKENDS = [
    "django_kc_auth.backends.KeycloakBackend",
    # ... other backends
]
```
2. Configure silent login settings (optional):

```python
# 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
