WHMCS OpenID and cPanel Setup Guide - Revision history

SarahK at 20:58, 10 May 2022

2022-05-10T20:58:45Z

PeterB: Undo revision 31120 by PeterB (talk)

2022-01-13T20:52:39Z

Undo revision 31120 by PeterB (talk)

PeterB: /* Setting Up OpenID Authentication for cPanel */

2022-01-13T20:51:29Z

‎Setting Up OpenID Authentication for cPanel

SarahK at 20:47, 10 January 2022

2022-01-10T20:47:56Z

SarahK at 18:40, 17 December 2021

2021-12-17T18:40:47Z

Chance: /* Setup Guide */

2016-02-24T22:06:51Z

‎Setup Guide

Matt at 09:24, 9 December 2015

2015-12-09T09:24:24Z

Matt at 10:29, 25 November 2015

2015-11-25T10:29:52Z

Matt: Created page with "In cPanel 54, support was introduced for login using OpenID Connect authentication providers. WHMCS 6.2 and later can act as an OpenID Connect Authentication Provider. The W..."

2015-11-25T10:23:00Z

Created page with "In cPanel 54, support was introduced for login using OpenID Connect authentication providers. WHMCS 6.2 and later can act as an OpenID Connect Authentication Provider. The W..."

New page

In cPanel 54, support was introduced for login using OpenID Connect authentication providers.

WHMCS 6.2 and later can act as an OpenID Connect Authentication Provider.

The WHMCS OpenID Connect feature allows users to sign into cPanel using their login credentials for your WHMCS Billing & Support system. Utilizing this integration reduces the number of login credentials that end users are required to remember.

==Setup Guide==

To enable WHMCS as an OpenID Connect Authentication Provider for your cPanel/WHM server, follow the steps below.

<div class="docs-alert-warning">'''Important:''' Please ensure you are running cPanel/WHM Version 54 or later or these options will not be available.</div>

# Log into WHM as root
# Navigate to ''Security Center > Manage External Authentications''
# Select the ''Configure'' tab
# Under the Authentication Providers heading, locate '''Log in via WHMCS'''
# Click the Configure button
# Copy the Redirect URI that contains the cPanel port number (2083) to your clipboard - you will need this in a minute.
# Now login to your WHMCS Admin Area
# Navigate to ''Setup > OpenID Connect''
# Click the '''Generate New Client API Credentials''' button
# Enter a name for this OpenID Credential Set - we suggest using the following details<div class="docs-alert-success">'''Application Name:''' cPanel<br />'''Description:''' hostname.example.com<br />'''Logo URI:''' /modules/servers/cpanel/logo.png<br />'''Redirect URI:''' (the URI you copied into your clipboard above)</div>
# Once all fields have been filled out, click the '''Generate Credentials''' button
# The page will re-load and display the generated Client API Credentials to you
# Copy the generated Client ID and Client Secret from here and paste them into the appropriate fields within the WHM WHMCS External Authentication Provider Configuration interface
# In the Well Known Config URI field, enter https://www.example.com/whmcs/oauth/openid-configuration.php, replacing https://www.example.com/whmcs with your WHMCS System SSL URL
# Finally, tick the box to confirm you have used the Redirect URIs as provided, and then click '''Save''' to complete the process.

To complete the setup and activate the WHMCS integration, slide the toggle switch for the '''Status (cpaneld)''' to Enabled. Upon doing this, the "Log in via WHMCS" button should immediately begin showing on the cPanel login page.

Repeat the above steps for each compatible cPanel/WHM server you wish to offer WHMCS authentication for. We recommend creating a unique set of OpenID Connect API Credentials for each server you wish to connect with your WHMCS installation for best security practices.

@@ Line 21: / Line 21: @@
 # Set up the necessary SSL certificates on the cPanel & WHM server. <div class="docs-alert-danger">OpenID Connect requires a Certificate Authority verified SSL certificate.  You must install an SSL certificate on the cPanel & WHM server for the cPanel and WHM service ports and for the WHMCS installation itself.</div>
 # Log in to WHM as the <tt>root</tt> user.
-# Navigate to '''Security Center > Manage External Authentications'''.
+# Navigate to '''WHM >> Security Center >> Manage External Authentications'''.
 # Select the '''Configure''' tab.
 # Click '''Configure''' for '''Log in via WHMCS'''.
 # Copy the redirect URI that contains the cPanel port number (usually, <tt>2083</tt>).
-# Log in to the WHMCS Admin Area.
+# Log in to the WHMCS [[Admin Area]].
-# Generate credentials at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[OpenID Connect]]'''. We recommend using the following details, making certain to use the redirect URI you retrieved from WHM:
+# Generate credentials at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[OpenID Connect]]''' or, prior to WHMCS 8.0, '''Setup > OpenID Connect'''. We recommend using the following details, making certain to use the redirect URI you retrieved from WHM:
 #* '''Application Name''' cPanel
 #* '''Description''' hostname.example.com
 #* '''Logo URI''' /modules/servers/cpanel/logo.png
-# Copy the generated client ID and client secret and paste them into the appropriate fields within WHM's '''WHMCS External Authentication Provider Configuration''' interface
+# Copy the generated client ID and client secret and paste them into the appropriate fields within WHM's '''WHMCS External Authentication Provider Configuration''' interface.
 # In the '''Well Known Config URI''' field, enter your WHMCS system URL.
 # Check to confirm that you have used the redirect URIs that WHMCS provided.

@@ Line 31: / Line 31: @@
 #* '''Logo URI''' /modules/servers/cpanel/logo.png
 # Copy the generated client ID and client secret and paste them into the appropriate fields within WHM's '''WHMCS External Authentication Provider Configuration''' interface
-# In the '''Well Known Config URI''' field, enter https://yourdomain.com/whmcs/oauth/openid-configuration.php. You must replace https://yourdomain.com/whmcs with your '''System URL'''.
+# In the '''Well Known Config URI''' field, enter your WHMCS system URL.
 # Check to confirm that you have used the redirect URIs that WHMCS provided.
 # Click '''Save'''.

@@ Line 31: / Line 31: @@
 #* '''Logo URI''' /modules/servers/cpanel/logo.png
 # Copy the generated client ID and client secret and paste them into the appropriate fields within WHM's '''WHMCS External Authentication Provider Configuration''' interface
-# In the '''Well Known Config URI''' field, enter your WHMCS system URL.
+# In the '''Well Known Config URI''' field, enter https://yourdomain.com/whmcs/oauth/openid-configuration.php. You must replace https://yourdomain.com/whmcs with your '''System URL'''.
 # Check to confirm that you have used the redirect URIs that WHMCS provided.
 # Click '''Save'''.

@@ Line 1: / Line 1: @@
-cPanel & WHM 54 introduces support for login using OpenID Connect authentication providers.
+==Why offer OpenID to your users?==
-WHMCS 6.2 and later can act as an [[OpenID Connect|OpenID Connect Authentication Provider]].
+By leveraging WHMCS as an OpenID provider, you enable your clients to authenticate with other systems and applications using the login credentials of your WHMCS Billing & Support system.  That means they only have to remember one username and password, and that's the username and password for your website, making things simpler and easier for the end user and keeping your brand in their mind.
-The WHMCS OpenID Connect feature allows users to sign into cPanel using their login credentials for your WHMCS Billing & Support system. Utilizing this integration reduces the number of login credentials that end users are required to remember.
+For more information, see:
-==Setup Guide==
+==How does it work?==
-To enable WHMCS as an OpenID Connect Authentication Provider for your cPanel/WHM server, follow the steps below.
+When users visit an application that uses WHMCS as an OpenID provider, users will be presented with a "Login with WHMCS" button, which takes them to your WHMCS Client Portal.  The user will authenticate using their login credentials for your WHMCS, if they are not already logged in, and then authorize the use of their profile information, if they have not previously done so.  WHMCS will return them to the originating application, where an active logged session is established for them.
-<div class="docs-alert-warning">'''Important:''' Please ensure you are running cPanel/WHM Version 54 or later or these options will not be available.</div>
+The referring application never sees the user's password, so there's no risk to the integrity of the client's authentication data.  Subsequent logins to the referring application will not require re-authentication WHMCS so long as they are actively logged in there, but instead the two systems perform a background "handshake" on behalf of the user, creating a seamless, one-click login for the user.
-<div class="docs-alert-danger">
-OpenID Connect requires a Certificate Authority verified SSL certificate.  You will need an SSL installed on the cPanel server for the cPanel/WHM service ports and for the WHMCS installation itself.
+== Setting Up OpenID Authentication for cPanel ==
-# Log into WHM as root
+cPanel & WHM 54 introduced support for login using OpenID Connect authentication providers. WHMCS 6.2 and later can act as an [[OpenID Connect|OpenID Connect Authentication Provider]].
-To complete the setup and activate the WHMCS integration, slide the toggle switch for the '''Status (cpaneld)''' to Enabled.  Upon doing this, the "Log in via WHMCS" button should immediately begin showing on the cPanel login page.
+To use these features:
-Repeat the above steps for each compatible cPanel/WHM server you wish to offer WHMCS authentication for. We recommend creating a unique set of OpenID Connect API Credentials for each server you wish to connect with your WHMCS installation for best security practices.
+Repeat this process for each compatible cPanel & WHM server for which you wish to offer WHMCS authentication. We recommend creating a unique set of OpenID Connect API credentials for each server you connect with your WHMCS installation.
-==How it works/Testing the integration==
+==Testing the Integration==
-Navigate to your cPanel login url, https://hostname.yourdomain.com:2083/ and there you should see a "Log in via WHMCS" button (see image below).  If you do not see the button, please double check you completed all the steps above.
+Navigate to your cPanel login URL (for example, <tt><nowiki>https://host.example.com:2083</nowiki></tt>). A '''Log in via WHMCS''' button will display. If you do not see the button, make certain that you completed all of the above steps.
 [[File:CPanelWHMCSOpenIDLogin.png]]
-===Initial Login===
+===Logging In Using OpenID Connect===
-# Click the '''Log in via WHMCS''' button on the cPanel login page.
+To log in using OpenID Connect:
-The first time a user does this they will not be logged into cPanel immediately.  cPanel will prompt the user for the cPanel username and password they wish to pair up with the WHMCS Billing & Support Client Account, which was just authenticated and authorized.
+# Click '''Log in via WHMCS''' on the cPanel login page. The system will redirect you to the WHMCS installation's login page.
-[[File:WHMCSAuthenticationAuthorizationScreen.png]]
+The system will then redirect you to the cPanel interface.
-===Future Logins===
+<div class="docs-alert-warning">
-On future login visits, clicking the '''Log in via WHMCS''' button will redirect to WHMCS, request the user to log in, and then immediately redirect them back to cPanel where an active login session is auto-generated for the associated cPanel account.
+[[File:WHMCSAuthenticationAuthorizationScreen.png]]

← Older revision		Revision as of 22:06, 24 February 2016
Line 10:		Line 10:

	<div class="docs-alert-warning">'''Important:''' Please ensure you are running cPanel/WHM Version 54 or later or these options will not be available.</div>		<div class="docs-alert-warning">'''Important:''' Please ensure you are running cPanel/WHM Version 54 or later or these options will not be available.</div>
		+	<div class="docs-alert-danger">
		+	OpenID Connect requires a Certificate Authority verified SSL certificate. You will need an SSL installed on the cPanel server for the cPanel/WHM service ports and for the WHMCS installation itself.
		+	</div>

	# Log into WHM as root		# Log into WHM as root

@@ Line 28: / Line 28: @@
 # Copy the generated Client ID and Client Secret from here and paste them into the appropriate fields within the WHM WHMCS External Authentication Provider Configuration interface
 # In the Well Known Config URI field, enter https://www.example.com/whmcs/oauth/openid-configuration.php, replacing https://www.example.com/whmcs with your WHMCS System SSL URL
-# Finally, tick the box to confirm you have used the Redirect URIs as provided, and then click '''Save''' to complete the process.
+# Finally, check the box to confirm you have used the Redirect URIs as provided, and then click '''Save''' to complete the process.
 To complete the setup and activate the WHMCS integration, slide the toggle switch for the '''Status (cpaneld)''' to Enabled.  Upon doing this, the "Log in via WHMCS" button should immediately begin showing on the cPanel login page.

← Older revision		Revision as of 10:29, 25 November 2015
Line 30:		Line 30:

	Repeat the above steps for each compatible cPanel/WHM server you wish to offer WHMCS authentication for. We recommend creating a unique set of OpenID Connect API Credentials for each server you wish to connect with your WHMCS installation for best security practices.		Repeat the above steps for each compatible cPanel/WHM server you wish to offer WHMCS authentication for. We recommend creating a unique set of OpenID Connect API Credentials for each server you wish to connect with your WHMCS installation for best security practices.
		+
		+	==How it works/Testing the integration==
		+
		+	Navigate to your cPanel login url, https://hostname.yourdomain.com:2083/ and there you should see a "Log in via WHMCS" button (see image below). If you do not see the button, please double check you completed all the steps above.
		+
		+	[[File:CPanelWHMCSOpenIDLogin.png]]
		+
		+	===Initial Login===
		+
		+	# Click the '''Log in via WHMCS''' button on the cPanel login page.
		+	# You should be redirected to your WHMCS installation's Authentication and Authorization page.
		+	# Login with a valid client area email address and password.
		+	# You should then see a screen like the image below requesting permission to provide the cPanel server the minimum amount of information required to associate the cPanel account and the WHMCS Billing Account
		+	## This authorization page is only displayed the first time a user requests to login using their WHMCS Billing Account Credentials.
		+	# Upon clicking '''Authorize''' the user is returned to cPanel.
		+
		+	The first time a user does this they will not be logged into cPanel immediately. cPanel will prompt the user for the cPanel username and password they wish to pair up with the WHMCS Billing & Support Client Account, which was just authenticated and authorized.
		+
		+	[[File:WHMCSAuthenticationAuthorizationScreen.png]]
		+
		+	===Future Logins===
		+
		+	On future login visits, clicking the '''Log in via WHMCS''' button will redirect to WHMCS, request the user to log in, and then immediately redirect them back to cPanel where an active login session is auto-generated for the associated cPanel account.
		+
		+	If a user is already authenticated to the WHMCS instance when they click '''Log in via WHMCS''' (either in the current browser session or via a remember me cookie), the user will not even be prompted for login details and simply be redirected immediately back to the cPanel interface with an active login session of the associated cPanel account.
		+
		+	==Caveats==
		+
		+	* cPanel does not provide a mechanism, at this time, to associate multiple cPanel accounts (on the same server) to a single OpenID Connect Subscriber. In short, if your client has multiple hosting accounts on the same cPanel/WHM server, they will only be able to pair their WHMCS Billing & Support Client Account with one of those hosting accounts.