defguard
Search
K

Django

This article aims to show the basic integration of authenticating users through Defguard via OpenID Connect. So you can have a solid start to adjust it for your own use case.

The Setup

Domain

This guide assumes both Defguard and Django are running on localhost.

Defguard

We will run Defguard instance on default port 8000.
You can learn how to launch your Defguard instance in the following article: Deploying your instance

Configuration

For our example to work on localhost we will need to change the following variables in Defguard:
Variable
Value
DEFGUARD_URL
http://localhost:8000
DEFGUARD_COOKIE_DOMAIN
localhost
DEFGUARD_COOKIE_INSECURE
true
Because we use localhost domain we need to set cookies to insecure, DON'T do this in a production environment.
Next, we need to configure the OpenID module to use RSA key instead of the default HMAC, this is due to Authlib being incompatible with HMAC.
Generate RSA key with the following command:
openssl genpkey -out rsakey.pem -algorithm RSA -pkeyopt rsa_keygen_bits:2048
Now we need to set DEFGUARD_OPENID_KEY variable to path pointing to that rsakey.pem file.
When starting Defguard now you should be able to see the following info log :
INFO defguard: Using RSA OpenID signing key

Django

This section will explain how to setup a fresh Django example project.
We will use poetry as a package manager but pip will also work fine.

Project

Setup a new project with poetry, we will name it django-project.
poetry new django-project && cd ./django-project
Delete the generated django_project directory, we don't need it.
rm -rd ./django_project/

Packages

Install the following Python packages:
  • django
  • django-jazzmin
  • Authlib
  • requests
poetry add django django-jazzmin Authlib requests

Django

Now we will make Django project and add oauth app.
poetry run django-admin startproject example .
poetry run ./manage.py startapp oauth
With this, we should have a directory structure close to this:
├── example
│   ├── asgi.py
│   ├── __init__.py
│   ├── __pycache__
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── manage.py
├── oauth
│   ├── admin.py
│   ├── apps.py
│   ├── __init__.py
│   ├── migrations
│   ├── models.py
│   ├── tests.py
│   └── views.py
├── poetry.lock
├── pyproject.toml
└── README.md

Register OpenID App

We need to register our Django application as an OpenID client in Defguard.
To do that, navigate to OpenID panel and add new client as shown below.
Redirect URL should point to http://localhost:9000/oauth/redirect
Scopes should include at least OpenID, Profile, and Email.

Authentication app setup

Register app in Django

We will use the created oauth Django app to handle our authentication.
Register oauth app in settings.py file.
INSTALLED_APPS = [
# ...rest of your apps
'oauth.apps.OauthConfig',
]

Views

Modify oauth/views.py file.
from authlib.integrations.django_client import OAuth
from os import getenv
from django.contrib import auth
from django.contrib.auth.models import User
from django.shortcuts import redirect
oauth = OAuth()
defguard = oauth.register(
name="defguard",
client_id=getenv("DEFGUARD_CLIENT_ID"),
client_secret=getenv("DEFGUARD_CLIENT_SECRET"),
access_token_url=getenv("DEFGUARD_ACCESS_TOKEN_URL", "http://localhost:8000/api/v1/oauth/token"),
access_token_params=None,
authorize_url=getenv("DEFGUARD_AUTHORIZE_URL", "http://localhost:8000/api/v1/oauth/authorize"),
api_base_url=getenv("DEFGUARD_API_BASE_URL", "http://localhost:8000/api/v1/oauth/userinfo"),
client_kwargs={"scope": getenv("DEFGUARD_SCOPE", "openid email profile")},
server_metadata_url=getenv("DEFGUARD_METADATA_URL", "http://localhost:8000/.well-known/openid-configuration"),
)
REDIRECT_URL = getenv("DEFGUARD_REDIRECT_URL")
def defguard_login(request):
redirect_uri = request.build_absolute_uri(REDIRECT_URL)
return oauth.defguard.authorize_redirect(request, redirect_uri)
def defguard_authorize(request):
token = oauth.defguard.authorize_access_token(request)
resp = oauth.defguard.get("userinfo", token=token)
resp.raise_for_status()
profile = resp.json()
user = None
user_exists = User.objects.filter(username=profile["sub"]).exists()
if not user_exists:
user = User(
is_active=True,
is_staff=True,
is_superuser=True,
username=profile["sub"],
email=profile["email"],
first_name=profile["given_name"],
last_name=profile["family_name"],
)
user.save()
else:
user = User.objects.get(username=profile["sub"])
auth.login(request, user)
return redirect("/admin")
With the provided example, you will need to fill out only DEFGUARD_CLIENT_ID and DEFGUARD_CLIENT_SECRET.
Either provide them as environment variables or modify the views file and pass them as strings to oauth register function.
Both Client ID and Secret can be found on OpenID apps page in Defguard, click our Django app row on the list and you will be able to copy needed values from the opened modal.

URLS

We will need to add our views to oauth/urls.py.
from django.urls import path
from oauth.views import defguard_authorize, defguard_login
urlpatterns = [
path("defguard-login", defguard_login),
path("redirect", defguard_authorize),
]
Modify example/urls.py file, so it includes oauth app urls:
from django.contrib import admin
from django.urls import path, include
from django.contrib.auth.models import Group
admin.site.unregister(Group)
urlpatterns = [
path('admin/', admin.site.urls),
path('oauth/', include('oauth.urls')),
]

Custom admin login template

With use of Jazzmin admin theme we will modify login template and add an additional button to login with Defguard.

Register Jazzmin app

Modify example/settings.py
INSTALLED_APPS = [
'jazzmin',
'django.contrib.admin',
# rest of the apps
]
# rest of config
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [BASE_DIR / "templates"],
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
'django.template.context_processors.debug',
'django.template.context_processors.request',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
],
},
},
]
jazzmin app needs to be registered before django.contrib.admin

Add template file

Make templates/admin/auth/login.html file:
{% extends "registration/base.html" %}
{% load i18n jazzmin %}
{% get_jazzmin_settings request as jazzmin_settings %}
{% get_jazzmin_ui_tweaks as jazzmin_ui %}
{% block content %}
<p class="login-box-msg">{{ jazzmin_settings.welcome_sign }}</p>
<form action="{{ app_path }}" method="post">
{% csrf_token %}
{% if user.is_authenticated %}
<p class="errornote">
<div class="callout callout-danger">
<p>
{% blocktrans trimmed %}
You are authenticated as {{ username }}, but are not authorized to
access this page. Would you like to login to a different account?
{% endblocktrans %}
</p>
</div>
</p>
{% endif %}
{% if form.errors %}
{% if form.username.errors %}
<div class="callout callout-danger">
<p>{{ form.username.label }}: {{ form.username.errors|join:', ' }}</p>
</div>
{% endif %}
{% if form.password.errors %}
<div class="callout callout-danger">
<p>{{ form.password.label }}: {{ form.password.errors|join:', ' }}</p>
</div>
{% endif %}
{% if form.non_field_errors %}
<div class="callout callout-danger">
{% for error in form.non_field_errors %}
<p>{{ error }}</p>
{% endfor %}
</div>
{% endif %}
{% endif %}
<div class="input-group mb-3">
<input type="text" name="username" class="form-control" placeholder="{{ form.username.label }}" required>
<div class="input-group-append">
<div class="input-group-text">
<span class="fas fa-user"></span>
</div>
</div>
</div>
<div class="input-group mb-3">
<input type="password" name="password" class="form-control" placeholder="{{ form.password.label }}" required>
<div class="input-group-append">
<div class="input-group-text">
<span class="fas fa-lock"></span>
</div>
</div>
</div>
{% url 'admin_password_reset' as password_reset_url %}
{% if password_reset_url %}
<div class="mb-3">
<div class="password-reset-link" style="text-align: center;">
<a href="{{ password_reset_url }}">
{% trans 'Forgotten your password or username?' %}
</a>
</div>
</div>
{% endif %}
<div class="row">
<div class="col-12">
<button type="submit" class="btn {{ jazzmin_ui.button_classes.primary }} btn-block">
{% trans "Log in" %}
</button>
</div>
</div>
</form>
<div class="row" style="padding-top: 8px">
<div class="col-12">
<button class="btn {{ jazzmin_ui.button_classes.secondary }} btn-block"
onclick="window.location.href = '/oauth/defguard-login'">
Login with Defguard
</button>
</div>
</div>
{% endblock %}

Register login route

Modify example/urls.py
from django.contrib import admin
from django.urls import path, include
from django.contrib.auth.models import User, Group
from django.contrib.auth.views import LoginView
admin.site.unregister(Group)
urlpatterns = [
path('admin/login/', LoginView.as_view(template_name="admin/auth/login.html"), name="admin_login"),
path('admin/', admin.site.urls),
path('oauth/', include('oauth.urls')),
]

Conclusion

Now we need to start our Django server.
If you started a fresh project don't forget to make migrations!
poetry run ./manage.py migrate
poetry run ./manage.py runserver 0.0.0.0:9000
After accessing http://localhost:9000/admin we should see our custom login page
Button "Login with Defguard" should redirect us to our Defguard instance. Depending on if Defguard session is active or not we should be able to see app authorization page or login page.
When we authorize Django App to our Defguard account we are redirected back to our Django admin and logged in with a user from Defguard.