{"id":5914,"library":"djangosaml2","title":"djangosaml2","description":"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.","status":"active","version":"1.12.0","language":"en","source_language":"en","source_url":"https://github.com/IdentityPython/djangosaml2","tags":["django","saml","sso","authentication","identity-management"],"install":[{"cmd":"pip install djangosaml2","lang":"bash","label":"Install `djangosaml2`"},{"cmd":"sudo apt-get install xmlsec1 # Debian/Ubuntu\nbrew install xmlsec1 # macOS","lang":"bash","label":"Install `xmlsec1` (OS dependency)"}],"dependencies":[{"reason":"Core SAML 2.0 implementation library.","package":"pysaml2"},{"reason":"Django web framework integration.","package":"Django"},{"reason":"Required OS-level binary for signing SAML assertions. Not a Python package.","package":"xmlsec1","optional":false}],"imports":[{"note":"Used in `AUTHENTICATION_BACKENDS` in `settings.py`.","symbol":"Saml2Backend","correct":"from djangosaml2.backends import Saml2Backend"},{"note":"Includes all necessary SAML 2.0 endpoints for the Service Provider (SP).","symbol":"djangosaml2.urls","correct":"from django.urls import include, path\n\nurlpatterns = [\n    path('saml2/', include('djangosaml2.urls'))\n]"}],"quickstart":{"code":"# settings.py\nimport os\n\nINSTALLED_APPS = [\n    # ... other Django apps\n    'djangosaml2',\n]\n\nAUTHENTICATION_BACKENDS = [\n    'django.contrib.auth.backends.ModelBackend', # Keep default for admin\n    'djangosaml2.backends.Saml2Backend',\n]\n\nLOGIN_URL = '/saml2/login/'\nSESSION_EXPIRE_AT_BROWSER_CLOSE = True # Recommended for SAML\n\nBASEDIR = os.path.dirname(os.path.abspath(__file__))\nSAML_CONFIG = {\n    'xmlsec_binary': '/usr/bin/xmlsec1', # Adjust path if necessary\n    'entityid': 'http://localhost:8000/saml2/metadata/', # Your SP Entity ID\n    'service': {\n        'sp': {\n            'endpoints': {\n                'assertion_consumer_service': [\n                    ('http://localhost:8000/saml2/acs/', saml2.BINDING_HTTP_POST),\n                ],\n                'single_logout_service': [\n                    ('http://localhost:8000/saml2/ls/', saml2.BINDING_HTTP_REDIRECT),\n                    ('http://localhost:8000/saml2/ls/post', saml2.BINDING_HTTP_POST)\n                ],\n            },\n            'allow_unsolicited': True, # Set to True for IdP-initiated SSO without prior SP request\n            'name_id_format': saml2.NAMEID_FORMAT_UNSPECIFIED,\n            'attribute_mapping': {\n                'uid': ('username', ),\n                'mail': ('email', ),\n                'cn': ('first_name', ),\n                'sn': ('last_name', ),\n            },\n            'metadata': {\n                'remote': [{\n                    'url': 'https://idp.example.com/saml/metadata/', # Your IdP's metadata URL\n                }],\n            },\n            'key_file': os.path.join(BASEDIR, 'certs/private.key'), # Path to SP private key\n            'cert_file': os.path.join(BASEDIR, 'certs/public.cert'),   # Path to SP public certificate\n            'encryption_keypairs': [{\n                'key_file': os.path.join(BASEDIR, 'certs/private.key'),\n                'cert_file': os.path.join(BASEDIR, 'certs/public.cert'),\n            }],\n        },\n    },\n}\n\n\n# urls.py\nfrom django.contrib import admin\nfrom django.urls import include, path\n\nurlpatterns = [\n    path('admin/', admin.site.urls),\n    path('saml2/', include('djangosaml2.urls')),\n    # Your other app URLs\n]","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.9+ and Django to 4.2+ (or compatible versions as per `djangosaml2`'s `requires_python` and release notes).","message":"Version 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+).","severity":"breaking","affected_versions":">=1.10.0"},{"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.","message":"The `xmlsec1` binary is a critical OS-level dependency for `pysaml2` (and thus `djangosaml2`) to sign SAML assertions. Without it, SAML authentication will fail.","severity":"gotcha","affected_versions":"All"},{"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).","message":"When 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.","severity":"gotcha","affected_versions":"< Django 3.1"},{"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.","message":"Dynamically 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}