dm.saml2 3.2.3
SAML2 support based on PyXB
License: BSD
Keywords: saml2 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 <https://github.com/pabigot/pyxb/blob/next/README.md>`_.
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 <https://pypi.org/project/pyxb-ctc/>`_, 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``.