WHMCS OpenID and cPanel Setup Guide

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:

• OAuth
• http://www.openidexplained.com/
• http://www.connect2id.com/learn/openid-connect

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:

1. 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.
2. Log in to WHM as the root user.
3. Navigate to WHM >> Security Center >> Manage External Authentications.
4. Select the Configure tab.
5. Click Configure for Log in via WHMCS.
6. Copy the redirect URI that contains the cPanel port number (usually, 2083).
7. Log in to the WHMCS Admin Area.
8. 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
9. Copy the generated client ID and client secret and paste them into the appropriate fields within WHM's WHMCS External Authentication Provider Configuration interface.
10. In the Well Known Config URI field, enter your WHMCS system URL.
11. Check to confirm that you have used the redirect URIs that WHMCS provided.
12. Click Save.
13. 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:

1. Click Log in via WHMCS on the cPanel login page. The system will redirect you to the WHMCS installation's login page.
2. 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.
3. 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.