dm.saml2 3.2.3

SAML2 support based on PyXB

This package provides support for SAML2 based on pyxb.

pyxb (http://pypi.python.org/pypi/PyXB) generates a Python class collection for an XML schema and provides means to convert between associated Python instances and xml documents. It is used to generate and parse SAML2 messages.

The package adds support for digital signatures and SAML2 bindings and metadata management.

Dependencies

PyXB

Class collections generated by pyxb tend to be very version dependent. Thus, they must usually be regenerated when the pyxb version has changed.

The current package’s version mostly uses class collections from the wssplat and saml20 bundles of pyxb. Thus, they have a good chance to be updated together with pyxb. However, the pyxb saml2 bundle lacks support for the so called SAML2 context classes. This package contains class collections generated with pyxb==1.1.4. They need to be regenerated if the pyxb version changes (and you use those classes – which is not very likely). The gen.sh script in subpackage pyxb can provide clues how to regenerate them.

The original PyXB author (Peter A. Bigot) has abandoned the project. The latest release 1.2.6 is no longer compatible with modern Python versions (at least from Python 3.10 on). To handle this situation, dm.saml2 no longer declares the PyXB dependency in its setup.py. This allows the use a PyXB replacement, potentially named differently. If you want to use dm.saml2 with Python 3.10+, you must provide such a replacement.

I have not yet found a Python 3.10 compatible replacement with the required wssplat and saml20 bundles. For a customer project, I used the following approach: I started with the PyXB-CTC 1.3.0 source distribution, fixed there a few remaining Python 3.10 incompatibilities (essentially replacing references to collections by corresponding ones to collections.abc) and generated the missing wssplat and saml20 bundles.

dm.xmlsec.binding

Check its installation notes should you face related installation problems.

Example

This section provides a simple example on how to create, sign and verify an assertion with this package.

Always ensure, the xmlsec library is initialized. Otherwise, it signing/ signature verification can fail with dubious messages.

>>> import dm.xmlsec.binding as xmlsec
>>> xmlsec.initialize()

We now build an assertion as Python object.

>>> import pyxb.binding.datatypes as xs
>>> from dm.saml2.pyxb.assertion import (NameID, Assertion, Subject, \
...      AuthnStatement, AttributeStatement, AuthnContext, AuthnContextClassRef, \
...      Attribute, AttributeValue, \
...      CreateFromDocument
...                                      )
>>> from datetime import datetime
>>>
>>> issuer = NameID('http://bfd.de')
>>> ass = Assertion(issuer)
>>>
>>> subject = Subject(NameID('Dieter Maurer'))
>>>
>>> ass.Subject = subject
>>>
>>> authn = AuthnStatement(
...   None,
...   AuthnContext(AuthnContextClassRef('urn:oasis:names:tc:SAML2:2.0:ac:classes:Password')),
...   AuthnInstant=datetime.utcnow(),
...   )
>>>
>>> ass.AuthnStatement.append(authn)
>>>
>>> att = AttributeStatement(
...   # does not yet work perfectly -- needs further analysis
...   Attribute(xs.string('Dieter', _element=AttributeValue), Name='Firstname'),
...   Attribute(xs.string('Maurer', _element=AttributeValue), Name='Lastname'),
...   )
>>>
>>> ass.AttributeStatement.append(att)

Now it looks like this (not yet signed).

>>> unsigned_ass = ass.toxml()
>>> print unsigned_ass
<?xml version="1.0" ?><ns1:Assertion ID="_fb6dc6ac-9ee6-4a1f-8010-6dba6e0d9746" IssueInstant="2012-07-06T07:24:53.262859" Version="2.0" xmlns:ns1="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns2="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><ns1:Issuer>http://bfd.de</ns1:Issuer><ns1:Subject><ns1:NameID>Dieter Maurer</ns1:NameID></ns1:Subject><ns1:AuthnStatement AuthnInstant="2012-07-06T07:24:53.282142"><ns1:AuthnContext><ns1:AuthnContextClassRef>urn:oasis:names:tc:SAML2:2.0:ac:classes:Password</ns1:AuthnContextClassRef></ns1:AuthnContext></ns1:AuthnStatement><ns1:AttributeStatement><ns1:Attribute Name="Firstname"><ns1:AttributeValue xsi:type="ns2:string">Dieter</ns1:AttributeValue></ns1:Attribute><ns1:Attribute Name="Lastname"><ns1:AttributeValue xsi:type="ns2:string">Maurer</ns1:AttributeValue></ns1:Attribute></ns1:AttributeStatement></ns1:Assertion>

We define the signature context to support signing.

>>> from dm.saml2.signature import default_sign_context
>>> default_sign_context.add_key(xmlsec.Key.load('key.pem',  xmlsec.KeyDataFormatPem, None), issuer.value())

We request that ass gets signed on serialization, serialize and look at the result.

>>> ass.request_signature()
>>> signed = ass.toxml()
>>> print signed
<?xml version="1.0" ?><ns1:Assertion ID="_fb6dc6ac-9ee6-4a1f-8010-6dba6e0d9746" IssueInstant="2012-07-06T07:24:53.262859" Version="2.0" xmlns:ns1="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#" xmlns:ns3="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><ns1:Issuer>http://bfd.de</ns1:Issuer><ns2:Signature><ns2:SignedInfo><ns2:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/><ns2:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><ns2:Reference URI="#_fb6dc6ac-9ee6-4a1f-8010-6dba6e0d9746"><ns2:Transforms><ns2:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/><ns2:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></ns2:Transforms><ns2:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><ns2:DigestValue>6P0dLnMLJCe22YuRD1Mngiprz6k=</ns2:DigestValue></ns2:Reference></ns2:SignedInfo><ns2:SignatureValue>liaBBIVjk73x5spJrvfYg1Sa3VGnOqz0zqDKQr7qoLNg5/pzZ8llQEXQsbvw6zLh
26UnQ6D3KWvvabw9vpRqzLA21ykNUPqEGtZPMiQynvpdRSeTbg5ZyVBGYCL7ww19
MiEKryDwPI56I/3z4Le7KFZ4qpPPUptodQ4mm1PVsyA=</ns2:SignatureValue></ns2:Signature><ns1:Subject><ns1:NameID>Dieter Maurer</ns1:NameID></ns1:Subject><ns1:AuthnStatement AuthnInstant="2012-07-06T07:24:53.282142"><ns1:AuthnContext><ns1:AuthnContextClassRef>urn:oasis:names:tc:SAML2:2.0:ac:classes:Password</ns1:AuthnContextClassRef></ns1:AuthnContext></ns1:AuthnStatement><ns1:AttributeStatement><ns1:Attribute Name="Firstname"><ns1:AttributeValue xsi:type="ns3:string">Dieter</ns1:AttributeValue></ns1:Attribute><ns1:Attribute Name="Lastname"><ns1:AttributeValue xsi:type="ns3:string">Maurer</ns1:AttributeValue></ns1:Attribute></ns1:AttributeStatement></ns1:Assertion>

Now, we look how the verification can be done. We first set up a verification context.

>>> from dm.saml2.signature import default_verify_context
>>> default_verify_context.add_key(xmlsec.Key.load('pubkey.pem',  xmlsec.KeyDataFormatPem, None), issuer.value())

Calling CreateFromDocument will verify any (available) signatures and raise an exception when a verification fails. Verification always uses the Issuer to select the key from the verification context. To check whether a signature was verified at the instance, verified_signature can be called.

>>> verified_ass = CreateFromDocument(signed)
>>> verified_ass.verified_signature()
True

You can use pydoc, the Python builtin help or look at the source to find out more about this package.

Configuration

Starting with version 3.1, the package provides an elementary way to configure parts of the signature generation and verification process. This may become necessary when SAML partner entities have special requirements in this regard.

You do this kind of configuration by importing the module dm.saml2.config and overriding some of the variables defined there.

As an example, let us assume that one of your SAML2 partner entities uses DsaSha1 as the signature method (rather than the default RsaSha1). Without special configuration, the verification will fail. The xmlsec stack trace will give hints (somewhat cryptic) towards a disabled transform. The configuration to get those SAML2 messages verified could look like:

>>> from dm.saml2 import config
>>> from dm.xmlsec.binding import TransformDsaSha1
>>> config.signature_transforms += (TransformDsaSha1, )

This configuration tells the package that DsaSha1 is an acceptable signature method.

The configuration should happen once - before the first signature creation/verification.

Notes

Note that signature creation and verification will fail with an obscure error message from xmlsec when xmlsec is not properly initialized. Do not forget to call dm.xmlsec.binding.initialize().

History

3.2.3

This version is identical to 3.2.2 with the exception that it no longer declares its PyXB dependency in its setup.py. This allows the use of a (potentially differently named) PyXB replacement. Such a replacement becomes necessary for Python 3.10+ because the latest PyXB release is no longer compatible. For Python versions up to 3.9 use dm.saml2==3.2.2.

3.2

Python 3 compatibity

Added test suite

Fixes in the httpartifact binding.

3.1.3

Added a 10 s timeout in metadata.EntityByUrl.get_metadata_document. It can be changed by changing the variable ENTITY_BY_URL_TIMEOUT in module metadata.

3.1.2

Support (limited) type conversion in util.xs_convert_from_xml.

3.1.1

Adapt to the changed binding for “plural” elements (maxoccurs > 1) in newer PyXB versions.

3.1

Elementary configuration support for the signature generation/verification process.

Support for use of Sha256 and RsaSha256 as digest or signature method, respcectively.

3.0

Switch to datetime values explicitely in the UTC time zone (rather than naive datetime values which implicitely use the UTC time zone).

This also affects the lexical representation of SAML time values: they now use the Z timezone suffix.

2.1

Signature support for the HTTP redirect binding. Note: for this to work, you need at least version 1.3 of dm.xmlsec.binding which requires lxml >= 3.0; as Plone 4.x still uses lxml 2.x, this version dependency is not declared in setup.py.

2.0

Version 2.0 uses dm.xmlsec.binding as Python binding to the XML security library, rather then the no longer maintained pyxmlsec. This drastically facilitates installation.

1.0

Initial release based on pyxmlsec.