python3-saml

SAML Python3 Toolkit

Add SAML support to your Python software using this library. Forget those complicated libraries and use the open source library provided by the SAML tool community.

This version supports Python3. Python 2 support was deprecated on Jan 1st, 2020: python-saml

Warning

Version 1.16.X is the latest version supporting Python2, consider its use deprecated. 1.17 won't be Python2 and old Python3 compatible.

Version 1.13.0 sets sha256 and rsa-sha256 as default algorithms

Version 1.8.0 sets strict mode active by default

Update python3-saml to 1.5.0, this version includes security improvements for preventing XEE and Xpath Injections.

Update python3-saml to 1.4.0, this version includes a fix for the CVE-2017-11427 vulnerability.

This version also changes how the calculate fingerprint method works, and will expect as input a formatted X.509 certificate.

Update python3-saml to 1.2.6 that adds the use defusedxml that will prevent XEE and other attacks based on the abuse of XML. (CVE-2017-9672)

Update python3-saml to >= 1.2.1, 1.2.0 had a bug on signature validation process (when using wantAssertionsSigned and wantMessagesSigned). CVE-2016-1000251

1.2.0 version includes a security patch that contains extra validations that will prevent signature wrapping attacks.

``python3-saml 3.7

• xmlsec Python bindings for the XML Security Library.
• lxml Python bindings for the libxml2 and libxslt libraries.
• isodate An ISO 8601 date/time/ duration parser and formatter

Review the pyproject.toml file to know the version of the library that python3-saml is using

Code

Option 1. Download from GitHub

The toolkit is hosted on GitHub. You can download it from:

• Latest release: https://github.com/saml-toolkits/python3-saml/releases/latest
• Master repo: https://github.com/saml-toolkits/python3-saml/tree/master

Find the core of the library at src/onelogin/saml2 folder.

Option 2. Download from pypi

The toolkit is hosted in pypi, you can find the python3-saml package at https://pypi.python.org/pypi/python3-saml

You can install it executing:

$ pip install python3-saml

If you want to know how a project can handle python packages review this guide and review this sampleproject

NOTE

To avoid libxml2 library version incompatibilities between xmlsec and lxml it is recommended that lxml is not installed from binary.

This can be ensured by executing:

$ pip install --force-reinstall --no-binary lxml lxml

Security Warning

In production, the strict parameter MUST be set as "true". Otherwise your environment is not secure and will be exposed to attacks.

In production also we highly recommend to register on the settings the IdP certificate instead of using the fingerprint method. The fingerprint, is a hash, so at the end is open to a collision attack that can end on a signature validation bypass. Other SAML toolkits deprecated that mechanism, we maintain it for compatibility and also to be used on test environment.

Avoiding Open Redirect attacks

Some implementations uses the RelayState parameter as a way to control the flow when SSO and SLO succeeded. So basically the user is redirected to the value of the RelayState.

If you are using Signature Validation on the HTTP-Redirect binding, you will have the RelayState value integrity covered, otherwise, and on HTTP-POST binding, you can't trust the RelayState so before executing the validation, you need to verify that its value belong a trusted and expected URL.

Read more about Open Redirect CWE-601.

Avoiding Replay attacks

A replay attack is basically try to reuse an intercepted valid SAML Message in order to impersonate a SAML action (SSO or SLO).

SAML Messages have a limited timelife (NotBefore, NotOnOrAfter) that make harder this kind of attacks, but they are still possible.

In order to avoid them, the SP can keep a list of SAML Messages or Assertion IDs already validated and processed. Those values only need to be stored the amount of time of the SAML Message life time, so we don't need to store all processed message/assertion Ids, but the most recent ones.

The OneLogin_Saml2_Auth class contains the get_last_request_id, get_last_message_id and get_last_assertion_id methods to retrieve the IDs

Checking that the ID of the current Message/Assertion does not exists in the list of the ones already processed will prevent replay attacks.

Getting Started

Knowing the toolkit

The new SAML Toolkit contains different folders (certs, lib, demo-django, demo-flask and tests) and some files.

Let's start describing them:

src

This folder contains the heart of the toolkit, onelogin/saml2 folder contains the new version of the classes and methods that are described in a later section.

demo-django

This folder contains a Django project that will be used as demo to show how to add SAML support to the Django Framework. demo is the main folder of the Django project (with its settings.py, views.py, urls.py), templates is the Django templates of the project and saml is a folder that contains the certs folder that could be used to store the X.509 public and private key, and the SAML toolkit settings (settings.json and advanced_settings.json).

Notice about certs

SAML requires a X.509 cert to sign and encrypt elements like NameID, Message, Assertion, Metadata.

If our environment requires sign or encrypt support, the certs folder may contain the X.509 cert and the private key that the SP will use:

• sp.crt The public cert of the SP
• sp.key The private key of the SP

Or also we can provide those data in the setting file at the x509cert and the privateKey JSON parameters of the sp element.

Sometimes we could need a signature on the metadata published by the SP, in this case we could use the X.509 cert previously mentioned or use a new X.509 cert: metadata.crt and metadata.key.

Use sp_new.crt if you are in a key rollover process and you want to publish that X.509 certificate on Service Provider metadata.

If you want to create self-signed certs, you can do it at the https://www.samltool.com/self_signed_certs.php service, or using the command:

openssl req -new -x509 -days 3652 -nodes -out sp.crt -keyout sp.key

demo-flask

This folder contains a Flask project that will be used as demo to show how to add SAML support to the Flask Framework. index.py is the main Flask file that has all the code, this file uses the templates stored at the templates folder. In the saml folder we found the certs folder to store the X.509 public and private key, and the SAML toolkit settings (settings.json and advanced_settings.json).

demo_pyramid

This folder contains a Pyramid project that will be used as demo to show how to add SAML support to the Pyramid Web Framework. \_\_init__.py is the main file that configures the app and its routes, views.py is where all the logic and SAML handling takes place, and the templates are stored in the templates folder. The saml folder is the same as in the other two demos.

demo-tornado

This folder contains a Tornado project that will be used as demo to show how to add SAML support to the Tornado Framework. views.py (with its settings.py) is the main Flask file that has all the code, this file uses the templates stored at the templates folder. In the saml folder we found the certs folder to store the X.509 public and private key, and the SAML toolkit settings (settings.json and advanced_settings.json).

It requires python3.8 (it's using tornado 6.4.1)

tests

Contains the unit test of the toolkit.

In order to execute the test you only need to load the virtualenv with the toolkit installed on it properly:

make install-test

and execute:

make pytest

The previous line will run the tests for the whole toolkit. You can also run the tests for a specific module. To do so for the auth module you would have to execute this:

pytest tests/src/OneLogin/saml2_tests/auth_test.py::OneLogin_Saml2_Auth_Test

Or for an specific method:

pytest tests/src/OneLogin/saml2_tests/auth_test.py::OneLogin_Saml2_Auth_Test::testBuildRequestSignature

How It Works

Settings

First of all we need to configure the toolkit. The SP's info, the IdP's info, and in some cases, configure advanced security issues like signatures and encryption.

There are two ways to provide the settings information:

• Use a settings.json file that we should locate in any folder, but indicates its path with the custom_base_path parameter.

• Use a JSON object with the setting data and provide it directly to the constructor of the class (if your toolkit integation requires certs, remember to provide the custom_base_path as part of the settings or as a parameter in the constructor).

In the demo-django and in the demo-flask folders you will find a saml folder, inside there is a certs folder and a settings.json and advanced_settings.json file. Those files contain the settings for the SAML toolkit. Copy them in your project and set the correct values.

This is the settings.json file:

…

In addition to the required settings data (idp, sp), extra settings can be defined in advanced_settings.json:

…

In the security section, you can set the way that the SP will handle the messages and assertions. Contact the admin of the IdP and ask them what the IdP expects, and decide what validations will handle the SP and what requirements the SP will have and communicate them to the IdP's admin too.

Once we know what kind of data could be configured, let's talk about the way settings are handled within the toolkit.

The settings files described (settings.json and advanced_settings.json) are loaded by the toolkit if not other dict with settings info is provided in the constructors of the toolkit. Let's see some examples.

# Initializes toolkit with settings.json & advanced_settings.json files.
auth = OneLogin_Saml2_Auth(req)
# or
settings = OneLogin_Saml2_Settings()

# Initializes toolkit with settings.json & advanced_settings.json files from a custom base path.
custom_folder = '/var/www/django-project'
auth = OneLogin_Saml2_Auth(req, custom_base_path=custom_folder)
# or
settings = OneLogin_Saml2_Settings(custom_base_path=custom_folder)

# Initializes toolkit with the dict provided.
auth = OneLogin_Saml2_Auth(req, settings_data)
# or
settings = OneLogin_Saml2_Settings(settings_data)

You can declare the settings_data in the file that contains the constructor execution or locate them in any file and load the file in order to get the dict available as we see in the following example:

filename = "/var/ww