{ "info": { "author": "Yaco Sistemas", "author_email": "lgs@yaco.es", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Environment :: Web Environment", "Intended Audience :: Developers", "Operating System :: OS Independent", "Programming Language :: Python", "Topic :: Internet :: WWW/HTTP", "Topic :: Internet :: WWW/HTTP :: WSGI", "Topic :: Security", "Topic :: Software Development :: Libraries :: Application Frameworks" ], "description": ".. contents::\n\n===========\ndjangosaml2\n===========\n\ndjangosaml2 is a Django application that integrates the PySAML2 library\ninto your project. This mean that you can protect your Django based project\nwith a service provider based on PySAML. This way it will talk SAML2 with\nyour Identity Provider allowing you to use this authentication mechanism.\nThis document will guide you through a few simple steps to accomplish\nsuch goal.\n\n\nInstallation\n============\n\nPySAML2 uses xmlsec1_ binary to sign SAML assertions so you need to install\nit either through your operating system package or by compiling the source\ncode. 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.\n\n.. _xmlsec1: http://www.aleksey.com/xmlsec/\n\nNow you can install the djangosaml2 package using easy_install or pip. This\nwill also install PySAML2 and its dependencies automatically.\n\n\nConfiguration\n=============\n\nThere are three things you need to setup to make djangosaml2 works in your\nDjango project:\n\n1. **settings.py** as you may already know, it is the main Django\n configuration file.\n2. **urls.py** is the file where you will include djangosaml2 urls.\n3. **pysaml2** specific files such as a attribute map directory and a\n certificate.\n\n\nChanges in the settings.py file\n-------------------------------\nThe first thing you need to do is add ``djangosaml2`` to the list of\ninstalled apps::\n\n INSTALLED_APPS = (\n 'django.contrib.auth',\n 'django.contrib.contenttypes',\n 'django.contrib.sessions',\n 'django.contrib.sites',\n 'django.contrib.messages',\n 'django.contrib.admin',\n 'djangosaml2', # new application\n )\n\nActually this is not really required since djangosaml2 does not include\nany data model. The only reason we include it is to be able to run\ndjangosaml2 test suite from our project, something you should always\ndo to make sure it is compatible with your Django version and environment.\n\n.. note::\n\n When you finish the configuation you can run the djangosaml2 test suite\n as you run any other Django application test suite. Just type\n ``python manage.py test djangosaml2``\n\nThen you have to add the djangosaml2.backends.Saml2Backend\nauthentication backend to the list of authentications backends.\nBy default only the ModelBackend included in Django is configured.\nA typical configuration would look like this::\n\n AUTHENTICATION_BACKENDS = (\n 'django.contrib.auth.backends.ModelBackend',\n 'djangosaml2.backends.Saml2Backend',\n )\n\n.. note::\n\n Before djangosaml2 0.5.0 this authentication backend was\n automatically added by djangosaml2. This turned out to be\n a bad idea since some applications want to use their own\n custom policies for authorization and the authentication\n backend is a good place to define that. Starting from\n djangosaml2 0.5.0 it is now possible to define such\n backends.\n\nFinally we have to tell Django what is the new login url we want to use::\n\n LOGIN_URL = '/saml2/login/'\n SESSION_EXPIRE_AT_BROWSER_CLOSE = True\n\nHere we are telling Django that any view that requires an authenticated\nuser should redirect the user browser to that url if the user has not\nbeen authenticated before. We are also telling that when the user closes\nhis browser, the session should be terminated. This is useful in SAML2\nfederations where the logout protocol is not always available.\n\n.. note::\n\n The login url starts with ``/saml2/`` as an example but you can change that\n if you want. Check the section about changes in the ``urls.py``\n file for more information.\n\nIf you want to allow several authentication mechanisms in your project\nyou should set the LOGIN_URL option to another view and put a link in such\nview to the ``/saml2/login/`` view.\n\n\nChanges in the urls.py file\n---------------------------\n\nThe next thing you need to do is to include ``djangosaml2.urls`` module to your\nmain ``urls.py`` module::\n\n urlpatterns = patterns(\n '',\n # lots of url definitions here\n\n (r'^saml2/', include('djangosaml2.urls')),\n\n # more url definitions\n )\n\nAs you can see we are including ``djangosaml2.urls`` under the *saml2*\nprefix. Feel free to use your own prefix but be consistent with what\nyou have put in the ``settings.py`` file in the LOGIN_URL parameter.\n\n\nPySAML2 specific files and configuration\n----------------------------------------\nOnce you have finished configuring your Django project you have to\nstart configuring PySAML. If you use just that library you have to\nput your configuration options in a file and initialize PySAML2 with\nthe path to that file.\n\nIn djangosaml2 you just put the same information in the Django\nsettings.py file under the SAML_CONFIG option.\n\nWe will see a typical configuration for protecting a Django project::\n\n from os import path\n import saml2\n BASEDIR = path.dirname(path.abspath(__file__))\n SAML_CONFIG = {\n # full path to the xmlsec1 binary programm\n 'xmlsec_binary': '/usr/bin/xmlsec1',\n\n # your entity id, usually your subdomain plus the url to the metadata view\n 'entityid': 'http://localhost:8000/saml2/metadata/',\n\n # directory with attribute mapping\n 'attribute_map_dir': path.join(BASEDIR, 'attribute-maps'),\n\n # this block states what services we provide\n 'service': {\n # we are just a lonely SP\n 'sp' : {\n 'name': 'Federated Django sample SP',\n 'endpoints': {\n # url and binding to the assetion consumer service view\n # do not change the binding or service name\n 'assertion_consumer_service': [\n ('http://localhost:8000/saml2/acs/',\n saml2.BINDING_HTTP_POST),\n ],\n # url and binding to the single logout service view\n # do not change the binding or service name\n 'single_logout_service': [\n ('http://localhost:8000/saml2/ls/',\n saml2.BINDING_HTTP_REDIRECT),\n ],\n },\n\n # attributes that this project need to identify a user\n 'required_attributes': ['uid'],\n\n # attributes that may be useful to have but not required\n 'optional_attributes': ['eduPersonAffiliation'],\n\n # in this section the list of IdPs we talk to are defined\n 'idp': {\n # we do not need a WAYF service since there is\n # only an IdP defined here. This IdP should be\n # present in our metadata\n\n # the keys of this dictionary are entity ids\n 'https://localhost/simplesaml/saml2/idp/metadata.php': {\n 'single_sign_on_service': {\n saml2.BINDING_HTTP_REDIRECT: 'https://localhost/simplesaml/saml2/idp/SSOService.php',\n },\n 'single_logout_service': {\n saml2.BINDING_HTTP_REDIRECT: 'https://localhost/simplesaml/saml2/idp/SingleLogoutService.php',\n },\n },\n },\n },\n },\n\n # where the remote metadata is stored\n 'metadata': {\n 'local': [path.join(BASEDIR, 'remote_metadata.xml')],\n },\n\n # set to 1 to output debugging information\n 'debug': 1,\n\n # certificate\n 'key_file': path.join(BASEDIR, 'mycert.key'), # private part\n 'cert_file': path.join(BASEDIR, 'mycert.pem'), # public part\n\n # own metadata settings\n 'contact_person': [\n {'given_name': 'Lorenzo',\n 'sur_name': 'Gil',\n 'company': 'Yaco Sistemas',\n 'email_address': 'lgs@yaco.es',\n 'contact_type': 'technical'},\n {'given_name': 'Angel',\n 'sur_name': 'Fernandez',\n 'company': 'Yaco Sistemas',\n 'email_address': 'angel@yaco.es',\n 'contact_type': 'administrative'},\n ],\n # you can set multilanguage information here\n 'organization': {\n 'name': [('Yaco Sistemas', 'es'), ('Yaco Systems', 'en')],\n 'display_name': [('Yaco', 'es'), ('Yaco', 'en')],\n 'url': [('http://www.yaco.es', 'es'), ('http://www.yaco.com', 'en')],\n },\n 'valid_for': 24, # how long is our metadata valid\n }\n\n.. note::\n\n Please check the `PySAML2 documentation`_ for more information about\n these and other configuration options.\n\n.. _`PySAML2 documentation`: http://packages.python.org/pysaml2/\n\nThere are several external files and directories you have to create according\nto this configuration.\n\nThe xmlsec1 binary was mentioned in the installation section. Here, in the\nconfiguration part you just need to put the full path to xmlsec1 so PySAML2\ncan call it as it needs.\n\nThe ``attribute_map_dir`` points to a directory with attribute mappings that\nare used to translate user attribute names from several standards. It's usually\nsafe to just copy the default PySAML2 attribute maps that you can find in the\n``tests/attributemaps`` directory of the source distribution.\n\nThe ``metadata`` option is a dictionary where you can define several types of\nmetadata for remote entities. Usually the easiest type is the ``local`` where\nyou just put the name of a local XML file with the contents of the remote\nentities metadata. This XML file should be in the SAML2 metadata format.\n\nThe ``key_file`` and ``cert_file`` options references the two parts of a\nstandard x509 certificate. You need it to sign your metadata an to encrypt\nand decrypt the SAML2 assertions.\n\n.. note::\n\n Check your openssl documentation to generate a test certificate but don't\n forget to order a real one when you go into production.\n\n\nCustom and dynamic configuration loading\n........................................\n\nBy default, djangosaml2 reads the pysaml2 configuration options from the\nSAML_CONFIG setting but sometimes you want to read this information from\nanother place, like a file or a database. Sometimes you even want this\nconfiguration to be different depending on the request.\n\nStarting from djangosaml2 0.5.0 you can define your own configuration\nloader which is a callable that accepts a request parameter and returns\na saml2.config.SPConfig object. In order to do so you set the following\nsetting::\n\n SAML_CONFIG_LOADER = 'python.path.to.your.callable'\n\n\nUser attributes\n---------------\n\nIn the SAML 2.0 authentication process the Identity Provider (IdP) will\nsend a security assertion to the Service Provider (SP) upon a succesfull\nauthentication. This assertion contains attributes about the user that\nwas authenticated. It depends on the IdP configuration what exact\nattributes are sent to each SP it can talk to.\n\nWhen such assertion is received on the Django side it is used to find\na Django user and create a session for it. By default djangosaml2 will\ndo a query on the User model with the 'username' attribute but you can\nchange it to any other attribute of the User model. For example,\nyou can do this look up using the 'email' attribute. In order to do so\nyou should set the following setting::\n\n SAML_DJANGO_USER_MAIN_ATTRIBUTE = 'email'\n\nPlease, use an unique attribute when setting this option. Otherwise\nthe authentication process will fail because djangosaml2 does not know\nwhich Django user it should pick.\n\nYou can configure djangosaml2 to create such user if it is not already in\nthe Django database or maybe you don't want to allow users that are not\nin your database already. For this purpose there is another option you\ncan set in the settings.py file::\n\n SAML_CREATE_UNKNOWN_USER = True\n\nThis setting is True by default.\n\nThe other thing you will probably want to configure is the mapping of\nSAML2 user attributes to Django user attributes. By default only the\nUser.username attribute is mapped but you can add more attributes or\nchange that one. In order to do so you need to change the\nSAML_ATTRIBUTE_MAPPING option in your settings.py::\n\n SAML_ATTRIBUTE_MAPPING = {\n 'uid': ('username', ),\n 'mail': ('email', ),\n 'cn': ('first_name', ),\n 'sn': ('last_name', ),\n }\n\nwhere the keys of this dictionary are SAML user attributes and the values\nare Django User attributes.\n\nIf you are using Django user profile objects to store extra attributes\nabout your user you can add those attributes to the SAML_ATTRIBUTE_MAPPING\ndictionary. For each (key, value) pair, djangosaml2 will try to store the\nattribute in the User model if there is a matching field in that model.\nOtherwise it will try to do the same with your profile custom model.\n\nLearn more about Django profile models at:\n\nhttps://docs.djangoproject.com/en/dev/topics/auth/#storing-additional-information-about-users\n\n\nSometimes you need to use special logic to update the user object\ndepending on the SAML2 attributes and the mapping described above\nis simply not enough. For these cases djangosaml2 provides a Django\nsignal that you can listen to. In order to do so you can add the\nfollowing code to your app::\n\n from djangosaml2.signals import pre_user_save\n\n def custom_update_user(sender=user, attributes=attributes, user_modified=user_modified)\n ...\n return True # I modified the user object\n\n\nYour handler will receive the user object, the list of SAML attributes\nand a flag telling you if the user is already modified and need\nto be saved after your handler is executed. If your handler\nmodifies the user object it should return True. Otherwise it should\nreturn False. This way djangosaml2 will know if it should save\nthe user object so you don't need to do it and no more calls to\nthe save method are issued.\n\n\nIdP setup\n=========\nCongratulations, you have finished configuring the SP side of the federation.\nNow you need to send the entity id and the metadata of this new SP to the\nIdP administrators so they can add it to their list of trusted services.\n\nYou can get this information starting your Django development server and\ngoing to the http://localhost:8000/saml2/metadata url. If you have included\nthe djangosaml2 urls under a different url prefix you need to correct this\nurl.\n\nSimpleSAMLphp issues\n--------------------\nAs of SimpleSAMLphp 1.8.2 there is a problem if you specify attributes in\nthe SP configuration. When the SimpleSAMLphp metadata parser converts the\nXML into its custom php format it puts the following option::\n\n 'attributes.NameFormat' => 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri'\n\nBut it need to be replaced by this one::\n\n 'AttributeNameFormat' => 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri'\n\nOtherwise the Assertions sent from the IdP to the SP will have a wrong\nAttribute Name Format and pysaml2 will be confused.\n\nFurthermore if you have a AttributeLimit filter in your SimpleSAMLphp\nconfiguration you will need to enable another attribute filter just\nbefore to make sure that the AttributeLimit does not remove the attributes\nfrom the authentication source. The filter you need to add is an AttributeMap\nfilter like this::\n\n 10 => array(\n 'class' => 'core:AttributeMap', 'name2oid'\n ),\n\nTesting\n=======\n\nOne way to check if everything is working as expected is to enable the\nfollowing url::\n\n urlpatterns = patterns(\n '',\n # lots of url definitions here\n\n (r'^saml2/', include('djangosaml2.urls')),\n (r'^test/', 'djangosaml2.views.echo_attributes'),\n\n # more url definitions\n )\n\n\nNow if you go to the /test/ url you will see your SAML attributes and also\na link to do a global logout.\n\nYou can also run the unit tests with the following command::\n\n python tests/run_tests.py\n\nIf you have `tox`_ installed you can simply call tox inside the root directory\nand it will run the tests in multiple versions of Python.\n\n.. _`tox`: http://pypi.python.org/pypi/tox\n\nFAQ\n===\n\n**Why can't SAML be implemented as an Django Authentication Backend?**\n\nwell SAML authentication is not that simple as a set of credentials you can\nput on a login form and get a response back. Actually the user password is\nnot given to the service provider at all. This is by design. You have to\ndelegate the task of authentication to the IdP and then get an asynchronous\nresponse from it.\n\nGiven said that, djangosaml2 does use a Django Authentication Backend to\ntransform the SAML assertion about the user into a Django user object.\n\n**Why not put everything in a Django middleware class and make our lifes\neasier?**\n\nYes, that was an option I did evaluate but at the end the current design\nwon. In my opinion putting this logic into a middleware has the advantage\nof making it easier to configure but has a couple of disadvantages: first,\nthe middleware would need to check if the request path is one of the\nSAML endpoints for every request. Second, it would be too magical and in\ncase of a problem, much harder to debug.\n\n**Why not call this package django-saml as many other Django applications?**\n\nFollowing that pattern then I should import the application with\nimport saml but unfortunately that module name is already used in pysaml2.\n\n\nChanges\n=======\n0.11.0 (2014-06-15)\n-------------------\n- Django 1.5 custom user model support. Thanks to Jos van Velzen\n- Django 1.5 compatibility url template tag. Thanks to bula\n- Support Django 1.5 and 1.6. Thanks to David Evans and Justin Quick\n\n0.10.0 (2013-05-05)\n-------------------\n- Check that RelayState is not empty before redirecting into a loop. Thanks\n to Sam Bull for reporting this issue.\n- In the global logout process, when the session is lost, report an error\n message to the user and perform a local logout.\n\n0.9.2 (2013-04-19)\n------------------\n- Upgrade to pysaml2-0.4.3.\n\n0.9.1 (2013-01-29)\n------------------\n- Add a method to the authentication backend so it is possible\n to customize the authorization based on SAML attributes.\n\n0.9.0 (2012-10-30)\n------------------\n- Add a signal for modifying the user just before saving it on\n the update_user method of the authentication backend.\n\n0.8.1 (2012-10-29)\n------------------\n- Trim the SAML attributes before setting them to the Django objects\n if they are too long. This fixes a crash with MySQL.\n\n0.8.0 (2012-10-25)\n------------------\n- Allow to use different attributes besides 'username' to look for\n existing users.\n\n0.7.0 (2012-10-19)\n------------------\n- Add a setting to decide if the user should be redirected to the\n next view or shown an authorization error when the user tries to\n login twice.\n\n0.6.1 (2012-09-03)\n------------------\n- Remove Django from our dependencies\n- Restore support for Django 1.3\n\n0.6.0 (2012-08-29)\n------------------\n- Add tox support configured to run the tests with Python 2.6 and 2.7\n- Fix some dependencies and sdist generation. Lorenzo Gil\n- Allow defining a logout redirect url in the settings. Lorenzo Gil\n- Add some logging calls to improve debugging. Lorenzo Gil\n- Add support for custom conf loading function. Sam Bull.\n- Make the tests more robust and easier to run when djangosaml2 is\n included in a Django project. Sam Bull.\n- Make sure the profile is not None before saving it. Bug reported by\n Leif Johansson\n\n0.5.0 (2012-05-22)\n------------------\n- Allow defining custom config loaders. They can be dynamic depending on\n the request.\n- Do not automatically add the authentication backend. This way\n we allow other people to add their own backends.\n- Support for additional attributes other than the ones that get mapped\n into the User model. Those attributes get stored in the UserProfile model.\n\n0.4.2 (2012-03-23)\n------------------\n- Fix a crash in the idplist templatetag about using an old pysaml2 function\n- Added a test for the previous crash\n\n0.4.1 (2012-03-19)\n------------------\n- Upgrade pysaml2 dependency to version 0.4.1\n\n0.4.0 (2012-03-18)\n------------------\n- Upgrade pysaml2 dependency to version 0.4.0 (update our tests as a result\n of this)\n- Add logging calls to make debugging easier\n- Use the Django configured logger in pysaml2\n\n0.3.3 (2012-02-14)\n------------------\n- Freeze the version of pysaml2 since we are not (yet!) compatible with\n version 0.4.0\n\n0.3.2 (2011-12-13)\n------------------\n- Avoid a crash when reading the SAML attribute that maps to the Django\n username\n\n0.3.1 (2011-12-01)\n------------------\n- Load the config in the render method of the idplist templatetag to\n make it more flexible and reentrant.\n\n0.3.0 (2011-11-30)\n------------------\n- Templatetag to get the list of available idps.\n- Allow to map the same SAML attribute into several Django field.\n\n0.2.4 (2011-11-29)\n------------------\n- Fix restructured text bugs that made pypi page looks bad.\n\n0.2.3 (2011-06-14)\n------------------\n- Set a unusable password when the user is created for the first time\n\n0.2.2 (2011-06-07)\n------------------\n- Prevent infinite loop when going to the /saml2/login/ endpoint and the user\n is already logged in and the settings.LOGIN_REDIRECT_URL is (badly) pointing\n to /saml2/login.\n\n0.2.1 (2011-05-09)\n------------------\n- If no next parameter is supplied to the login view, use the\n settings.LOGIN_REDIRECT_URL as default\n\n0.2.0 (2011-04-26)\n------------------\n- Python 2.4 compatible if the elementtree library is installed\n- Allow post processing after the authentication phase by using\n Django signals.\n\n0.1.1 (2011-04-18)\n------------------\n- Simple view to echo SAML attributes\n- Improve documentation\n- Change default behaviour when a new user is created. Now their attributes\n are filled this first time\n- Allow to set a next page after the logout\n\n0.1.0 (2011-03-16)\n------------------\n- Emancipation from the pysaml package", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/bernii/djangosaml2", "keywords": "django,pysaml2,saml2,federated authentication,authentication", "license": "Apache 2.0", "maintainer": null, "maintainer_email": null, "name": "djangosaml2-bernii", "package_url": "https://pypi.org/project/djangosaml2-bernii/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/djangosaml2-bernii/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/bernii/djangosaml2" }, "release_url": "https://pypi.org/project/djangosaml2-bernii/0.11.2/", "requires_dist": null, "requires_python": null, "summary": "pysaml2 integration in Django", "version": "0.11.2" }, "last_serial": 1182942, "releases": { "0.11.1": [ { "comment_text": "", "digests": { "md5": "30aa57b1a941395e3589af7897ae4027", "sha256": "03a1a2f0f9eea4b1155b6d3f60a7c534d7266fe9132db17495e54e33623a9ae8" }, "downloads": -1, "filename": "djangosaml2-bernii-0.11.1.tar.gz", "has_sig": false, "md5_digest": "30aa57b1a941395e3589af7897ae4027", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 49060, "upload_time": "2014-08-07T08:50:00", "url": "https://files.pythonhosted.org/packages/aa/c6/b83075cc9a83906603b50cbc1093899e67474ee1f5feafdc6b28f5f7d436/djangosaml2-bernii-0.11.1.tar.gz" } ], "0.11.2": [ { "comment_text": "", "digests": { "md5": "8144029820c893244b0d1aff78367f7c", "sha256": "1a5cdcea449ac96a2288b3da8f5b65ad1e98156a14d565a210f2513113605df6" }, "downloads": -1, "filename": "djangosaml2-bernii-0.11.2.tar.gz", "has_sig": false, "md5_digest": "8144029820c893244b0d1aff78367f7c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 49122, "upload_time": "2014-08-07T14:12:52", "url": "https://files.pythonhosted.org/packages/7f/52/a5015933a83a095b80a81eb9b720b80351d738e942835b6e89fad1f64364/djangosaml2-bernii-0.11.2.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "8144029820c893244b0d1aff78367f7c", "sha256": "1a5cdcea449ac96a2288b3da8f5b65ad1e98156a14d565a210f2513113605df6" }, "downloads": -1, "filename": "djangosaml2-bernii-0.11.2.tar.gz", "has_sig": false, "md5_digest": "8144029820c893244b0d1aff78367f7c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 49122, "upload_time": "2014-08-07T14:12:52", "url": "https://files.pythonhosted.org/packages/7f/52/a5015933a83a095b80a81eb9b720b80351d738e942835b6e89fad1f64364/djangosaml2-bernii-0.11.2.tar.gz" } ] }