djsaml2-idp-app
===============
djsaml2-idpapp implements the Identity Provider side of the SAML2 protocol for Django.
It builds on top of `PySAML2 <https://github.com/IdentityPython/pysaml2>`_, and is production-ready.
Any contributions, feature requests, proposals, ideas ... are welcome! See the `CONTRIBUTING document <https://github.com/abybaddi009/djangosaml2idp/blob/master/CONTRIBUTING.md>`_ for some info.
Installation
============
PySAML2 uses `XML Security Library <http://www.aleksey.com/xmlsec/>`_ binary to sign SAML assertions, so you need to install
it either through your operating system package or by compiling the source code. It doesn't matter where the final executable is installed because
you will need to set the full path to it in the configuration stage. XmlSec is available (at least) for Debian, OSX and Alpine Linux.
Now you can install the djsaml2-idp-app package using pip. This will also install PySAML2 and its dependencies automatically::
pip install djsaml2-idp-app
Configuration & Usage
=====================
The first thing you need to do is add ``djangosaml2idp`` to the list of installed apps::
INSTALLED_APPS = (
'django.contrib.admin',
'djangosaml2idp',
...
)
Now include ``djangosaml2idp`` in your project by adding it in the url config::
from django.conf.urls import url, include
from django.contrib import admin
urlpatterns = [
url(r'^idp/', include('djangosaml2idp.urls')),
url(r'^admin/', admin.site.urls),
...
]
Run the migrations for the app.
In your Django settings, configure your IdP. Configuration follows the `PySAML2 configuration <https://github.com/IdentityPython/pysaml2/blob/master/docs/howto/config.rst>`_. The IdP from the example project looks like this::
import saml2
from saml2.saml import NAMEID_FORMAT_EMAILADDRESS, NAMEID_FORMAT_UNSPECIFIED
from saml2.sigver import get_xmlsec_binary
LOGIN_URL = '/login/'
BASE_URL = 'http://localhost:9000/idp'
SAML_IDP_CONFIG = {
'debug' : DEBUG,
'xmlsec_binary': get_xmlsec_binary(['/opt/local/bin', '/usr/bin']),
'entityid': '%s/metadata' % BASE_URL,
'description': 'Example IdP setup',
'service': {
'idp': {
'name': 'Django localhost IdP',
'endpoints': {
'single_sign_on_service': [
('http://localhost:9000/idp/sso/post/', saml2.BINDING_HTTP_POST),
('http://localhost:9000/idp/sso/redirect/', saml2.BINDING_HTTP_REDIRECT),
],
"single_logout_service": [
("http://localhost:9000/idp/slo/post/", saml2.BINDING_HTTP_POST),
("http://localhost:9000/idp/slo/redirect/", saml2.BINDING_HTTP_REDIRECT)
],
},
'name_id_format': [NAMEID_FORMAT_EMAILADDRESS, NAMEID_FORMAT_UNSPECIFIED],
'sign_response': True,
'sign_assertion': True,
'want_authn_requests_signed': True,
},
},
# Signing
'key_file': BASE_DIR + '/certificates/private.key',
'cert_file': BASE_DIR + '/certificates/public.cert',
# Encryption
'encryption_keypairs': [{
'key_file': BASE_DIR + '/certificates/private.key',
'cert_file': BASE_DIR + '/certificates/public.cert',
}],
'valid_for': 365 * 24,
}
Notice the configuration requires a private key and public certificate to be available on the filesystem in order to sign and encrypt messages.
Next the Service Providers and their configuration need to be added, this is done via the Django admin interface. Add an entry for each SP which speaks to thie IdP.
Add a copy of the local metadata xml, or set a remote metadata url. Add an attribute mapping for user attributes to SAML fields or leave the default mapping which will be prefilled.
Several attributes can be overriden per SP. If they aren't overridden explicitly, they will use the 'global' settings which can be configured for your Django installation.
If those aren't set, some defaults will be used, as indicated in the admin when you configre a SP.
The resulting configuration of a SP, with merged settings of its own and the instance settings and defaults, is shown in the admin as a summary.
Further optional configuration options
======================================
In the ``SAML_IDP_SPCONFIG`` setting you can define a ``processor``, its value being a string with dotted path to a class.
This is a hook to customize some access control checks. By default, the included `BaseProcessor` is used, which allows every user to login on the IdP.
You can customize this behaviour by subclassing the `BaseProcessor` and overriding its `has_access(self, request)` method. This method should return true or false, depending if the user has permission to log in for the SP / IdP.
The processor has the SP entity ID available as `self._entity_id`, and received the request (with an authenticated request.user on it) as parameter to the `has_access` function.
This way, you should have the necessary flexibility to perform whatever checks you need.
An example `processor subclass <https://github.com/abybaddi009/djangosaml2idp/blob/master/example_setup/idp/idp/processors.py>`_ can be found in the IdP of the included example.
Use this metadata xml to configure your SP. Place the metadata xml from that SP in the location specified in the config dict (sp_metadata.xml in the example above).
Without custom setting, users will be identified by the ``USERNAME_FIELD`` property on the user Model you use. By Django defaults this will be the username.
You can customize which field is used for the identifier by adding ``SAML_IDP_DJANGO_USERNAME_FIELD`` to your settings with as value the attribute to use on your user instance.
Other settings you can set as defaults to be used if not overriden by an SP are `SAML_AUTHN_SIGN_ALG`, `SAML_AUTHN_DIGEST_ALG`, and `SAML_ENCRYPT_AUTHN_RESPONSE`. They can be set if desired in the django settings, in which case they will be used for all ServiceProviders configuration on this instance if they don't override it. E.g.::
SAML_AUTHN_SIGN_ALG = saml2.xmldsig.SIG_RSA_SHA256
SAML_AUTHN_DIGEST_ALG = saml2.xmldsig.DIGEST_SHA256
In case your SP does not properly expose validuntil in metadata, you can provide fallback setting for it using::
SAML_IDP_FALLBACK_EXPIRATION_DAYS = 30
The default value for the fields ``processor`` and ``attribute_mapping`` in the ``ServiceProvider`` can be set via the settings (the values displayed here are the defaults)::
SAML_IDP_SP_FIELD_DEFAULT_PROCESSOR = 'djangosaml2idp.processors.BaseProcessor'
SAML_IDP_SP_FIELD_DEFAULT_ATTRIBUTE_MAPPING = {"email": "email", "first_name": "first_name", "last_name": "last_name", "is_staff": "is_staff", "is_superuser": "is_superuser"}
Customizing error handling
==========================
djangosaml2idp renders a very basic error page if it encounters an error, indicating an error occured, which error, and possibly an extra message.
The HTTP status code is dependant on which error occured. It also logs the exception with error severity.
You can customize this by using the ``SAML_IDP_ERROR_VIEW_CLASS`` setting. Set this to a dotted import path to your custom (class based) view in order to use that one.
You'll likely want this to use your own template and styling to display and error message.
If you subclass the provided `djangosaml2idp.error_views.SamlIDPErrorView`, you have the following variables available for use in the template:
exception
the exception instance that occurred
exception_type
the class of the exception that occurred
exception_msg
the message from the exception (by doing `str(exception)`)
extra_message
if no specific exception given, a message indicating something went wrong, or an additional message next to the `exception_msg`
The simplest override is to subclass the `SamlIDPErrorView` and only using your own error template.
You can use any Class-Based-View for this; it's not necessary to subclass the builtin error view.
The example project contains a ready to use example of this; uncomment the `SAML_IDP_ERROR_VIEW_CLASS` setting and it will use a custom view with custom template.
Multi Factor Authentication support
===================================
There are three main components to adding multiple factor support.
1. Subclass djangosaml2idp.processors.BaseProcessor as outlined above. You will need to override the `enable_multifactor()` method to check whether or not multifactor should be enabled for a user. (If it should allways be enabled for all users simply hard code to True). By default it unconditionally returns False and no multifactor is enforced.
2. Sublass the `djangosaml2idp.views.ProcessMultiFactorView` view to make the appropriate calls for your environment. Implement your custom verification logic in the `multifactor_is_valid` method: this could call a helper script, an internal SMS triggering service, a data source only the IdP can access or an external second factor provider (e.g. Symantec VIP). By default this view will log that it was called then redirect.
3. Add an entry to settings.py with a string representing the path to your multifactor view. The first package should be the app name:
`SAML_IDP_MULTIFACTOR_VIEW = "this.is.the.path.to.your.multifactor.view`
Running the test suite
======================
Install the dev dependencies in ``requirements-dev.txt``::
pip install -r requirements-dev.txt
Run the test suite from the project root::
tox -e format # to run linting
tox -e py3.7-django3.0 # to run the tests
tox -e typing # to run typechecking, this is allowed to fail
Tests will be ran using CI when opening a merge request as well.
Example project
---------------
The directory ``example_project`` contains a barebone demo setup to demonstrate the login-logout functionality.
It consists of a Service Provider implemented with `djangosaml2 <https://github.com/knaperek/djangosaml2/>`_ and an Identity Provider using ``djangosaml2idp``.
The readme in that folder contains more information on how to run it.
Raw data
{
"_id": null,
"home_page": "https://github.com/abybaddi009/djangosaml2idp/",
"name": "djsaml2-idp-app",
"maintainer": "Abhishek Baddi",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "django, pysaml2, sso, saml2, federated authentication, authentication, idp",
"author": "Abhishek Baddi",
"author_email": "abybaddi009@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1c/08/697a94309e56326361e62b42f7e2b47e4865c86bd5dfaee993325d5618f7/djsaml2_idp_app-0.7.4.tar.gz",
"platform": null,
"description": "djsaml2-idp-app\n===============\n\ndjsaml2-idpapp implements the Identity Provider side of the SAML2 protocol for Django.\nIt builds on top of `PySAML2 <https://github.com/IdentityPython/pysaml2>`_, and is production-ready.\n\nAny contributions, feature requests, proposals, ideas ... are welcome! See the `CONTRIBUTING document <https://github.com/abybaddi009/djangosaml2idp/blob/master/CONTRIBUTING.md>`_ for some info.\n\nInstallation\n============\n\nPySAML2 uses `XML Security Library <http://www.aleksey.com/xmlsec/>`_ binary to sign SAML assertions, so you need to install\nit either through your operating system package or by compiling the source code. It doesn't matter where the final executable is installed because\nyou will need to set the full path to it in the configuration stage. XmlSec is available (at least) for Debian, OSX and Alpine Linux.\n\nNow you can install the djsaml2-idp-app package using pip. This will also install PySAML2 and its dependencies automatically::\n\n pip install djsaml2-idp-app\n\n\nConfiguration & Usage\n=====================\n\nThe first thing you need to do is add ``djangosaml2idp`` to the list of installed apps::\n\n INSTALLED_APPS = (\n 'django.contrib.admin',\n 'djangosaml2idp',\n ...\n )\n\nNow include ``djangosaml2idp`` in your project by adding it in the url config::\n\n from django.conf.urls import url, include\n from django.contrib import admin\n\n urlpatterns = [\n url(r'^idp/', include('djangosaml2idp.urls')),\n url(r'^admin/', admin.site.urls),\n ...\n ]\n\nRun the migrations for the app.\n\nIn your Django settings, configure your IdP. Configuration follows the `PySAML2 configuration <https://github.com/IdentityPython/pysaml2/blob/master/docs/howto/config.rst>`_. The IdP from the example project looks like this::\n\n import saml2\n from saml2.saml import NAMEID_FORMAT_EMAILADDRESS, NAMEID_FORMAT_UNSPECIFIED\n from saml2.sigver import get_xmlsec_binary\n\n LOGIN_URL = '/login/'\n BASE_URL = 'http://localhost:9000/idp'\n\n SAML_IDP_CONFIG = {\n 'debug' : DEBUG,\n 'xmlsec_binary': get_xmlsec_binary(['/opt/local/bin', '/usr/bin']),\n 'entityid': '%s/metadata' % BASE_URL,\n 'description': 'Example IdP setup',\n\n 'service': {\n 'idp': {\n 'name': 'Django localhost IdP',\n 'endpoints': {\n 'single_sign_on_service': [\n ('http://localhost:9000/idp/sso/post/', saml2.BINDING_HTTP_POST),\n ('http://localhost:9000/idp/sso/redirect/', saml2.BINDING_HTTP_REDIRECT),\n ],\n \"single_logout_service\": [\n (\"http://localhost:9000/idp/slo/post/\", saml2.BINDING_HTTP_POST),\n (\"http://localhost:9000/idp/slo/redirect/\", saml2.BINDING_HTTP_REDIRECT)\n ],\n },\n 'name_id_format': [NAMEID_FORMAT_EMAILADDRESS, NAMEID_FORMAT_UNSPECIFIED],\n 'sign_response': True,\n 'sign_assertion': True,\n 'want_authn_requests_signed': True,\n },\n },\n\n # Signing\n 'key_file': BASE_DIR + '/certificates/private.key',\n 'cert_file': BASE_DIR + '/certificates/public.cert',\n # Encryption\n 'encryption_keypairs': [{\n 'key_file': BASE_DIR + '/certificates/private.key',\n 'cert_file': BASE_DIR + '/certificates/public.cert',\n }],\n 'valid_for': 365 * 24,\n }\n\n\nNotice the configuration requires a private key and public certificate to be available on the filesystem in order to sign and encrypt messages.\n\nNext the Service Providers and their configuration need to be added, this is done via the Django admin interface. Add an entry for each SP which speaks to thie IdP.\nAdd a copy of the local metadata xml, or set a remote metadata url. Add an attribute mapping for user attributes to SAML fields or leave the default mapping which will be prefilled.\n\nSeveral attributes can be overriden per SP. If they aren't overridden explicitly, they will use the 'global' settings which can be configured for your Django installation.\nIf those aren't set, some defaults will be used, as indicated in the admin when you configre a SP.\nThe resulting configuration of a SP, with merged settings of its own and the instance settings and defaults, is shown in the admin as a summary.\n\nFurther optional configuration options\n======================================\n\nIn the ``SAML_IDP_SPCONFIG`` setting you can define a ``processor``, its value being a string with dotted path to a class.\nThis is a hook to customize some access control checks. By default, the included `BaseProcessor` is used, which allows every user to login on the IdP.\nYou can customize this behaviour by subclassing the `BaseProcessor` and overriding its `has_access(self, request)` method. This method should return true or false, depending if the user has permission to log in for the SP / IdP.\nThe processor has the SP entity ID available as `self._entity_id`, and received the request (with an authenticated request.user on it) as parameter to the `has_access` function.\nThis way, you should have the necessary flexibility to perform whatever checks you need.\nAn example `processor subclass <https://github.com/abybaddi009/djangosaml2idp/blob/master/example_setup/idp/idp/processors.py>`_ can be found in the IdP of the included example.\nUse this metadata xml to configure your SP. Place the metadata xml from that SP in the location specified in the config dict (sp_metadata.xml in the example above).\n\nWithout custom setting, users will be identified by the ``USERNAME_FIELD`` property on the user Model you use. By Django defaults this will be the username.\nYou can customize which field is used for the identifier by adding ``SAML_IDP_DJANGO_USERNAME_FIELD`` to your settings with as value the attribute to use on your user instance.\n\nOther settings you can set as defaults to be used if not overriden by an SP are `SAML_AUTHN_SIGN_ALG`, `SAML_AUTHN_DIGEST_ALG`, and `SAML_ENCRYPT_AUTHN_RESPONSE`. They can be set if desired in the django settings, in which case they will be used for all ServiceProviders configuration on this instance if they don't override it. E.g.::\n\n SAML_AUTHN_SIGN_ALG = saml2.xmldsig.SIG_RSA_SHA256\n SAML_AUTHN_DIGEST_ALG = saml2.xmldsig.DIGEST_SHA256\n\nIn case your SP does not properly expose validuntil in metadata, you can provide fallback setting for it using::\n\n SAML_IDP_FALLBACK_EXPIRATION_DAYS = 30\n\nThe default value for the fields ``processor`` and ``attribute_mapping`` in the ``ServiceProvider`` can be set via the settings (the values displayed here are the defaults)::\n\n SAML_IDP_SP_FIELD_DEFAULT_PROCESSOR = 'djangosaml2idp.processors.BaseProcessor'\n SAML_IDP_SP_FIELD_DEFAULT_ATTRIBUTE_MAPPING = {\"email\": \"email\", \"first_name\": \"first_name\", \"last_name\": \"last_name\", \"is_staff\": \"is_staff\", \"is_superuser\": \"is_superuser\"}\n\n\nCustomizing error handling\n==========================\n\ndjangosaml2idp renders a very basic error page if it encounters an error, indicating an error occured, which error, and possibly an extra message.\nThe HTTP status code is dependant on which error occured. It also logs the exception with error severity.\nYou can customize this by using the ``SAML_IDP_ERROR_VIEW_CLASS`` setting. Set this to a dotted import path to your custom (class based) view in order to use that one.\nYou'll likely want this to use your own template and styling to display and error message.\nIf you subclass the provided `djangosaml2idp.error_views.SamlIDPErrorView`, you have the following variables available for use in the template:\n\nexception\n the exception instance that occurred\n\nexception_type\n the class of the exception that occurred\n\nexception_msg\n the message from the exception (by doing `str(exception)`)\n\nextra_message\n if no specific exception given, a message indicating something went wrong, or an additional message next to the `exception_msg`\n\nThe simplest override is to subclass the `SamlIDPErrorView` and only using your own error template.\nYou can use any Class-Based-View for this; it's not necessary to subclass the builtin error view.\nThe example project contains a ready to use example of this; uncomment the `SAML_IDP_ERROR_VIEW_CLASS` setting and it will use a custom view with custom template.\n\n\nMulti Factor Authentication support\n===================================\n\nThere are three main components to adding multiple factor support.\n\n\n1. Subclass djangosaml2idp.processors.BaseProcessor as outlined above. You will need to override the `enable_multifactor()` method to check whether or not multifactor should be enabled for a user. (If it should allways be enabled for all users simply hard code to True). By default it unconditionally returns False and no multifactor is enforced.\n\n2. Sublass the `djangosaml2idp.views.ProcessMultiFactorView` view to make the appropriate calls for your environment. Implement your custom verification logic in the `multifactor_is_valid` method: this could call a helper script, an internal SMS triggering service, a data source only the IdP can access or an external second factor provider (e.g. Symantec VIP). By default this view will log that it was called then redirect.\n\n3. Add an entry to settings.py with a string representing the path to your multifactor view. The first package should be the app name:\n`SAML_IDP_MULTIFACTOR_VIEW = \"this.is.the.path.to.your.multifactor.view`\n\n\nRunning the test suite\n======================\nInstall the dev dependencies in ``requirements-dev.txt``::\n\n pip install -r requirements-dev.txt\n\nRun the test suite from the project root::\n\n tox -e format # to run linting\n tox -e py3.7-django3.0 # to run the tests\n tox -e typing # to run typechecking, this is allowed to fail\n\nTests will be ran using CI when opening a merge request as well.\n\n\nExample project\n---------------\nThe directory ``example_project`` contains a barebone demo setup to demonstrate the login-logout functionality.\nIt consists of a Service Provider implemented with `djangosaml2 <https://github.com/knaperek/djangosaml2/>`_ and an Identity Provider using ``djangosaml2idp``.\nThe readme in that folder contains more information on how to run it.\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "SAML 2.0 Identity Provider for Django",
"version": "0.7.4",
"project_urls": {
"Homepage": "https://github.com/abybaddi009/djangosaml2idp/"
},
"split_keywords": [
"django",
" pysaml2",
" sso",
" saml2",
" federated authentication",
" authentication",
" idp"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1a8cef13ecffdb1b7066e5394557f5ea175751a2f844fea942b0c6d93acbbab8",
"md5": "ebc7841051571af23392c02a194ed509",
"sha256": "4ade5cff386447f9998e2ee0e14cd8564430addf5a227a11a0e20ad6f8e1e3f9"
},
"downloads": -1,
"filename": "djsaml2_idp_app-0.7.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "ebc7841051571af23392c02a194ed509",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 30379,
"upload_time": "2024-09-30T06:35:45",
"upload_time_iso_8601": "2024-09-30T06:35:45.064596Z",
"url": "https://files.pythonhosted.org/packages/1a/8c/ef13ecffdb1b7066e5394557f5ea175751a2f844fea942b0c6d93acbbab8/djsaml2_idp_app-0.7.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c08697a94309e56326361e62b42f7e2b47e4865c86bd5dfaee993325d5618f7",
"md5": "e40da6cb5d33aa600c7ea2d355e76458",
"sha256": "63990ea9241e4457a1bd98992fbee6dfee8373f4a1dca4720bbd9264580d216e"
},
"downloads": -1,
"filename": "djsaml2_idp_app-0.7.4.tar.gz",
"has_sig": false,
"md5_digest": "e40da6cb5d33aa600c7ea2d355e76458",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 41315,
"upload_time": "2024-09-30T06:35:47",
"upload_time_iso_8601": "2024-09-30T06:35:47.222785Z",
"url": "https://files.pythonhosted.org/packages/1c/08/697a94309e56326361e62b42f7e2b47e4865c86bd5dfaee993325d5618f7/djsaml2_idp_app-0.7.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-30 06:35:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "abybaddi009",
"github_project": "djangosaml2idp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "djsaml2-idp-app"
}
JSON
