Django SAML2 Authentication

This plugin provides a simple way to integrate SAML2 Authentication into your Django-powered app. SAML SSO is a standard, so practically any SAML2 based SSO identity provider is supported.

This plugin supports both identity provider and service provider-initiated SSO:

• For IdP-initiated SSO, the user should sign in to their identity provider platform, e.g., Okta, and click on the application that authorizes and redirects the user to the service provider, that is your platform.
• For SP-initiated SSO, the user should first exist on your platform, either by signing in via the first method (IdP-initiated SSO) or any other custom solution. It can be configured to be redirected to the correct application on the identity provider platform.

For IdP-initiated SSO, the user will be created if it doesn't exist. Still, for SP-initiated SSO, the user should exist in your platform for the code to detect and redirect them to the correct application on the identity provider platform.

Project Information

• Original Author: Fang Li (@fangli)

• Maintainer: Mostafa Moradian (@mostafa)

• Version support matrix:

  Python	Django	django-saml2-auth
  3.7.x, 3.8.x, 3.9.x, 3.10.x	2.2.x	>=3.4.0
  3.7.x, 3.8.x, 3.9.x, 3.10.x	3.2.x	>=3.4.0
  3.8.x, 3.9.x, 3.10.x	4.0.x	>=3.4.0
  3.8.x, 3.9.x, 3.10.x	4.1.x	>=3.4.0

• Release logs are available here. The old release log file still exist, and will be removed in future releases.

• For contribution, read contributing guide.

CycloneDX SBOM

From v3.6.1, CycloneDX SBOMs will be generated for requirements.txt and requirements_test.txt and it can be accessed from the latest build of GitHub Actions for a tagged release, for example, this one. The artifacts are only kept for 90 days.

Donate

Please give us a shiny and help spread the word.

Installation

You can install this plugin via pip. Make sure you update pip to be able to install from git:

pip install grafana-django-saml2-auth

or from source:

git clone https://github.com/grafana/django-saml2-auth
cd django-saml2-auth
python setup.py install

xmlsec is also required by pysaml2, so it must be installed:

// RPM-based distributions
# yum install xmlsec1
// DEB-based distributions
# apt-get install xmlsec1
// macOS
# brew install xmlsec1

Windows binaries are also available.

How to use?

1. Once you have the library installed or in your requirements.txt, import the views module in your root urls.py:

   import django_saml2_auth.views

2. 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/", "^sso_auth/", "^sso_login/", etc. (required)
   url(r'^sso/', include('django_saml2_auth.urls')),
   
   # The following line will replace the default user login with SAML2 (optional)
   # If you want to specific the after-login-redirect-URL, use parameter "?next=/the/path/you/want"
   # with this view.
   url(r'^accounts/login/$', django_saml2_auth.views.signin),
   
   # The following line will replace the admin login with SAML2 (optional)
   # If you want to specific the after-login-redirect-URL, use parameter "?next=/the/path/you/want"
   # with this view.
   url(r'^admin/login/$', django_saml2_auth.views.signin),

3. Add 'django_saml2_auth' to INSTALLED_APPS in your django settings.py:

   INSTALLED_APPS = [
       '...',
       'django_saml2_auth',
   ]

4. In settings.py, add the SAML2 related configuration:

   Please note, the only required setting is METADATA_AUTO_CONF_URL or the existence of a GET_METADATA_AUTO_CONF_URLS trigger function. The following block shows all required and optional configuration settings and their default values.

   SAML2_AUTH = {
       # Metadata is required, choose either remote url or local file path
       'METADATA_AUTO_CONF_URL': '[The auto(dynamic) metadata configuration URL of SAML2]',
       'METADATA_LOCAL_FILE_PATH': '[The metadata configuration file path]',
   
       'DEBUG': False,  # Send debug information to a log file
   
       # Optional settings below
       'DEFAULT_NEXT_URL': '/admin',  # Custom target redirect URL after the user get logged in. Default to /admin if not set. This setting will be overwritten if you have parameter ?next= specificed in the login URL.
       'CREATE_USER': True,  # Create a new Django user when a new user logs in. Defaults to True.
       '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': False,  # 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': 'user.email',
           'username': 'user.username',
           'first_name': 'user.first_name',
           'last_name': 'user.last_name',
           'token': 'Token',  # Mandatory, can be unrequired if TOKEN_REQUIRED is False
           'groups': 'Groups',  # Optional
       },
       'GROUPS_MAP': {  # Optionally allow mapping SAML2 Groups to Django Groups
           'SAML Group Name': 'Django Group Name',
       },
       'TRIGGER': {
           # Optional: needs to return a User Model instance or None
           'GET_USER': 'path.to.your.get.user.hook.method',
           'CREATE_USER': 'path.to.your.new.user.hook.method',
           'BEFORE_LOGIN': 'path.to.your.login.hook.method',
           'AFTER_LOGIN': 'path.to.your.after.login.hook.method',
           # Optional. This is executed right before METADATA_AUTO_CONF_URL.
           # For systems with many metadata files registered allows to narrow the search scope.
           'GET_USER_ID_FROM_SAML_RESPONSE': 'path.to.your.get.user.from.saml.hook.method',
           # This can override the METADATA_AUTO_CONF_URL to enumerate all existing metadata autoconf URLs
           'GET_METADATA_AUTO_CONF_URLS': 'path.to.your.get.metadata.conf.hook.method',
       },
       'ASSERTION_URL': 'https://mysite.com',  # Custom URL to validate incoming SAML requests against
       'ENTITY_ID': 'https://mysite.com/saml2_auth/acs/',  # Populates the Issuer element in authn request
       'NAME_ID_FORMAT': FormatString,  # Sets the Format property of authn NameIDPolicy element, e.g. 'user.email'
       'USE_JWT': True,  # Set this to True if you are running a Single Page Application (SPA) with Django Rest Framework (DRF), and are using JWT authentication to authorize client users
       'JWT_ALGORITHM': 'HS256',  # JWT algorithm to sign the message with
       'JWT_SECRET': 'your.jwt.secret',  # JWT secret to sign the message with
       'JWT_PRIVATE_KEY': '--- YOUR PRIVATE KEY ---',  # Private key to sign the message with. The algorithm should be set to RSA256 or a more secure alternative.
       'JWT_PRIVATE_KEY_PASSPHRASE': 'your.passphrase',  # If your private key is encrypted, you might need to provide a passphrase for decryption
       'JWT_PUBLIC_KEY': '--- YOUR PUBLIC KEY ---',  # Public key to decode the signed JWT token
       'JWT_EXP': 60,  # JWT expiry time in seconds
       'FRONTEND_URL': 'https://myfrontendclient.com',  # Redirect URL for the client if you are using JWT auth with DRF. See explanation below
       'LOGIN_CASE_SENSITIVE': True,  # whether of not to get the user in case_sentive mode
       'AUTHN_REQUESTS_SIGNED': True, # Require each authentication request to be signed
       'LOGOUT_REQUESTS_SIGNED': True,  # Require each logout request to be signed
       'WANT_ASSERTIONS_SIGNED': True,  # Require each assertion to be signed
       'WANT_RESPONSE_SIGNED': True,  # Require response to be signed
       'ACCEPTED_TIME_DIFF': None,  # Accepted time difference between your server and the Identity Provider
       'ALLOWED_REDIRECT_HOSTS': ["https://myfrontendclient.com"], # Allowed hosts to redirect to using the ?next parameter
       'TOKEN_REQUIRED': True,  # Whether or not to require the token parameter in the SAML assertion
   }

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

Module Settings

Triggers

JWT Signing Algorithm and Settings

Both symmetric and asymmetric signing functions are supported. If you want to use symmetric signing using a secret key, use either of the following algorithms plus a secret key:

• HS256
• HS384
• HS512

{
    ...
    'USE_JWT': True,
    'JWT_ALGORITHM': 'HS256',
    'JWT_SECRET': 'YOU.ULTRA.SECURE.SECRET',
    ...
}

Otherwise if you want to use your PKI key-pair to sign JWT tokens, use either of the following algorithms and then set the following fields:

• RS256
• RS384
• RS512
• ES256
• ES256K
• ES384
• ES521
• ES512
• PS256
• PS384
• PS512
• EdDSA

{
    ...
    'USE_JWT': True,
    'JWT_ALGORITHM': 'RS256',
    'JWT_PRIVATE_KEY': '--- YOUR PRIVATE KEY ---',
    'JWT_PRIVATE_KEY_PASSPHRASE': 'your.passphrase',  # Optional, if your private key is encrypted
    'JWT_PUBLIC_KEY': '--- YOUR PUBLIC KEY ---',
    ...
}

Note: If both PKI fields and JWT_SECRET are defined, the JWT_ALGORITHM decides which method to use for signing tokens.

Custom token triggers

This is an example of the functions that could be passed to the TRIGGER.CUSTOM_CREATE_JWT (it uses the DRF Simple JWT library) and to TRIGGER.CUSTOM_TOKEN_QUERY:

from rest_framework_simplejwt.tokens import RefreshToken


def get_custom_jwt(user):
    """Create token for user and return it"""
    return RefreshToken.for_user(user)


def get_custom_token_query(refresh):
    """Create url query with refresh and access token"""
    return "?%s%s%s%s%s" % ("refresh=", str(refresh), "&", "access=", str(refresh.access_token))

Customize Error Messages

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

To override these pages put a template named 'django_saml2_auth/error.html', 'django_saml2_auth/welcome.html' or 'django_saml2_auth/denied.html' in your project's template folder.

If a 'django_saml2_auth/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.views.signout),

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

To override the built in signout page put a template named 'django_saml2_auth/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.

More information can be found in the Okta Developer Documentation.

Release Process

I adopted a reasonably simple release process, which is almost automated, except for two actions that needed to be taken to start a release:

1. Update setup.py and increase the version number in the setup function. Unless something backward-incompatible is introduced, only the minor version is upgraded: 3.8.0 becomes 3.9.0.
2. Tag the main branch with the the vSEMVER, e.g. v3.9.0, and git-push the tag.
3. The release and publish to PyPI is handled in the CI/CD using GitHub Actions.
4. Create a new release with auto-generated (and polished) release notes on the tag.
5. Download SBOM artifacts generated by GitHub Actions for the corresponding run, and add them to the release files.