OAuth Authentication Plugin

Last Updated: Oct 27, 2021
documentation for the dotCMS Content Management System

This OSGI plugin provides an example of single sign-on in dotCMS using the OAuth2 protocol.


This plugin is intended to be a drop-in replacement for the standard dotCMS login, both for front-end and back-end users.

  • When this plugin is enabled it effectively disables the native (default) dotCMS authentication.
  • This plugin is provided as a code example and should not be used in a production environment without careful understanding of both the OAuth2 protocol and the operation of this plugin.

The plugin includes sample implementations for both Google and Facebook logins.

Building the Plugin

To use the OAuth plugin, you must download and build the plugin code. The following steps may be used to download and build the plugin on Linux and OSX:

  1. Run git clone https://github.com/dotcms-plugins/plugin-dotcms-oauth.git.
  2. Run cd ./plugin-dotcms-oauth
  3. Modify the oauth.properties file as needed.
  4. Run ./gradlew jar

Note: Using these commands, the plugin will be built in the build/lib directory within the current directory.

Activator Class

This plugin “rewrites” the URLs used by dotCMS to login (for both the front-end and back-end), pointing them to the OAuth provider specified. You can view (and add, delete, or modify) these “rewrites” in the Activator.java class in the oauth plugin Github repository.

Loading the Plugin

You may the plugin via the back-end Plugins tool. For more information on loading dynamic plugins in dotCMS, please see the Dynamic Plugins Portlet section of the OSGI Plugins documentation.

OSGi Exports

The following package exports are required by this plugin:


For information on how to add export packages for OSGI plugins, please see the Exported Packages section of the OSGI Plugins documentation.


Application Requirements

To use this plugin, you must have both:

  • A developer account with the appropriate provider (e.g. Google or Facebook).
  • At least one application registered with the appropriate provider.

In addition, in each registered application you must:

  • Authorize the application scopes required by the plugin.
    • Please see the oauth.properties file for a list of the required scopes.
  • Authorize the Callback host to receive the callback.
  • Add the application API key and API secret to the oauth.properties file.

Forced OAuth Bypass

When this plugin is running, the native (default) dotCMS authentication is disabled. However you may explicitly bypass the OAuth2 authentication and use the native dotCMS authentication for a single page by passing the URL parameter native=true, as in the following examples:


Disabling DHE

On some environments you may receive an exception with the TLS algorithm, for example:

javax.net.ssl.SSLHandshakeException: Could not generate secret

To solve this problem, disable support for DHE by adding DHE to the jdk.tls.disabledAlgorithms property in your JAVA_HOME/lib/security/java.security file:

jdk.tls.disabledAlgorithms=SSLv3, DHE.

On this page


We Dig Feedback

Selected excerpt: