cross is now running Foswiki 2.1.3 Beta 1. Please open a task for any issues.
TIP OpenIDLoginContrib is not installed on

Open ID Connect Authentication with OpenIDLoginContrib

Enables Authentication via OpenID Connect


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 for more help.


Configuration of Open ID Connect 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/client (the terminology differs from provider to provider) with at least one Open ID Connect provider (if you don't know how, check out the reference links at the bottom of the page). You also need access to your Foswiki installation's templates folder, as you'll have to edit the login template to suit your needs.


Important: Open ID Connect is not compatible with the original Open ID protocols. Therefore, you can't use OpenIDLoginContrib to connect with older (Open ID 1.0 or 2.0) providers which don't offer Open ID Connect yet.

You need the following information before you can continue:
  1. Your Application/Client ID
  2. Your Application/Client Secret
  3. The Open ID discovery/configuration document URL. The URL usually ends in /.well_known/openid-configuration. If you open this URL, you should see a JSON document listing various OAuth API endpoint URLs, supported scopes, claims etc.
  4. (The issuer string. You can find it in the discovery/configuration document under the 'issuer' key. This is only necessary if you encounter 'wrong issuer' verification errors.)
  5. You also need to know the full URL to your Foswiki installation's login script. This is the redirect or callback URL that you need to provide when registering a new application/client with your Open ID provider.

If you want your users to be able to authenticate using multiple Open ID providers, make sure you have the information for points one through four for each of them.

The information for the first Open ID Provider can be entered using Foswiki's web-based configuration tool (/bin/configure) under the "Open ID" tab which you'll find under "Security and Authentication" . Any additional providers must be added to the LocalSite.cfg configuration file manually. The first provider's key is named 'Default'; you can name additional provider's keys however you wish.

Open ID Login and the Foswiki authentication infrastructure

In order to enable Open ID authentication, you need to switch Foswiki's LoginManager from whatever solution you're currently using over to Foswiki::LoginManager::OpenIDConnectLogin. 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 Open ID authentication.

The OpenIDConnectLogin 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, if you have accounts with multiple Open ID providers, it is currently not possible to explicitely link these accounts in Foswiki while retaining the use of loginnames. You also can't link a native Foswiki user account and an Open ID 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

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 all the Open ID providers enabled for your site, or if you don't care about people being able to impersonate others.

Adjusting the Open ID login template

Since Open ID is a decentralized authentication solution, users usually are given a choice of which Open ID provider they want to use. On all websites which allow their users to authenticate using Open ID, this choice replaces (or extends) the login dialog; so instead of a form with username and password fields, the login dialog under Open ID Connect Login consists of a number of icons or buttons, each representing an Open ID Connect provider. So your login dialog may look like this:

Even if there was only a single provider, showing the login template would still be necessary to give the user a chance to opt out of using an Open ID and switch back to providing native credentials instead. This is what the "I don't use any of those" link is for: It will allow users to authenticate using the default TemplateLogin. If you do not wish to offer native authentication, remove the link from the template. This won't disable the functionality, but hide it from the users.

The above screenshot is exactly what you see if you have PatternSkin installed, but it won't work just yet. You need to logically connect these icons to the providers you configured earlier on. Also, you might want to offer a different list of providers, change the images etc. Currently, there is no way around manually fixing the openidloginbase.tmpl template to achieve all this.

To fix the login page, open the openidloginbase.tmpl and edit the lines at the very end to conform to the providers you need:
%TMPL:P{"openidbutton" PROVIDER="Default" PROVIDERNAME="Microsoft" LOGOIMAGE="windows_logo.png"}%
%TMPL:P{"openidbutton" PROVIDER="Google" PROVIDERNAME="Google" LOGOIMAGE="google_g_logo.png"}%

The PROVIDER parameter references the key you use in LocalSite.cfg. The LOGOIMAGE references an image which you should attach to this topic. Add or remove lines as needed; one for each provider.

If you are using a vanilla PatternSkin or NatSkin, this is all you have to. OpenIDLoginContrib comes with login templates that should work with these skins out of the box (If they don't, fix it in openidlogin.pattern.tmpl or openidlogin.nat.tmpl).

If you are using another Skin, create your own template to act as an "interface" between the standard login template for your skin and openidloginbase.tmpl. Basically, this template should add the openidstep template to the standard login template and mark the other form fields with the native_credentials css class to make them invisible when the login page is first loaded.

If you are not happy with the default look of the icons or the whole login template, you can also edit the openidlogin.css file, which is also attached to this topic.

Supported Open ID Connect Providers

OpenIDLoginContrib aims to eventually support all Open ID Connect providers which adhere to the standard. However, reality tends to intrude. So here's the current list of which providers were tested.

Provider State
Microsoft Works
Google Works
Yahoo Broken (Currently fails halfway through the protocol with an invalid authorization code error)
Facebook* Currently not implemented
*Facebook has it's own implementation called "Facebook Connect", which is close enough to Open ID Connect to warrant eventual support by this Contrib.

Bugs, Shortcomings, Future work

  1. There is a problem with redirection to an action other than view when logging in. This is annoying and shall be fixed soon.
  2. Currently, there is no way to permanently log off. 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. Several Open ID providers offer solutions for this in the form of a logout endpoint, but this functionality hasn't been implemented yet.
  3. We also don't do any registration of new users. An Open ID token doesn't yield much information, but we can get at least the given name, family name and e-mail address out of an ID token.
  4. Future work should include support for Facebook Connect, which is a nearly identical implementation with a few gotchas.
  5. The code is still new and needs thorough testing. Bug reports are welcome.

Important files

There are several places where you can tweak the configuration of Open ID Connect Login:

/templates/openidlogin*.tmpl Related templates. The most important one is openidloginbase.tmpl
/pub/System/OpenIDLoginContrib/openidlogin.css contains css to format the openidlogin templates
/pub/System/OpenIDLoginContrib/openidlogin.js contains javascript for the login page
Please note that these files, especially your templates which aren't under version control, will be overwritten when you update OpenIDLoginContrib.

Nice to know

Reserving WikiNames for specific people

Letting just anyone register via Open ID 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 Open ID and falling back to standard TemplateLogin

Open ID 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 messed up your openidlogin template and can't use it to access the standard template login any more.

You can provide a direct link to any of the configured Open ID login dialogs by using the provider parameter of the login script: /bin/login?provider=Default will send you off to authenticate with the default provider.

Internals & security

The OAuth Open ID client implementation uses the Authorization Code flow (explicit grant flow). This means that no access or ID tokens are ever exposed to the user agent. The implementation currently uses Crypt::JWT to verify the ID Token. In addition, the issuer and audience fields of the id token are checked.

Note: The issuer check is secure by default, but is configurable using the IssuerRegex; therefore it's security depends on the person who configures it.



MIME::Base64 Required
LWP::UserAgent >=6.15 Required for OAuth 2 Server Flow
Crypt::JWT >=0.010 Required for JWT signature verification
Crypt::Random Required for cryptographically secure nonces
JSON Required
Change History:
1.0.0 (11 Dec 2016): Initial release
Topic revision: r2 - 11 Dec 2016, PascalSchuppli - This page was cached on 22 Jan 2017 - 09:14.

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