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.
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.
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.
