django-saml2-auth-custom 1.0.4

Dependencies

This plugin is compatible with Django 1.6/1.7/1.8/1.9. The pysaml2 Python module is required.

Install

You can install this plugin via pip:

# pip install django_saml2_auth_custom

or from source:

# git clone
# cd django-saml2-auth
# python setup.py install

xmlsec is also required by pysaml2:

# yum install xmlsec1
// or
# apt-get install xmlsec1

What does this plugin do?

This plugin takes over Django’s login page and redirect the user to a SAML2 SSO authentication service. Once the user is logged in and redirected back, the plugin will check if the user is already in the system. If not, the user will be created using Django’s default UserModel, otherwise the user will be redirected to their last visited page.

How to use?

1. Override the default login page in the root urls.py file, by adding these lines BEFORE any urlpatterns:

   # These are the SAML2 related URLs. You can change "^saml2_auth/" regex to
   # any path you want, like "^sso_auth/", "^sso_login/", etc. (required)
   url(r'^saml2_auth/', include('django_saml2_auth_custom.urls')),
   
   # The following line will replace the default user login with SAML2 (optional)
   url(r'^accounts/login/$', 'django_saml2_auth_custom.views.signin'),
   
   # The following line will replace the admin login with SAML2 (optional)
   url(r'^admin/login/$', 'django_saml2_auth_custom.views.signin'),

2. Add ‘django_saml2_auth_custom’ to INSTALLED_APPS

   INSTALLED_APPS = [
       '...',
       'django_saml2_auth_custom',
   ]

3. In settings.py, add the SAML2 related configuration.

   Please note, the only required setting is METADATA_AUTO_CONF_URL. The following block shows all required and optional configuration settings and their default values.

   SAML2_AUTH = {
       # Required setting
       'METADATA_AUTO_CONF_URL': '[The auto(dynamic) metadata configuration URL of SAML2]',
   
       # Optional settings
       'NEW_USER_PROFILE': {
           'USER_GROUPS': [],  # The default group name when a new user logs in
           'ACTIVE_STATUS': True,  # The default active status for new users
           'STAFF_STATUS': True,  # The staff status for new users
           'SUPERUSER_STATUS': False,  # The superuser status for new users
       },
       'ATTRIBUTES_MAP': {  # Change Email/UserName/FirstName/LastName to corresponding SAML2 userprofile attributes.
           'email': 'Email',
           'username': 'UserName',
           'first_name': 'FirstName',
           'last_name': 'LastName',
       },
       'TRIGGER': {
           'CREATE_USER': 'path.to.your.new.user.hook.method',
           'BEFORE_LOGIN': 'path.to.your.login.hook.method',
       },
   }

4. In your SAML2 SSO identity provider, set the Single-sign-on URL and Audience URI(SP Entity ID) to http://your-domain/saml2_auth/acs/

Customize

The default permission denied page and user welcome page can be overridden.

To override these pages put a template named ‘django_saml2_auth_custom/welcome.html’ or ‘django_saml2_auth_custom/denied.html’ in your project’s template folder.

If a ‘django_saml2_auth_custom/welcome.html’ template exists, that page will be shown to the user upon login instead of the user being redirected to the previous visited page. This welcome page can contain some first-visit notes and welcome words. The Django user object is available within the template as the user template variable.

To enable a logout page, add the following lines to urls.py, before any urlpatterns:

# The following line will replace the default user logout with the signout page (optional)
url(r'^accounts/logout/$', 'django_saml2_auth_custom.views.signout'),

# The following line will replace the default admin user logout with the signout page (optional)
url(r'^admin/logout/$', 'django_saml2_auth_custom.views.signout'),

To override the built in signout page put a template named ‘django_saml2_auth_custom/signout.html’ in your project’s template folder.

If your SAML2 identity provider uses user attribute names other than the defaults listed in the settings.py ATTRIBUTES_MAP, update them in settings.py.

For Okta Users

I created this plugin originally for Okta.

The METADATA_AUTO_CONF_URL needed in settings.py can be found in the Okta web UI by navigating to the SAML2 app’s Sign On tab, in the Settings box. You should see :

Identity Provider metadata is available if this application supports dynamic configuration.

The Identity Provider metadata link is the METADATA_AUTO_CONF_URL.