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
, 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.
|| config setting
| Change Login Manager
| Change Password Manager
| Enable Allow Login Names
| Login Return Page
| Signing Cert
| Signing Key
| Identity Provider Root Certificate
| Change WikiName Claims
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:
- The metadata xml file provided by your Identity Provider
- The SAML "Application/Service Provider defined on your Identity Provider
- The Root Certificate that the Identity provider will use to sign the SAMLResponse
- 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)
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
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.
| Microsoft Azure
| Google GSuite
Bugs, Shortcomings, Future work
- 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.
- 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.
- Future work should include support for Microsoft's SAML Federation service.
- 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
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.
|| Required for getting the Metadata
|| Required for JWT signature verification
|| Required for cryptographically secure nonces
| Change History:
| 1.0.0 (24 Feb 2019):
|| Initial release