dotCMS logodotCMS logo
dotCMS Github RepodotCMS Github RepodotCMS Discourse CommunityChat With Us
Legacy and Deprecated

Deprecated Plugins

OAuth Authentication Plugin

Deprecated: OAuth Authentication Plugin
26.08.24-01
Deprecated Oct 29, 2026Deprecated in 26.08.24-01
Recommendation

On dotCMS 26.08.24-01 or later, configure SSO in dotAuth instead of the OAuth Authentication Plugin. Settings aren't migrated automatically, so re-enter the configuration in dotAuth. The plugin keeps working until you switch, so you can set up dotAuth with SSO turned off, test it, then turn it on and remove the plugin. Existing users are matched by verified email, so test sign-in with an existing account before you switch production sign-in. See dotAuth Overview and Rolling Out SSO Safely.

Reason

The OAuth Authentication Plugin is superseded by dotAuth, which is built into dotCMS core as of version 26.08.24-01. dotAuth provides OAuth 2.0 / OpenID Connect single sign-on through a guided screen under Settings, with no plugin to install. It also adds per-site configuration, user provisioning and role mapping, and headless token exchange, none of which the plugin offers.

All deprecations

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-community/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

Securing Forced Native Logins#

The variable SSO_BYPASS_TOKEN (or DOT_SSO_BYPASS_TOKEN) allows you to configure an extra layer of security over forced native logins. Assign a token value to this variable, and that token will be required to force native login, and ?native=true will no longer work.

For example, if you set:

DOT_SSO_BYPASS_TOKEN=tok_abc123xyzDoReMi...

Then to perform a native login, you would need to browse to:

/dotAdmin?native=tok_abc123xyzDoReMi...

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.