djangosaml2

library1.12.0pypypiunverified

djangosaml2 is a Python library that integrates `pysaml2` into Django applications, enabling SAML 2.0 based Single Sign-On (SSO). The current stable version is 1.12.0. It receives regular updates to support new Django and Python versions, often aligning with Django's release cycle.

web-framework auth-security

pip install djangosaml2

github ↗package ↗

INSTALL

IMPORT

SIG · DJANGOSAML2

djangosaml2

web-frameworkpythonv1.12.0

Install

5.9s avg

Import

—

Disk

95MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.12.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 94.3MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 5.9s · import 0.000s · 95MB

95MB installed

● package 95MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Saml2Backend

✓ from djangosaml2.backends import Saml2Backend

✗ from djangosaml2.backends import Saml2Backend

This quickstart outlines the essential `settings.py` and `urls.py` configurations for `djangosaml2`. It involves adding the app and authentication backend, defining `LOGIN_URL`, and setting up the `SAML_CONFIG` dictionary which holds all PySAML2 related configurations, including SP entity ID, endpoints, attribute mappings, and IdP metadata. Ensure `xmlsec1` is installed at the OS level and paths to certificates are correct.

# settings.py import os INSTALLED_APPS = [ # ... other Django apps 'djangosaml2', ] AUTHENTICATION_BACKENDS = [ 'django.contrib.auth.backends.ModelBackend', # Keep default for admin 'djangosaml2.backends.Saml2Backend', ] LOGIN_URL = '/saml2/login/' SESSION_EXPIRE_AT_BROWSER_CLOSE = True # Recommended for SAML BASEDIR = os.path.dirname(os.path.abspath(__file__)) SAML_CONFIG = { 'xmlsec_binary': '/usr/bin/xmlsec1', # Adjust path if necessary 'entityid': 'http://localhost:8000/saml2/metadata/', # Your SP Entity ID 'service': { 'sp': { 'endpoints': { 'assertion_consumer_service': [ ('http://localhost:8000/saml2/acs/', saml2.BINDING_HTTP_POST), ], 'single_logout_service': [ ('http://localhost:8000/saml2/ls/', saml2.BINDING_HTTP_REDIRECT), ('http://localhost:8000/saml2/ls/post', saml2.BINDING_HTTP_POST) ], }, 'allow_unsolicited': True, # Set to True for IdP-initiated SSO without prior SP request 'name_id_format': saml2.NAMEID_FORMAT_UNSPECIFIED, 'attribute_mapping': { 'uid': ('username', ), 'mail': ('email', ), 'cn': ('first_name', ), 'sn': ('last_name', ), }, 'metadata': { 'remote': [{ 'url': 'https://idp.example.com/saml/metadata/', # Your IdP's metadata URL }], }, 'key_file': os.path.join(BASEDIR, 'certs/private.key'), # Path to SP private key 'cert_file': os.path.join(BASEDIR, 'certs/public.cert'), # Path to SP public certificate 'encryption_keypairs': [{ 'key_file': os.path.join(BASEDIR, 'certs/private.key'), 'cert_file': os.path.join(BASEDIR, 'certs/public.cert'), }], }, }, } # urls.py from django.contrib import admin from django.urls import include, path urlpatterns = [ path('admin/', admin.site.urls), path('saml2/', include('djangosaml2.urls')), # Your other app URLs ]

Debug

Known issues

breakingVersion 1.10.0 removed support for Python 3.8 and Django 3.2. Ensure your environment meets the new minimum requirements (Python 3.9+, Django 4.2+).

fix

Upgrade Python to 3.9+ and Django to 4.2+ (or compatible versions as per `djangosaml2`'s `requires_python` and release notes).

affects: >=1.10.0

gotchaThe `xmlsec1` binary is a critical OS-level dependency for `pysaml2` (and thus `djangosaml2`) to sign SAML assertions. Without it, SAML authentication will fail.

fix

Install `xmlsec1` on your operating system (e.g., `apt-get install xmlsec1` on Debian/Ubuntu, `brew install xmlsec1` on macOS) and ensure the `xmlsec_binary` path in `SAML_CONFIG` is correct.

affects: All

gotchaWhen using `HTTP-POST` binding for unsolicited responses, older Django versions (pre-3.1) might have `SameSite` cookie issues. This can lead to cookies not being sent.

fix

Upgrade Django to 3.1 or higher. If not possible, configure `allow_unsolicited` to `True` in your `pySAML2` configuration within `SAML_CONFIG` (though this might have security implications and should be evaluated carefully).

affects: < Django 3.1

gotchaDynamically modifying `settings.SAML_CONFIG` within views in a multi-tenant environment can lead to race conditions and security vulnerabilities where one user's configuration overwrites another's.

fix

Instead of modifying `SAML_CONFIG` directly, use the `SAML_CONFIG_LOADER` setting to point to a callable that returns the `saml2.config.SPConfig` object dynamically, scoped to the current request.

affects: All

gotchaWhen setting `SAML_DJANGO_USER_MAIN_ATTRIBUTE` to map a SAML attribute to a Django user field, ensure the chosen attribute is unique across your user base to prevent authentication failures or unintended user mapping.

fix

Always use a unique attribute (e.g., 'email') for `SAML_DJANGO_USER_MAIN_ATTRIBUTE`. If using an attribute that might not be unique, consider implementing custom user lookup logic.

affects: All

Upgrade

Version history

1.12.0latest on PyPI · released Feb 17, 2026

Audit

Dependencies

pysaml2requiredCore SAML 2.0 implementation library.

DjangorequiredDjango web framework integration.

xmlsec1requiredRequired OS-level binary for signing SAML assertions. Not a Python package.

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/IdentityPython/djangosaml2 ↗

packagehttps://pypi.org/project/djangosaml2/ ↗