module New Module: PoetSaml2 - A SAML2 Service Provider for the ProcessWire CMS/CMF

[BitPoet]

Sooner or later, everybody gets hit by the dreaded "can't we integrate this with [Azure|Google|Facebook|whatever|...]?" question. Lately, those have more or less assaulted me, and I've been looking for a clean-cut solution to link my PW instances up to a big Identity Provider. There is already the SamlAuth module in the module repository, but it has not been updated in a while and it's not as "graphical" as I'd like it to be - I want to be able to take long holidays away from cellphone reception while our IdP's certificate might expire. So I started wiring things up from scratch (as much as "building a PW UI and endpoints around php-saml) can be called "from scratch".

So I've been starting to build:
PoetSaml2

A SAML2 Service Provider for the ProcessWire CMS/CMF

The module is still very alpha, rough around the edges and lacking a bunch of features I consider essential for long-term production use. Still, I decided to get the word out there early, maybe find even find some daring early adopters willing to restore a backup or two of their PW instance in case things go wrong, and also perhaps get some feedback about use cases and requirements I am not aware of. My SAML2 experience so far is limited to an enterprise environment with only Azure / Entra Id and SamlTest.id.

It uses OneLogin's php-saml library for the hard work.

The necessary SSO endpoints are realized with ProcessWire's URL hooks.

Requirements

• ProcessWire >= 3.0.218
• FieldtypeOptions
• FieldtypeRepeater
• PHP-OpenSSL

Compatibility

Basic compatibility has been verified with both Entra Id and SamlTest, meaning I could initiate successful logins into ProcessWire both from PW itself and from the Identity Provider.

Screenshots

SAML2 login button on the admin login form:

PoetSaml2 comes with an admin page that lists all configured profiles and gives you quick links for adding and deleting profiles, lets you download your metadata file so you can upload it to your Identity Provider and even lets you backup profiles to a file. Uses ProcessPagesExportImport to import backup files.

The profile configuration is a regular page edit screen. There are sections for the local endpoint (SP Configuration) and for the Identity Provider (IdP Configuration).

You can set a redirect URL or even role specific URLs so PW knows where to take you if you initiate a login on the IdP side.

Fine grained login permission, redirect URL discovery and even user creation based on SAML Claims can be realized through hooks.

A checkbox lets you create a self-signed SP certificate.

You can import your IdP's metadata.xml from a file or URL instead of having to copy & paste the URLs and certificate (thanks to php-saml's metadata parser).

A lot of it is already documented to some extent in the README file on GitHub.

 

[adrian]

@BitPoet - thanks so much for your hard work on this and sharing it with everyone.

Just curious though about the need for the PHP-mcrypt library. I thought it was considered important to instead use sodium these days. I'd love your thoughts on this because it seems like you are pretty in-tune with these types of things.

[BitPoet]

18 minutes ago, adrian said:

Just curious though about the need for the PHP-mcrypt library.

It's a dependency of php-saml. I haven't looked to deeply into the why and where there, but it's on my radar. The php-saml docs are still a bit of a mix of old and new from versions 2, 3 and 4, so I'll have to dig into the code to see if it's really still needed.

[adrian]

Thanks - looks like it goes deeper than php-saml to one of it's dependencies (https://github.com/robrichards/xmlseclibs) - https://github.com/SAML-Toolkits/php-saml/issues/79

php-saml branch without mcrypt: https://github.com/SAML-Toolkits/php-saml/tree/remove_mcrypt but this was created in 2017, so who knows when it will make it into the master branch.

And it looks like mcrypt has been removed from https://github.com/robrichards/xmlseclibs - https://github.com/robrichards/xmlseclibs/pull/101

I don't know - looks like some of these relied upon packages aren't really being maintained anymore, so hopefully php-saml will merge those changes to master sometime :)

[BitPoet]

So, after jumping through the code, I found that v4 includes xmlseclibs through composer (2 and 3 ship an integrated, outdated version). The code in the xmlseclibs GitHub repo doesn't have any references to mcrypt left. So it seems I can hard wire v4 (only dropping backwards compatibility with eol PHP releases) and be done with mcrypt 🙂

[teppo]

Just to confirm: I've got a php-saml based setup running (via in-house PW SAML module, which is loosely based on https://github.com/adamxp12/ProcessWire-SAMLAuth) and only requirement there is onelogin/php-saml ^4.1 🙂

Anyway, it's good to have an up to date SAML module available, so thanks for sharing!

[BitPoet]

20 hours ago, teppo said:

Just to confirm: I've got a php-saml based setup running

Thanks for the feedback! I tested things with 4.1 and just committed the change to GitHub.

If you don't mind me asking: which IdPs have you had success with, and did you have to dabble with advanced settings to get things up and running? (If you don't want to or can't answer that, I'll understand).

 

[BitPoet]

v0.0.32 is out with the following additions:

• "Configurations" have been renamed to "Profiles"
• You can now fine tune your settings with all the advanced options php-saml supports (besides contact information in the metadata), e.g. encryption and signing settings, algorithms, required fields / attributes or ADFS compatiblity
• The import of backup files is now possible
• "Log in with ..." Buttons on the admin login form can be switched on and off for each SP Profile
• Error messages can be customized in PoetSaml2 module settings

I also added a bunch of hookable methods:

canLogin( $user )
Hook for extra checks whether a user is allowed to log in

getLocalUser( $nameId )         
Hookable user lookup method.
Gets the IdP-supplied nameId and looks up the user with that email address. You can implement your own lookup logic by hooking this function and returning either a User object or boolean FALSE.

getLoginRedirectFor( $profile, $user )         
Hookable method that determines the login success redirect URL for the logged in user.

processSamlUserdata( $userdata, $friendlyUserdata )         
Hookable method for actions based on the SAML2 claims returned by the IdP. You could hook into this method to create users on the fly.

[BitPoet]

Another update: 0.0.35 is on GitHub supports (still experimental) updating of user profile fields with data supplied by the IdP.

User updating can be enabled per profile, and the claims/fields can be mapped individually. The update method is also hookable, so you can leave the mapping empty and perform the deed in your hook to PoetSaml2::updateUserData.

This introduces a dependency on my new FieldtypeListLinks module, which got a few test runs that way 😉

[teppo]

On 10/31/2023 at 9:05 PM, BitPoet said:

If you don't mind me asking: which IdPs have you had success with, and did you have to dabble with advanced settings to get things up and running? (If you don't want to or can't answer that, I'll understand).

Only used OneLogin so far. It's been a couple of years since I set this thing up, but as far as I can remember there was no need to tweak anything in advanced settings 🙂