djangosaml2-bernii 0.11.2

Changes in the settings.py file

The first thing you need to do is add djangosaml2 to the list of installed apps:

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.messages',
    'django.contrib.admin',
    'djangosaml2',  # new application
)

Actually this is not really required since djangosaml2 does not include any data model. The only reason we include it is to be able to run djangosaml2 test suite from our project, something you should always do to make sure it is compatible with your Django version and environment.

Then you have to add the djangosaml2.backends.Saml2Backend authentication backend to the list of authentications backends. By default only the ModelBackend included in Django is configured. A typical configuration would look like this:

AUTHENTICATION_BACKENDS = (
    'django.contrib.auth.backends.ModelBackend',
    'djangosaml2.backends.Saml2Backend',
)

Finally we have to tell Django what is the new login url we want to use:

LOGIN_URL = '/saml2/login/'
SESSION_EXPIRE_AT_BROWSER_CLOSE = True

Here we are telling Django that any view that requires an authenticated user should redirect the user browser to that url if the user has not been authenticated before. We are also telling that when the user closes his browser, the session should be terminated. This is useful in SAML2 federations where the logout protocol is not always available.

If you want to allow several authentication mechanisms in your project you should set the LOGIN_URL option to another view and put a link in such view to the /saml2/login/ view.

Changes in the urls.py file

The next thing you need to do is to include djangosaml2.urls module to your main urls.py module:

urlpatterns = patterns(
    '',
    #  lots of url definitions here

    (r'^saml2/', include('djangosaml2.urls')),

    #  more url definitions
)

As you can see we are including djangosaml2.urls under the saml2 prefix. Feel free to use your own prefix but be consistent with what you have put in the settings.py file in the LOGIN_URL parameter.

PySAML2 specific files and configuration

Once you have finished configuring your Django project you have to start configuring PySAML. If you use just that library you have to put your configuration options in a file and initialize PySAML2 with the path to that file.

In djangosaml2 you just put the same information in the Django settings.py file under the SAML_CONFIG option.

We will see a typical configuration for protecting a Django project:

from os import path
import saml2
BASEDIR = path.dirname(path.abspath(__file__))
SAML_CONFIG = {
  # full path to the xmlsec1 binary programm
  'xmlsec_binary': '/usr/bin/xmlsec1',

  # your entity id, usually your subdomain plus the url to the metadata view
  'entityid': 'http://localhost:8000/saml2/metadata/',

  # directory with attribute mapping
  'attribute_map_dir': path.join(BASEDIR, 'attribute-maps'),

  # this block states what services we provide
  'service': {
      # we are just a lonely SP
      'sp' : {
          'name': 'Federated Django sample SP',
          'endpoints': {
              # url and binding to the assetion consumer service view
              # do not change the binding or service name
              'assertion_consumer_service': [
                  ('http://localhost:8000/saml2/acs/',
                   saml2.BINDING_HTTP_POST),
                  ],
              # url and binding to the single logout service view
              # do not change the binding or service name
              'single_logout_service': [
                  ('http://localhost:8000/saml2/ls/',
                   saml2.BINDING_HTTP_REDIRECT),
                  ],
              },

           # attributes that this project need to identify a user
          'required_attributes': ['uid'],

           # attributes that may be useful to have but not required
          'optional_attributes': ['eduPersonAffiliation'],

          # in this section the list of IdPs we talk to are defined
          'idp': {
              # we do not need a WAYF service since there is
              # only an IdP defined here. This IdP should be
              # present in our metadata

              # the keys of this dictionary are entity ids
              'https://localhost/simplesaml/saml2/idp/metadata.php': {
                  'single_sign_on_service': {
                      saml2.BINDING_HTTP_REDIRECT: 'https://localhost/simplesaml/saml2/idp/SSOService.php',
                      },
                  'single_logout_service': {
                      saml2.BINDING_HTTP_REDIRECT: 'https://localhost/simplesaml/saml2/idp/SingleLogoutService.php',
                      },
                  },
              },
          },
      },

  # where the remote metadata is stored
  'metadata': {
      'local': [path.join(BASEDIR, 'remote_metadata.xml')],
      },

  # set to 1 to output debugging information
  'debug': 1,

  # certificate
  'key_file': path.join(BASEDIR, 'mycert.key'),  # private part
  'cert_file': path.join(BASEDIR, 'mycert.pem'),  # public part

  # own metadata settings
  'contact_person': [
      {'given_name': 'Lorenzo',
       'sur_name': 'Gil',
       'company': 'Yaco Sistemas',
       'email_address': 'lgs@yaco.es',
       'contact_type': 'technical'},
      {'given_name': 'Angel',
       'sur_name': 'Fernandez',
       'company': 'Yaco Sistemas',
       'email_address': 'angel@yaco.es',
       'contact_type': 'administrative'},
      ],
  # you can set multilanguage information here
  'organization': {
      'name': [('Yaco Sistemas', 'es'), ('Yaco Systems', 'en')],
      'display_name': [('Yaco', 'es'), ('Yaco', 'en')],
      'url': [('http://www.yaco.es', 'es'), ('http://www.yaco.com', 'en')],
      },
  'valid_for': 24,  # how long is our metadata valid
  }

There are several external files and directories you have to create according to this configuration.

The xmlsec1 binary was mentioned in the installation section. Here, in the configuration part you just need to put the full path to xmlsec1 so PySAML2 can call it as it needs.

The attribute_map_dir points to a directory with attribute mappings that are used to translate user attribute names from several standards. It’s usually safe to just copy the default PySAML2 attribute maps that you can find in the tests/attributemaps directory of the source distribution.

The metadata option is a dictionary where you can define several types of metadata for remote entities. Usually the easiest type is the local where you just put the name of a local XML file with the contents of the remote entities metadata. This XML file should be in the SAML2 metadata format.

The key_file and cert_file options references the two parts of a standard x509 certificate. You need it to sign your metadata an to encrypt and decrypt the SAML2 assertions.

SAML_CONFIG_LOADER = 'python.path.to.your.callable'

User attributes

In the SAML 2.0 authentication process the Identity Provider (IdP) will send a security assertion to the Service Provider (SP) upon a succesfull authentication. This assertion contains attributes about the user that was authenticated. It depends on the IdP configuration what exact attributes are sent to each SP it can talk to.

When such assertion is received on the Django side it is used to find a Django user and create a session for it. By default djangosaml2 will do a query on the User model with the ‘username’ attribute but you can change it to any other attribute of the User model. For example, you can do this look up using the ‘email’ attribute. In order to do so you should set the following setting:

SAML_DJANGO_USER_MAIN_ATTRIBUTE = 'email'

Please, use an unique attribute when setting this option. Otherwise the authentication process will fail because djangosaml2 does not know which Django user it should pick.

You can configure djangosaml2 to create such user if it is not already in the Django database or maybe you don’t want to allow users that are not in your database already. For this purpose there is another option you can set in the settings.py file:

SAML_CREATE_UNKNOWN_USER = True

This setting is True by default.

The other thing you will probably want to configure is the mapping of SAML2 user attributes to Django user attributes. By default only the User.username attribute is mapped but you can add more attributes or change that one. In order to do so you need to change the SAML_ATTRIBUTE_MAPPING option in your settings.py:

SAML_ATTRIBUTE_MAPPING = {
    'uid': ('username', ),
    'mail': ('email', ),
    'cn': ('first_name', ),
    'sn': ('last_name', ),
}

where the keys of this dictionary are SAML user attributes and the values are Django User attributes.

If you are using Django user profile objects to store extra attributes about your user you can add those attributes to the SAML_ATTRIBUTE_MAPPING dictionary. For each (key, value) pair, djangosaml2 will try to store the attribute in the User model if there is a matching field in that model. Otherwise it will try to do the same with your profile custom model.

Learn more about Django profile models at:

https://docs.djangoproject.com/en/dev/topics/auth/#storing-additional-information-about-users

Sometimes you need to use special logic to update the user object depending on the SAML2 attributes and the mapping described above is simply not enough. For these cases djangosaml2 provides a Django signal that you can listen to. In order to do so you can add the following code to your app:

from djangosaml2.signals import pre_user_save

def custom_update_user(sender=user, attributes=attributes, user_modified=user_modified)
   ...
   return True  # I modified the user object

Your handler will receive the user object, the list of SAML attributes and a flag telling you if the user is already modified and need to be saved after your handler is executed. If your handler modifies the user object it should return True. Otherwise it should return False. This way djangosaml2 will know if it should save the user object so you don’t need to do it and no more calls to the save method are issued.

SimpleSAMLphp issues

As of SimpleSAMLphp 1.8.2 there is a problem if you specify attributes in the SP configuration. When the SimpleSAMLphp metadata parser converts the XML into its custom php format it puts the following option:

'attributes.NameFormat' => 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri'

But it need to be replaced by this one:

'AttributeNameFormat' => 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri'

Otherwise the Assertions sent from the IdP to the SP will have a wrong Attribute Name Format and pysaml2 will be confused.

Furthermore if you have a AttributeLimit filter in your SimpleSAMLphp configuration you will need to enable another attribute filter just before to make sure that the AttributeLimit does not remove the attributes from the authentication source. The filter you need to add is an AttributeMap filter like this:

10 => array(
           'class' => 'core:AttributeMap', 'name2oid'
      ),

0.11.0 (2014-06-15)

• Django 1.5 custom user model support. Thanks to Jos van Velzen

• Django 1.5 compatibility url template tag. Thanks to bula

• Support Django 1.5 and 1.6. Thanks to David Evans and Justin Quick

0.10.0 (2013-05-05)

• Check that RelayState is not empty before redirecting into a loop. Thanks to Sam Bull for reporting this issue.

• In the global logout process, when the session is lost, report an error message to the user and perform a local logout.

0.9.2 (2013-04-19)

• Upgrade to pysaml2-0.4.3.

0.9.1 (2013-01-29)

• Add a method to the authentication backend so it is possible to customize the authorization based on SAML attributes.

0.9.0 (2012-10-30)

• Add a signal for modifying the user just before saving it on the update_user method of the authentication backend.

0.8.1 (2012-10-29)

• Trim the SAML attributes before setting them to the Django objects if they are too long. This fixes a crash with MySQL.

0.8.0 (2012-10-25)

• Allow to use different attributes besides ‘username’ to look for existing users.

0.7.0 (2012-10-19)

• Add a setting to decide if the user should be redirected to the next view or shown an authorization error when the user tries to login twice.

0.6.1 (2012-09-03)

• Remove Django from our dependencies

• Restore support for Django 1.3

0.6.0 (2012-08-29)

• Add tox support configured to run the tests with Python 2.6 and 2.7

• Fix some dependencies and sdist generation. Lorenzo Gil

• Allow defining a logout redirect url in the settings. Lorenzo Gil

• Add some logging calls to improve debugging. Lorenzo Gil

• Add support for custom conf loading function. Sam Bull.

• Make the tests more robust and easier to run when djangosaml2 is included in a Django project. Sam Bull.

• Make sure the profile is not None before saving it. Bug reported by Leif Johansson

0.5.0 (2012-05-22)

• Allow defining custom config loaders. They can be dynamic depending on the request.

• Do not automatically add the authentication backend. This way we allow other people to add their own backends.

• Support for additional attributes other than the ones that get mapped into the User model. Those attributes get stored in the UserProfile model.

0.4.2 (2012-03-23)

• Fix a crash in the idplist templatetag about using an old pysaml2 function

• Added a test for the previous crash

0.4.1 (2012-03-19)

• Upgrade pysaml2 dependency to version 0.4.1

0.4.0 (2012-03-18)

• Upgrade pysaml2 dependency to version 0.4.0 (update our tests as a result of this)

• Add logging calls to make debugging easier

• Use the Django configured logger in pysaml2

0.3.3 (2012-02-14)

• Freeze the version of pysaml2 since we are not (yet!) compatible with version 0.4.0

0.3.2 (2011-12-13)

• Avoid a crash when reading the SAML attribute that maps to the Django username

0.3.1 (2011-12-01)

• Load the config in the render method of the idplist templatetag to make it more flexible and reentrant.

0.3.0 (2011-11-30)

• Templatetag to get the list of available idps.

• Allow to map the same SAML attribute into several Django field.

0.2.4 (2011-11-29)

• Fix restructured text bugs that made pypi page looks bad.

0.2.3 (2011-06-14)

• Set a unusable password when the user is created for the first time

0.2.2 (2011-06-07)

• Prevent infinite loop when going to the /saml2/login/ endpoint and the user is already logged in and the settings.LOGIN_REDIRECT_URL is (badly) pointing to /saml2/login.

0.2.1 (2011-05-09)

• If no next parameter is supplied to the login view, use the settings.LOGIN_REDIRECT_URL as default

0.2.0 (2011-04-26)

• Python 2.4 compatible if the elementtree library is installed

• Allow post processing after the authentication phase by using Django signals.

0.1.1 (2011-04-18)

• Simple view to echo SAML attributes

• Improve documentation

• Change default behaviour when a new user is created. Now their attributes are filled this first time

• Allow to set a next page after the logout

0.1.0 (2011-03-16)

• Emancipation from the pysaml package