dm.saml2 3.1.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

This package’s version has been tested with version 1.1.4 of pyxb. It may not work with other versions.

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.

A bug in pyxb 1.1.4 (http://sourceforge.net/apps/trac/pyxb/ticket/130#comment:4) prevents its installation via package managers (such as easy_install, pip, zc.buildout) for Python versions without os.path.relpath (this applies e.g. to Python 2.4). I work around this problem by downloading the pyxb source, apply patch http://sourceforge.net/apps/trac/pyxb/attachment/ticket/130/pyxb_setup.patch to it and then egg install the result. After this, dm.saml2 can be installed normally.

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