SAML authentication for plone sites
Project description
wcs.samlauth
wcs.samlauth is a saml authentication plugin based on python3-saml for plone 6. It turns your plone site into a SP (Service Provider). IDP (Identity Provider) is not supported.
The package is tested with plone 6.x and python 3.11/3.12. It does not officially support other versions.
Goal
Make it as easy as possible to configure plone as a SP (Service Provider), without having a in depth knowledge of SAML and how it works under the hood. This package uses the high level API of python3-saml, which makes it easy to configure and use.
TL;DR
- Install wcs.samlauth plugin
- Add PAS plugin via ZMI (in acl_users)
- Go to http://localhost:8080/Plone/acl_users/saml/idp_metadata
- Fetch or upload IDP metadata -> Click "Get and store metadata"
- Go to http://localhost:8080/Plone/acl_users/saml/metadata and configure your IDP
- Use http://localhost:8080/Plone/acl_users/saml/sls to login via IDP
Architecure
The plugin is based on a similar architecture/concept as pas.plugins.oidc. It basically means that all endpoints are directly on the plugin. The plugin does not override plones login/logout views. This is up to you. If you only have one saml plugin it's possible to enable the Challenge plugin, which redirects to the saml login endpoint.
This enables you to add multiple saml plugins as well.
Dependecies:
See python3-saml Make especially sure the following packages can be installed, since the have some system dependencies as well:
For example, on a recent Ubuntu, you should run:
apt install pkg-config libxml2-dev libxmlsec1-dev libxmlsec1-openssl
Endpoints
Given the ID of the SAML plugin is "saml":
- Expose SP metadata on http://localhost:8080/Plone/acl_users/saml/metadata
- the SP metadata is partially generated and partially static. entityId, assertionConsumerService and singleLogoutService are generated
- SAML Login endpoint is http://localhost:8080/Plone/acl_users/saml/sls
- SAML ACS endpoint is http://localhost:8080/Plone/acl_users/saml/acs
- SAML Logout endpoint is http://localhost:8080/Plone/acl_users/saml/slo
- SAML SP initiated logout endpoint http://localhost:8080/Plone/acl_users/saml/logout
- Fetch IDP metadata http://localhost:8080/Plone/acl_users/saml/idp_metadata
Features
- Fetch and store IDP metadata via IDP metadata endpoint
- Upload and store IDP metadata via file upload
- Multiple saml plugins at the same time
- Implements almost everything from python3-saml, this includes SP signing of the AuthnRequest and metadata
- Create a plone session and/or restapi token
- Enable/Disable the creation of a plone user
- Automatically updates user data (hardcoded, currently limited to email and fullname)
- Enable/Disable the validation of authn requests (Uses temporarly a
__saml
cookie) - Prevent Redirect attacks, by validating the RelayState parameter and a and an "allowed" list of domains, where we can redirect to
- E2E tests with Keykloak as IDP in different configuration variations
- Manually tested with Azure AD as IDP
- Documentation use azure and keycloak as IDP
Installation
Add plugin to your buildout
[buildout]
...
eggs =
wcs.samlauth
Add wcs.samlauth to plone docker image
$ docker run -p 8080:8080 -e SITE="mysite" -e ADDONS="wcs.samlauth" plone
From the ZMI go to acl_users
and add the saml plugin.
Development
It's best to use a local IDP, for example keycloak in order to make changes to this package.
Start a local keycloak server using docker:
$ docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:22.0.2 start-dev
Install and run a test plone instance:
$ git clone git@github.com:webcloud7/wcs.samlauth.git && cd wcs.samlauth
$ make install
$ make run
Test
You need a local docker installation to run tests.
The package provides a docker test layer, which spins up keycloak and loads various configuration files into keycloak.
$ make test
Run individual tests:
$ ./bin/test -t test_whatever
HowTo's
The tests/assets folder contains some keycloak configurations you can use for your test setup. It inclues examples with SP signed autn requests and metadata.
The examples below do not use this specific saml feature which is required by most IDP.
Manuall configuiration
You can configure everythin manully as well. Please see the python3-saml documentation for details
The configuration needs to be applied directly on the property tab of the saml plugin.
Configure with keycloak as IDP
For both create a new saml pas plugin via ZMI in acl_users
IDP part on keycloak
-
Login to your Keycloak admin console.
-
Create a new realm or use one that's already there. If not there create a test user.
-
With the data from http://localhost:8080/Plone/acl_users/saml/metadata create a new Client.
Client type is SAML.
Important note here: The client ID is identical to the SAML
EntityID
For example http://localhost:8080/keycloak/acl_users/saml/metadataClick "next"
-
Configure Home URL and Valid redirect URLs
Click "Save"
-
Go to "Keys" tab and disable "Client signature required"
-
Configure attribute bindings
Unter "Client scopes" click on URL which ends with /metadata-dedicated
Click on "Add predefined mapper"
Chose the following mappers
Click "Add"
-
Go to the Advance tab and configure the logout service redirect binding (python3-saml only supports the redirect binding here)
-
Copy the metadataa saml config URL
SP part on your Plone site
-
Go to URL: http://localhost:8080/Plone/acl_users/saml/idp_metadata
Enter the Url and Click on "Get and store metadata"
Hints: Keycloak has
authnRequestsSigned: true
hardcoded.
THATS IT!! Go To http://localhost:8080/Plone/acl_users/saml/sls to login via azure
If this is the only saml plugin on your site and want all users to login via saml, then you can enable the Challenge Plugin and change the login and logout actions on your plone site to use the saml endpoints.
Configure with Azure as IDP
This is a tutorial how to configure an azure cloud enterprise app as IDP for this plugin.
IDP part on azure cloud
-
Go to your azure AD and create a new enterprise app.
-
Go to the "Single Sign on" section.
-
Add SAML authentification to app.
-
Gather the metadata from the SAML plugin.
-
Manually edit "Basic SAML Configuration" (Info's can be taken from the SP metadata xml)
Add EntityID and ACS. Optionally also add the Logout URL. Azure wants https there, so depending on your setup just leave it blank.
-
Edit "Attributes & Claims"
The plugin only supports the email address, given name and surename You can configure more attributes, but they will be ignored.
Important: The clame names need to be givenName, surename and email. Also remove the namespace and leave empty.
-
Download Federation metadata XML
SP part on your Plone site
-
Go to URL: http://localhost:8080/Plone/acl_users/saml/idp_metadata
Upload and store configuration from IDP (azure)
-
The upload form also shows you what information has been gathered from the Metadata XML and what will be stored in your saml plugin
THATS IT!! Go To http://localhost:8080/Plone/acl_users/saml/sls to login via azure
If this is the only saml plugin on your site and want all users to login via saml, then you can enable the Challenge Plugin and change the login and logout actions on your plone site to use the saml endpoints.
Changelog
1.0.0b1 (2024-11-01)
- Support Plone 6.1 and Python 3.12. [mathias.leimgruber]
1.0.0a4 (2024-02-20)
- Do not use SCRIPT_NAME for the callback URL. [mathias.leimgruber]
1.0.0a3 (2023-09-28)
- Fix typo for boolean property. [mathias.leimgruber]
1.0.0a2 (2023-09-28)
- Disable csrf protection on acs (callback view). [mathias.leimgruber]
1.0.0a1 (2023-09-28)
- Init release [mathias.leimgruber]
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.