djangosaml2 0.1.0

pysaml2 integration in Django

Contents

• djangosaml2

  • Installation

  • Configuration

    • Changes in the settings.py file

    • Changes in the urls.py file

    • PySAML2 specific files and configuration

    • User attributes

  • IdP setup

  • FAQ

  • Changes

djangosaml2

djangosaml2 is a Django application that integrates the PySAML2 library into your project. This mean that you can protect your Django based project with a service provider based on PySAML. This way it will talk SAML2 with your Identity Provider allowing you to use this authentication mechanism. This document will guide you through a few simple steps to accomplish such goal.

Installation

PySAML2 uses xmlsec1 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.

Now you can install the djangosaml2 package using easy_isntall or pip. This will also install PySAML2 and its dependencies automatically.

Configuration

There are three things you need to setup to make djangosaml2 works in your Django project:

1. settings.py as you may already know, it is the main Django configuration file.

2. urls.py is the file where you will include djangosaml2 urls.

3. pysaml2 specific files such as a attribute map directory and a certificate.

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.

Note

When you finish the configuation you can run the djangosaml2 test suite as you run any other Django application test suite. Just type python manage.py test djangosaml2

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.

Note

The login url starts with /saml2/ as an example but you can change that if you want. Check the section about changes in the urls.py file for more information.

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': '[e-mail]',
       'contact_type': 'technical'},
      {'given_name': 'Angel',
       'sur_name': 'Fernandez',
       'company': 'Yaco Sistemas',
       'email_address': '[e-mail]',
       '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
  }

Note

Please check the PySAML2 documentation for more information about these and other configuration options.

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.

Note

Check your openssl documentation to generate a test certificate but don’t forget to order a real one when you go into production.

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. 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.

IdP setup

Congratulations, you have finished configuring the SP side of the federation. Now you need to send the entity id and the metadata of this new SP to the IdP administrators so they can add it to their list of trusted services.

You can get this information starting your Django development server and going to the http://localhost:8000/saml2/metadata url. If you have included the djangosaml2 urls under a different url prefix you need to correct this url.

FAQ

Why can’t SAML be implemented as an Django Authentication Backend?

well SAML authentication is not that simple as a set of credentials you can put on a login form and get a response back. Actually the user password is not given to the service provider at all. This is by design. You have to delegate the task of authentication to the IdP and then get an asynchronous response from it.

Given said that, djangosaml2 does use a Django Authentication Backend to transform the SAML assertion about the user into a Django user object.

Why not put everything in a Django middleware class and make our lifes easier?

Yes, that was an option I did evaluate but at the end the current design won. In my opinion putting this logic into a middleware has the advantage of making it easier to configure but has a couple of disadvantages: first, the middleware would need to check if the request path is one of the SAML endpoints for every request. Second, it would be too magical and in case of a problem, much harder to debug.

Changes

0.1.0 (2011-03-16)

• Emancipation from the pysaml package