TIP SamlLoginContrib is not installed on Foswiki.org.

SAML Authentication with SamlLoginContrib

Enables Authentication via SAML Authentication


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 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


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 a 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:


Supported SAML Identity Providers

SamlLoginContrib aims to eventually support any SAML2 standars 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
Microsoft Azure Tested
Google GSuite Works

Bugs, Shortcomings, Future work

  1. Currently, it does not support SAML's Logout everywhere functionality. Destroying the Foswiki session isn't enough, because someone with access to the browser can simply re-authenticate without needing to enter a password. This is a hard problem. SAML Identity Providers offer a logout endpoint, but this functionality hasn't been implemented yet.
  2. 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.
  3. Future work should include support for Microsoft's SAML Federation service.
  4. The code is still new and needs thorough testing. Bug reports are welcome.

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::VerifyX509 verify 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.




Name Version Description
NET:SAML2   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
Topic attachments
I Attachment Action Size Date Who Comment
SamlLoginContrib.md5md5 SamlLoginContrib.md5 manage 171 bytes 24 Feb 2020 - 01:42 TimothyLegge  
SamlLoginContrib.sha1sha1 SamlLoginContrib.sha1 manage 195 bytes 24 Feb 2020 - 01:43 TimothyLegge  
SamlLoginContrib.tgztgz SamlLoginContrib.tgz manage 13 K 24 Feb 2020 - 01:42 TimothyLegge  
SamlLoginContrib.zipzip SamlLoginContrib.zip manage 16 K 24 Feb 2020 - 01:42 TimothyLegge  
SamlLoginContrib_installerEXT SamlLoginContrib_installer manage 5 K 24 Feb 2020 - 01:42 TimothyLegge  
Topic revision: r1 - 24 Feb 2020, TimothyLegge - This page was cached on 19 Nov 2020 - 17:12.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy