django-epfl-entra-id

Custom Microsoft Entra ID Authentication Backend for Django.

Requirements

• Python 3.6 or later
• Django 1.11, 2.2, 3.2, 4.2 or 5.2

Installation

pip install django-epfl-entra-id

Documentation

Settings

Add mozilla_django_oidc to INSTALLED_APPS:

INSTALLED_APPS = [
  ...
  "django.contrib.auth",
  "mozilla_django_oidc",  # Load after auth
  ...
]

Add django_epfl_entra_id authentication backend:

AUTHENTICATION_BACKENDS = ("django_epfl_entra_id.auth.EPFLOIDCAB",)

Register your application in the App Portal and add the OIDC configuration:

TENANT_ID = os.environ["TENANT_ID"]

OIDC_RP_CLIENT_ID = os.environ["OIDC_RP_CLIENT_ID"]
OIDC_RP_CLIENT_SECRET = os.environ["OIDC_RP_CLIENT_SECRET"]

AUTH_DOMAIN = f"https://login.microsoftonline.com/{TENANT_ID}"
OIDC_OP_AUTHORIZATION_ENDPOINT = f"{AUTH_DOMAIN}/oauth2/v2.0/authorize"
OIDC_OP_TOKEN_ENDPOINT = f"{AUTH_DOMAIN}/oauth2/v2.0/token"
OIDC_OP_JWKS_ENDPOINT = f"{AUTH_DOMAIN}/discovery/v2.0/keys"
OIDC_OP_USER_ENDPOINT = "https://graph.microsoft.com/oidc/userinfo"
OIDC_RP_SIGN_ALGO = "RS256"

LOGIN_URL = "/auth/authenticate"
LOGIN_REDIRECT_URL = "/"
LOGOUT_REDIRECT_URL = "/"

Routing

Edit your urls.py and add the following:

urlpatterns = [
  ...
  path("", include("django_epfl_entra_id.urls")),
  path("auth/", include("mozilla_django_oidc.urls")),
  ...
]

Example template:

{% if user.is_authenticated %}
  <p>Current user: {{ user.username }}</p>
  <form action="{% url 'oidc_logout' %}" method="post">
    {% csrf_token %}
    <input type="submit" value="logout">
  </form>
{% else %}
  <a href="{% url 'oidc_authentication_init' %}?next={{ request.path }}">
    Login
  </a>
{% endif %}

Optional configuration

AUTH_PROFILE_MODULE = "userprofile.UserProfile"

Restrict Authentication by Rights (Authorizations)

By default, any user with a valid EPFL Entra ID account can authenticate. If you want to restrict access only to users possessing specific application rights (claims injected by the EPFL portal), follow these steps:

Configure your app's settings.py

You need to enable the strict rights verification and define where Django should redirect unauthorized users (e.g., to a 403 Forbidden page). Add the following to your settings:

  # Enable strict rights verification. 
  # (You can dynamically load this from your .env file if preferred)
  OIDC_REQUIRE_AUTHORIZATIONS = True
  
  # Redirect unauthorized users to the dedicated forbidden view
  LOGIN_REDIRECT_URL_FAILURE = "/forbidden"

Note: Ensure that your application rights are properly configured in the EPFL deployment portal (app-portal). Entra ID relies on this configuration to inject the authorizations claim into the user's token.

Logging

Enable these loggers in settings to see logging messages to help you debug:

LOGGING = {
  ...
  "loggers": {
      "mozilla_django_oidc": {
        "handlers": ["console"], 
        "level": "DEBUG"
      },
      "django_epfl_entra_id": {
        "handlers": ["console"],
        "level": "DEBUG",
      },
  ...
}

Make sure to use the appropriate handler for your app.