Difference between revisions of "WHMCS OpenID and cPanel Setup Guide"

Latest revision as of 20:58, 10 May 2022

Why offer OpenID to your users?

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.

For more information, see:

How does it work?

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.

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.

Setting Up OpenID Authentication for cPanel

cPanel & WHM 54 introduced support for login using OpenID Connect authentication providers. WHMCS 6.2 and later can act as an OpenID Connect Authentication Provider.

To use these features:

Set up the necessary SSL certificates on the cPanel & WHM server.
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.
Log in to WHM as the root user.
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, 2083).
Log in to the WHMCS Admin Area.
Generate credentials at Configuration () > 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.
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.
Toggle Status (cpaneld) to Enabled. The Log in via WHMCS button should immediately begin showing on the cPanel login page.

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.

Testing the Integration

Navigate to your cPanel login URL (for example, https://host.example.com:2083). 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.

Logging In Using OpenID Connect

To log in using OpenID Connect:

Click Log in via WHMCS on the cPanel login page. The system will redirect you to the WHMCS installation's login page.
Log in with a valid WHMCS user email address and password.
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 cookie), the user will immediately return to the cPanel interface with an active login session.
If this is the first time you have logged in using this method:
1. Click Authorize to grant the system permission to provide information to the cPanel & WHM server in order to associate the cPanel account and the WHMCS client account.
2. Enter the cPanel account username and password to pair with the WHMCS user account.

The system will then redirect you to the cPanel interface.

cPanel does not provide a mechanism, at this time, to associate multiple cPanel accounts (on the same server) to a single OpenID Connect Subscriber. 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.

@@ 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:
+* [[OAuth]]
+* http://www.openidexplained.com/
+* http://www.connect2id.com/learn/openid-connect
-==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 ==
-</div>
-# 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]].
-# 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.
+To use these features:
+# 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 '''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]].
+# 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.
+# 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'''.
+# Toggle '''Status (cpaneld)''' to ''Enabled''.  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.
+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:
-# 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.
+# Click '''Log in via WHMCS''' on the cPanel login page. The system will redirect you to the WHMCS installation's login page.
+# Log in with a valid WHMCS user email address and password.<div class="docs-alert-success">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 cookie), the user will immediately return to the cPanel interface with an active login session.</div>
+# If this is the first time you have logged in using this method:
+## Click '''Authorize''' to grant the system permission to provide information to the cPanel & WHM server in order to associate the cPanel account and the WHMCS client account.
+## Enter the cPanel account username and password to pair with the WHMCS user account.
-[[File:WHMCSAuthenticationAuthorizationScreen.png]]
+The system will then redirect you to the cPanel interface.
-===Future Logins===
+<div class="docs-alert-warning">
+cPanel does not provide a mechanism, at this time, to associate multiple cPanel accounts (on the same server) to a single OpenID Connect Subscriber. 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.
+</div>
-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]]
-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.

Documentation