SAML Authentication with SamlLoginContrib

Enables Authentication via SAML Authentication

Installation

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Configuration

Configuration of SAML Authentication for your Foswiki site requires a bit of work, knowledge about Foswiki's configuration files and at least a passing understanding of it's templating system.

Before you begin, make sure you have registered a new application/Service Provider (SP) (the terminology differs from provider to provider) with at the SAML Identity Provider you plan to use (if you don't know how, check out the reference links at the bottom of the page).

Assumes that SamlLoginContrib is installed and enabled and you are logged in as admin to modify the config.

Description	Setting	config setting
Change Login Manager	{LoginManager}	Foswiki::LoginManager::SamlLogin
Change Password Manager	{PasswordManager}	None
Enable Allow Login Names	{Register}{AllowLoginName}	Enabled
Metadata	{Saml}{metadata}	http://localhost/metadata.xml
Login Return Page	{Saml}{issuer}	https://foswiki.local/bin/login
Signing Cert	{Saml}{sp_signing_cert}	/var/www/foswiki/saml/sign.pem
Signing Key	{Saml}{sp_sigining_key}	/var/www/foswiki/saml/sign.key
Identity Provider Root Certificate	{Saml}{cacert}	/var/www/foswiki/saml/cacert.pem
Change WikiName Claims	{Saml}{WikiNameAttributes}	fname,lname

Requirements

Important: SAML2 is not compatible with the original SAML protocol. However it is unlikely any Identity provider would be supporting SAML v1 at this point.

You need the following information before you can continue:

1. The metadata xml file provided by your Identity Provider
2. The SAML "Application/Service Provider" defined on your Identity Provider
3. The Root Certificate that the Identity provider will use to sign the SAMLResponse
4. A public/private key pair for your Application (Service Provider). This is used to sign the request to the Identity Provider

The information for the SAML Authentication can be entered using Foswiki's web-based configuration tool (/bin/configure) under the "Saml" tab which you'll find under "Security and Authentication" .

Saml Login and the Foswiki authentication infrastructure

In order to enable Saml authentication, you need to switch Foswiki's LoginManager from whatever solution you're currently using over to Foswiki::LoginManager::SamlLogin. If you were previously using an authentication scheme that made use of TemplateLogin, chances are you will be able to keep it working in parallel with SAML authentication.

The SamlLogin manager obviously doesn't require a password backend. Currently, it also doesn't provide it's own user mapper. I suggest you use TopicUserMapping in order to get a stable mapping from a third-party account to a WikiName, but this isn't required for authentication.

Not having our own user mapper has it's downsides. For example, you can't link a native Foswiki user account and a SAML account. You may manage to map both accounts to the same WikiName, but unless you disable the use of loginnames in the Foswiki configuration, this is only a cosmetic operation; it doesn't really link the identities. In addition, Foswiki redirects to the SAML provider immediately and does not allow you to enter a Non-SAML login and password (see below)

Warning: You are strongly discouraged from disabling the use of loginnames. In fact, you should only ever consider this if you either have full control over the SAML Identity providers enabled for your site, or if you don't care about people being able to impersonate others.

Logging in as the Local Admin

To login as the local admin (to access configure) you need to tell the login process that you wish to use the native login:

https://foswiki.local/bin/login?provider=native

Supported SAML Identity Providers

SamlLoginContrib aims to eventually support any SAML2 standards compliant Identity Provider and will include configuration options to allow you to use the data they provide. So here's the current list of which providers were tested.

Provider	State
Auth0	(requires Net::SAML2 >=0.39) Works
Microsoft Azure	Works
Google GSuite	Works
Jump	Works
Keycloak	Works
OneLogin	Works
PingIdentity	(requires Net::SAML2 >=0.44) Works

Bugs, Shortcomings, Future work

1. We also don't currently support creating a New User Page like Ldap's NewUserPlugin but that is on the list. SAML can get at least the given name, family name and e-mail address in most cases. Other SAML providers can provide additional information. Groups can be provided but are not currently.

Nice to know

Reserving WikiNames for specific people

Letting just anyone register via SAML has its downsides: A common problem is that you don't control which WikiNames will get "taken". So how can you make sure your good friend John Smith gets JohnSmith even though he's taking his time logging in for the first time?

Easy. Enable WikiName Reservation in the configuration settings. Then create the JohnSmith topic in the users web and add his e-mail-address to the user form. Now only the John Smith who claims this e-mail-address will get the WikiName. The other John Smiths will get mapped to JohnSmith2, JohnSmith3 and so on. This isn't designed to withstand malicious attacks, but should keep accidental assignment of a WikiName from happening.

Bypassing SAML Autherntication and falling back to standard TemplateLogin

SAML Authentication captures the Foswiki login script, but it can be made to yield to template-based password authentication. Call /bin/login?provider=native to see it in action.

This can also come in handy when you've need to login to the admin user to access the configure script.

Internals & security

The SAML Service Provider (SP) implementation means that no usernames or passwords are ever exposed to the user agent. The implementation currently uses Net::SAML2::XML::Sig to verify the signature of the response and Crypt::OpenSSL::Verify to verify that the signing certificate is trusted by the Root CA Cert of Identity Provider. In addition, the ID of the request from the application/Service Provider (SP) is verified against the InResponseTo value in the SAMLResponse.

Updating User Form with data from the SAML2 Assertion Attributes

Upon initial login the user is registered and the user's topic is created. Unfortunately, the topic is not available at that point so the SAML2 attributes are not saved in the user's topic. Upon the next login (and all subesquent) the assertion attributes are written to the UserForm in the user's topic. As the SAML2 attributes may not match the Foswiki User form data attributes the $Foswiki::cfg{Saml}{AttributeMap} contains a HASH of Foswiki to SAML2 attribute mappings.

References

• SAML Wiki at Oasis-Open.org: https://wiki.oasis-open.org/security/FrontPage
• SAML_2: https://en.wikipedia.org/wiki/SAML_2.0

Info

Dependencies:

Name	Version	Description
NET:SAML2	0.61	Required
LWP::UserAgent	>=6.15	Required for getting the Metadata
Crypt::JWT	>=0.010	Required for JWT signature verification
Crypt::Random		Required for cryptographically secure nonces
JSON		Required

Change History:
1.0.0 (24 Feb 2019):	Initial release
1.1.0 (30 Mar 2021):	Clean up of Code, Debugging and Readaability Improvements
1.1.1 (23 Apr 2022):	Support for SAML2 LogoutRequest/Response
1.1.2 (23 Apr 2022):	Fix issue in last release
1.1.3 (26 Apr 2022):	Fix Logout/Login loop
1.1.4 (01 May 2022):	Fixes #4 logoutUrl does not work correctly with NatSkinPlugin
1.1.5 (04 May 2022):	Update User Form with data from SAML2 attributes
1.16 (05 May 2022):	Fix Version format
1.17 (27 Oct 2022):	Updates for Net::SAML2 and oops page for some errors
1.18 (29 Oct 2022):	Fix version date issue
1.19 (31 Oct 2022):	Add additional oops and change oops status code
1.20 (26 Feb 2024):	Updates for Net::SAML2 changes and undefined values