184 lines
4.1 KiB
Markdown
Executable File
184 lines
4.1 KiB
Markdown
Executable File
# HopID Client for Django
|
|
|
|
**django-hopid** is a lightweight Django library that simplifies OpenID Connect (OIDC) authentication with an authorization server powered by `django-oauth-toolkit`. It offers decorators, utility functions, URLs, and template tags to streamline secure login integration.
|
|
|
|
---
|
|
|
|
## 📚 Table of Contents
|
|
|
|
* [✅ Features](#✅-features)
|
|
* [🛠️ Installation](#🛠️-installation)
|
|
* [🚀 Quick Start](#🚀-quick-start)
|
|
|
|
* [1. Configure settings](#1-configure-settings)
|
|
* [2. Include URLs](#2-include-urls)
|
|
* [3. Use the callback decorator](#3-use-the-callback-decorator)
|
|
* [4. Use the login button tag](#4-use-the-login-button-tag)
|
|
* [⚙️ Advanced Usage](#⚙️-advanced-usage)
|
|
|
|
* [Custom callback response handling](#custom-callback-response-handling)
|
|
* [Use login URL in views](#use-login-url-in-views)
|
|
* [Logout integration](#logout-integration)
|
|
* [📄 License](#📄-license)
|
|
|
|
---
|
|
|
|
## ✅ Features
|
|
|
|
* 🧷 OpenID Connect Authorization Code flow with PKCE and nonce support
|
|
* 🔐 Secure token exchange and ID token verification (including issuer, nonce, and access token hash checks)
|
|
* 🤝 Seamless user login or creation using the access token
|
|
* 🌈 Template tag for styled login button
|
|
* ⚖️ Built-in URL routes for callback and logout
|
|
* ✨ Minimal configuration, no third-party dependencies
|
|
|
|
---
|
|
|
|
## 🛠️ Installation
|
|
|
|
```bash
|
|
pip install django-hopid
|
|
```
|
|
|
|
Add to `INSTALLED_APPS` (for templates):
|
|
|
|
```python
|
|
INSTALLED_APPS = [
|
|
...,
|
|
'django_hopid',
|
|
]
|
|
```
|
|
|
|
Ensure `request` is in template context:
|
|
|
|
```python
|
|
TEMPLATES = [
|
|
{
|
|
'OPTIONS': {
|
|
'context_processors': [
|
|
...,
|
|
'django.template.context_processors.request',
|
|
],
|
|
},
|
|
},
|
|
]
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### 1. Configure settings
|
|
|
|
Add the following to your `settings.py`:
|
|
|
|
```python
|
|
HOPID_URL = "https://auth.example.com"
|
|
HOPID_CLIENT_ID = "your-client-id"
|
|
HOPID_CLIENT_SECRET = "your-client-secret"
|
|
HOPID_CLIENT_URI = "https://yourapp.example.com"
|
|
```
|
|
|
|
### 2. Include URLs
|
|
|
|
In your app's `urls.py`, include HopID routes:
|
|
|
|
```python
|
|
from django.urls import path, include
|
|
|
|
urlpatterns = [
|
|
path("auth/", include("django_hopid.urls")),
|
|
]
|
|
```
|
|
|
|
This provides:
|
|
|
|
* `/auth/callback/` for OIDC callback
|
|
* `/auth/logout/` for logout
|
|
|
|
### 3. Use the callback decorator
|
|
|
|
Create your callback view:
|
|
|
|
```python
|
|
from django.shortcuts import render
|
|
from django_hopid.decorators import hopid_callback
|
|
|
|
@hopid_callback()
|
|
def hopid_callback_view(request, *args, **kwargs):
|
|
user = kwargs.get("user")
|
|
return render(request, "home.html", {"user": user})
|
|
```
|
|
|
|
### 4. Use the login button tag
|
|
|
|
In any template:
|
|
|
|
```django
|
|
{% load hopid_tags %}
|
|
{% hopid_login_button %}
|
|
```
|
|
|
|
This renders a styled login button based on your template:
|
|
|
|
```html
|
|
<a href="https://auth.example.com/o/authorize/?..." class="hopid-login-button">
|
|
Login with HopID
|
|
</a>
|
|
```
|
|
|
|
---
|
|
|
|
## ⚙️ Advanced Usage
|
|
|
|
### Custom callback response handling
|
|
|
|
Pass a custom `response=` to the decorator to override error handling:
|
|
|
|
```python
|
|
@hopid_callback(response=my_error_view)
|
|
def hopid_callback_view(request, user=None, error=None):
|
|
if error:
|
|
return render(request, "error.html", {"error": error})
|
|
return render(request, "home.html", {"user": user})
|
|
```
|
|
|
|
### Use login URL in views
|
|
|
|
If you want to build your own login redirect view:
|
|
|
|
```python
|
|
from django.shortcuts import redirect
|
|
from django_hopid.utils import get_hopid_login_url
|
|
|
|
def login_view(request):
|
|
return redirect(get_hopid_login_url(request))
|
|
```
|
|
|
|
### Logout integration
|
|
|
|
Logout is handled via:
|
|
|
|
```python
|
|
from django.contrib.auth import logout as django_logout
|
|
from django.shortcuts import redirect
|
|
from django_hopid.utils import get_hopid_logout_url
|
|
|
|
def logout_view(request):
|
|
django_logout(request)
|
|
return redirect(get_hopid_logout_url(request))
|
|
```
|
|
|
|
Or use the built-in route `/auth/logout/`.
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions are welcome! Open issues or pull requests on [Git](https://git.hopsenn.com/hopsenn/django-hopid). |