.. contents::
SAML2 is a single sign on standard. It allows for the following use cases (depending how its configured)
All this is done via redirects in the browser with no direct connection needed between the two web servers. This means, unlike LDAP you can have an external website be authenticated by an internal intranet SAML2 complaint identity provider (such as ADFS) without having to setup a VPN connection between the servers.
It doesn't provide a way to search users or groups. It's not a directory service. Anything in plone that requires listing users or groups will not give you accurate information.
This plugin is mainly a wrapper around dm.zope.saml2
to aid in installation
for a Plone environment. All the hard work is done by Dieter Maurer's excellent
dm.zope.saml2
.
This plugin does the following so far
dm.zope.saml2
_ are installedexample buildout
_ to build all the dependencies standalonedm.zope.saml2
_In the future we hope to also include a control panel to
metadata
_ urls)Unfortunately dm.zope.saml2
_ was written requiring many dependencies some of
which are c-extensions requiring some libraries.
dm.saml2
_dm.reuse
_dm.zope.schema
_dm.xmlsec.binding
_PyXB
_xmlsec1
_lxml
_openssl
_ (although other encryption libraries can be used)There is an example buildout
_ to compile all these components from source
if you want a completely standalone solution.
First you need to decide if you want your Plone to be an IdP or an SP.
An IdP means the users and passwords will be stored in your Plone site and other services will be configured to redirect to Plone to be able to login into their respective sites.
An SP means that you won't store users and passwords locally and instead your
users will be redirected to another site (the IdP) during the login process to
be authenticated. Examples of alternative IdP's might be Microsoft Active Directory Federated services
(ADFS
) or Shibboleth
_, or another Plone site configured
as an IdP.
Regardless if you are going to be an IdP or SP you will need a single authority
object. This object contains assertions about what your service can do and
what other services can do. It also provides a public url to a XML Metadata
_ file
that contains the SAML2 assertions.
metadata
_ url you will give to the owners of
other servicesNext you will need to configure the other services that you will collaborate with. If you are an SP these will be IdP's that the user can choose to login into your service via. If you are an IdP these will be the SP's that are allowed to login via your site.
If Plone is going to be your IdP do the following
saml2idp
but it doesn't really matter. This id will appear
in the url of some of the urls used as part of the authentication process.If your IdP isn't a Plone site you will need to consult their documentation on how it needs to be configured.
If your Plone is going to be your SP do the following
saml2sp
. Again id doesn't really matter.saml2sp
is the top plugin.
This means that if an UnAuthorized exception is thrown in Plone
the saml2 plugin will be used and the user will be directed to select a IdP
to login via. If this isn't done Plone's normal login page will display
and the only way to instigate a SAML login sequence is via the explicit
login url. The explicit login url in this case would be
'acl_users/saml2sp/login'.If your Plone is the IdP and you are setting up another service as the SP you will need to look at the documentation of your SP on how to configure it.
Now that you have a working IdP and SP you will need to authorise them so they will work together. The SAML2 protocol is such that a IdP needs to know about the SP and visa versa for the authentication requests to work.
Providers can be configured to authorise each other in different ways however
dm.zope.saml2
ONLY supports the metadata
method. Your Plone site has
a web accessible url to a metadata
file that contains all the information
the other providers need to authorise the Plone site. Likewise your other providers
will need to provide a url to a metadata
file that your Plone site can access.
Periodically your Plone site will download this file. The
file is then cached locally. The metadata
_ contains the information about what
kind of service and urls are needed or offered for the interaction.
Note that the actual SAML2 authentication exchange doesn't require the SP and IdP
to be directly connected, just that the end users browser be able to access both.
However the metadata
exchange does require direct connectivity between the services.
If you don't have direct connectivity this can be
worked around by moving your metadata files on a different webserver. Note however
that your metadata
file generated by Plone has an expiry date in it.
You will need to periodically update your metadata
_ file to ensure the expiry date
is in the future.
To configure another provider (SP or IdP) to authorise your Plone site
metadata
url. This is found by clicking on the "metadata
"
tab inside the saml2auth object. Due to something strange with iframes you
will likely have to open this url in a new window/tab to see the XML properly.
The url is the url to your saml authority object + '/metadata'.
Note that you will get an error like "DOMGenerationError: Binding value inconsistent with content model"
if you try to access this url before you have done step 2 or 3.You might find that your provider doesn't support the metadata
standard
as this is optional. Many implementations that claim to be SAML2 compliant
but have retained the old way of doing configuration.
In this case you will need to learn to read the metadata
file to get the urls and settings from it that your IdP will need.
To configure your Plone site to authorize another provider (SP or IdP)
If your provider doesn't support the metadata
standard you will need to
manually generate a metadata file and place it in a web accessible location.
Once you've done that, follow the above steps. For example here is documentation
on creating metadata files for shibboleth
To test an IdP you will need a SP. You can use another Plone site (same one won't work) or another SAML2 SP. To test an SP you will need a IdP. You can use another Plone site or another SAML2 SP.
It's possible to create two Plone sites in the same instance and authorise one to authenticate via the other.
If you set your Plone site up as an IdP then you make member attributes or arbritrary data available to the SP's.
saml2idp
of type
'Saml simple idpsso with integrated attribute provider'. Open this.SAML Attribute Query
_.TODO
c.saml2 overrides the IRelayStateStore implementation for the idpsso so as to store the original SAML request during the login process. Instead of storing it in the database incurring a transaction for each login attempt, it stores it back in the users browsers in a cookie.
c.saml2 also makes the call to 'dm.xmlsec.binding.initialize()' on zope startup
refered to in the dm.zope.saml2
implementation. This means that currently
c.saml2 is hard-coded to use openssl. In future this might be made configurable
via an environment variable, otherwise try setting this yourself as per
dm.xmlsec.binding
_ documentation.
Some SAML2 SP's expect to see both key and signature passed back in the authentication response.
The key is compared against one store locally on the SP to ensure its the correct one.
dm.zope.saml2
_ doesn't support this, instead expecting the key to be shared
and updated via the metadata url.
dm.zope.saml2
_ doesn't support SAML 2.0 Single Logout.
If you get 'DOMGenerationError: Binding value inconsistent with content model' exception when viewing your own metadata url. Ensure your ipdsso or spsso objects are created first.
If you get a 'ComponentLookupError: (
You may also get a
'ComponentLookupError: (
You may experience errors compiling and/or running the software on CentOS. These GitHub issues mention some errors you might expect to encounter, and pointers how to solve them:
Most of it is to do with the dm.xmlsec.binding
package.
Dieter Maurer
_ for the excellent dm.zope.saml2 which does all the work.
Work on collective.saml2 is so far sponsored by PretaGov
_.
.. _example buildout: https://github.com/collective/collective.saml2/blob/master/buildout.cfg .. _dm.zope.saml2: https://pypi.python.org/pypi/dm.zope.saml2 .. _dm.reuse: https://pypi.python.org/pypi/dm.reuse .. _dm.saml2: https://pypi.python.org/pypi/dm.saml2 .. _dm.xmlsec.binding: https://pypi.python.org/pypi/dm.xmlsec.binding .. _dm.zope.schema: https://pypi.python.org/pypi/dm.zope.schema .. _PyXB: https://pypi.python.org/pypi/PyXB .. _lxml: https://pypi.python.org/pypi/lxml .. _xmlsec1: http://www.aleksey.com/xmlsec/ .. _openssl: http://www.openssl.org/ .. _PretaGov: http://www.pretagov.com.au .. _Dieter Maurer:http://www.dieter.handshake.de/ .. _Shibboleth: http://shibboleth.net/ .. _ADFS: http://en.wikipedia.org/wiki/Active_Directory_Federation_Services .. _Microsoft Active Directory Federated services: http://en.wikipedia.org/wiki/Active_Directory_Federation_Services .. _metadata: http://en.wikipedia.org/wiki/SAML_2.0#SAML_2.0_Metadata .. _Metadata: http://en.wikipedia.org/wiki/SAML_2.0#SAML_2.0_Metadata .. _metadata files for shibboleth: https://wiki.shibboleth.net/confluence/display/SHIB2/MetadataForSP .. _SAML Attribute Query: http://en.wikipedia.org/wiki/SAML_2.0#SAML_Attribute_Query