Authentication with external identity providers

By installing a plug-in that provides a method of authentication with an external identity provider, your users can create accounts and login without a password, instead relying on being logged in to an external system.

External identity providers currently only work on single tenant installations and root tenants of multitenant instances. It may be possible without too much work to make it work on tenant applications if the plug-in is installed both on the root tenant and the subdomain tenant application. Please get in touch if you need this.

To use external identity providers, you should first set the base URL configuration value (under Settings-> Configuration, when logged in as an administrator). Set this to the URL your application is installed at, for instance http://example.com or http://45.32.167.95.

After the base URL has been set, you should install plug-ins that provide authentication. These are marked in the plug-in store with the label "authentication" - note that these will be absent if you are on a subdomain tenant. The following identity providers are currently implemented as plug-ins:

  • Twitter authentication with twitter-auth
  • GitHub authentication with github-auth
  • Google authentication with google-auth
  • LDAP
  • Generic OAuth 2.0 provider

After installing the authentication plug-in, you will be directed to the configuration form (or filled this in later by clicking the cog in the plugin in the plugin store) where you should enter the necessary configuration to make this authentication method work. For instance, for OAuth based methods you should enter a client ID and the client secret which you obtain by creating an app with the identity provider.

The pluggable authentication system is based on passport.js. Any strategy listed on that website should be easy to convert to a plug-in supplying authentication. The authentication plug-ins are very short, for instance see the twitter--auth code.  The plug-ins consist entirely of the configuration form obtaining the client ID and secret, and a call to the passport strategy.

Note that even if the "allows signup" configuration is set to false, users will still be able to create new accounts using external identity providers.

If the external identity provider does not supply an email, the user will be prompted for their email upon creating the account. If a new user form is enabled through the configuration system to obtain user fields, this form will also appear after creating the account. If it is both the case that an email address cannot be obtained and the new user form is enabled, then an email field will be inserted at the top of the new user form. You may want to test this scenario as you design your new user form to ensure that it is harmonious with the email field.