dotCMS logodotCMS logo

OAuth Authentication Plugin

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

Important#

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 Tool section of the OSGI Plugins documentation.

OSGi Exports#

The following package exports are required by this plugin:

org.apache.velocity.tools.view.tools,
org.apache.velocity.tools.view.servlet,
org.apache.velocity.tools.view,
javax.xml.bind,
com.liferay.portal.util,
com.liferay.portal.model,
com.liferay.portal.auth,
com.dotmarketing.viewtools,
com.dotmarketing.util.json,
com.dotmarketing.util,
com.dotmarketing.osgi,
com.dotmarketing.filters,
com.dotmarketing.exception,
com.dotmarketing.cms.login.factories,
com.dotmarketing.cms.factories,
com.dotmarketing.business,

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

Usage#

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:

http://localhost:8082/html/portal/login.jsp?native=true
http://localhost:8082/dotCMS/login?native=true

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.