SAML Python Toolkit

Python 2 was deprecated on January 1, 2020. We recommend to migrate your project
to Python 3 and use python3-saml

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

This version supports Python2. There is a separate version that supports Python3: python3-saml.

Warning

Version 2.7.0 sets strict mode active by default

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

Update python-saml to 2.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 python-saml to 2.2.3, this version replaces some etree.tostring calls, that were introduced recently, by the sanitized call provided by defusedxml

Update python-saml to 2.2.0, this version includes a security patch that contains extra validations that will prevent signature wrapping attacks. CVE-2016-1000252

python-saml < v2.2.0 is vulnerable and allows signature wrapping!

Security Guidelines

If you believe you have discovered a security vulnerability in this toolkit, please report it by mail to the maintainer: sixto.martin.garcia+security@gmail.com

Why add SAML support to my software?

SAML is an XML-based standard for web browser single sign-on and is defined by the OASIS Security Services Technical Committee. The standard has been around since 2002, but lately it is becoming popular due its advantages:

• Usability - One-click access from portals or intranets, deep linking, password elimination and automatically renewing sessions make life easier for the user.
• Security - Based on strong digital signatures for authentication and integrity, SAML is a secure single sign-on protocol that the largest and most security conscious enterprises in the world rely on.
• Speed - SAML is fast. One browser redirect is all it takes to securely sign a user into an application.
• Phishing Prevention - If you don’t have a password for an app, you can’t be tricked into entering it on a fake login page.
• IT Friendly - SAML simplifies life for IT because it centralizes authentication, provides greater visibility and makes directory integration easier.
• Opportunity - B2B cloud vendor should support SAML to facilitate the integration of their product.

General Description

SAML Python toolkit lets you turn your Python application into a SP (Service Provider) that can be connected to an IdP (Identity Provider).

Supports:

• SSO and SLO (SP-Initiated and IdP-Initiated).
• Assertion and nameId encryption.
• Assertion signatures.
• Message signatures: AuthNRequest, LogoutRequest, LogoutResponses.
• Enable an Assertion Consumer Service endpoint.
• Enable a Single Logout Service endpoint.
• Publish the SP metadata (which can be signed).

Key features:

• saml2int - Implements the SAML 2.0 Web Browser SSO Profile.
• Session-less - Forget those common conflicts between the SP and the final app, the toolkit delegate session in the final app.
• Easy to use - Programmer will be allowed to code high-level and low-level programming, 2 easy to use APIs are available.
• Tested - Thoroughly tested.
• Popular - Developers use it. Add easy support to your Django/Flask/Bottle/Pyramid web projects.

Installation

Dependencies

• python 2.7
• lxml Python bindings for the libxml2 and libxslt libraries.
• dm.xmlsec.binding Cython/lxml based binding for the XML security library (depends on python-dev libxml2-dev libxmlsec1-dev)
• isodate An ISO 8601 date/time/duration parser and formater
• defusedxml XML bomb protection for Python stdlib modules

Review the setup.py file to know the version of the library that python-saml is using

OSX Dependencies

• python 2.7
• libxmlsec1

# using brew
$ brew install libxmlsec1

Code

Option 1. Download from Github

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

• Lastest release: https://github.com/SAML-Toolkits/python-saml/releases/latest
• Master repo: https://github.com/SAML-Toolkits/python-saml/tree/master

Copy the core of the library (src/onelogin/saml2 folder) and merge the setup.py inside the Python application. (Each application has its structure so take your time to locate the Python SAML toolkit in the best place).

Option 2. Download from pypi

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

You can install it executing:

$ pip install python-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 alredy valdidated 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 lis of the ones already processed will prevent replay attacks.

Getting Started

Knowing the toolkit

The SAML Toolkit contains different folders (cert, lib, demo-django, demo-flask, demo-bottle 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 saml.key

demo-bottle

This folder contains a Bottle project that will be used as demo to show how to add SAML support to the Bottle Framework. index.py contains all the logic of the demo project, templates is the Bottle 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).

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.

setup.py

Setup script is the centre of all activity in building, distributing, and installing modules. Read more at https://pythonhosted.org/an_example_pypi_project/setuptools.html

tests

Contains the unit test of the toolkit.

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

pip install -e ".[test]"

that will install dependences that the test requires.

and later execute:

python setup.py test

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:

python setup.py test --test-suite tests.src.OneLogin.saml2_tests.auth_test.OneLogin_Saml2_Auth_Test

With the --test-suite parameter you can specify the module to test. You'll find all the module available and their class names at tests/src/OneLogin/saml2_tests/

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, demo-flask, demo-pyramid and demo-bottle folders you will find a saml folder, inside there is a certs folder and a settings.json and a advanced_settings.json files. Those files contain the settings