Revision as of 22:06, 24 February 2016

cPanel & WHM 54 introduces support 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.

1. Log into WHM as root
2. Navigate to Security Center > Manage External Authentications
3. Select the Configure tab
4. Under the Authentication Providers heading, locate Log in via WHMCS
5. Click the Configure button
6. Copy the Redirect URI that contains the cPanel port number (2083) to your clipboard - you will need this in a minute.
7. Now login to your WHMCS Admin Area
8. Navigate to Setup > OpenID Connect
9. Click the Generate New Client API Credentials button
10. Enter a name for this OpenID Credential Set - we suggest using the following details
    Application Name: cPanel
    Description: hostname.example.com
    Logo URI: /modules/servers/cpanel/logo.png
    Redirect URI: (the URI you copied into your clipboard above)
11. Once all fields have been filled out, click the Generate Credentials button
12. The page will re-load and display the generated Client API Credentials to you
13. 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
14. 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
15. 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.

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.

Initial Login

1. Click the Log in via WHMCS button on the cPanel login page.
2. You should be redirected to your WHMCS installation's Authentication and Authorization page.
3. Login with a valid client area email address and password.
4. 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
   1. This authorization page is only displayed the first time a user requests to login using their WHMCS Billing Account Credentials.
5. 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.

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.