OpenID Connect

OpenID Connect is the standard for single sign-on and identity provisioning on the internet. It uses JSON-based identity tokens (JWT) via the OAuth 2.0 protocol. In order to perform single sign-on through OpenID using WHMCS as an authentication provider, applications must use details that your WHMCS installation generates.

You can access this feature at Utilities > System > OpenID Connect.

You can develop your own integrations with OpenID Connect and WHMCS using the WHMCS API. For more information, see OpenID Connect Development.

What is the OAuth protocol?

OAuth is a protocol that allows third-party applications to obtain limited access to WHMCS on behalf of users. WHMCS uses OAuth 2, an open specification, which allows users to authenticate with WHMCS to both verify their identity and give apps permission to access their data.

After a user completes authorization, OAuth returns an access token. The access token is a string that the WHMCS installation generates. The app or service sends it with each subsequent API request to uniquely identify both the app and the authorized user.

OAuth ensures that third-party apps and services do not store or transmit the user’s WHMCS password. It also allows the user to authorize only specific permissions and to revoke access at any time. Because of this, OAuth is safer and more secure than other forms of API authorization.

OpenID Connect Workflow

Most applications and services that use OAuth or OpenID Connect require the following workflow:

  1. The user clicks Connect to WHMCS or a similar button or link within the app or service.
  2. The app or service redirects the user to the WHMCS installation.
  3. The user logs in to WHMCS and authorizes the app or service to access their WHMCS account using the requested permissions.
  4. After user approval, the system redirects them back to the app or service with an authorization code.
  5. The app or service uses this authorization code to make a request for a reusable access token. It will use this access token to make subsequent requests to the WHMCS API.

Credentials

All OAuth requests require a valid API Client Credential Identifier and Secret.

For single sign-on credentials, we recommend using Application Links or provisioning and managing OAuth credentials through the WHMCS API.

Generate Credentials

To generate a new set of credentials:

  1. Go to Utilities > System > OpenID Connect.
  2. Click Generate New Client API Credentials.
  3. Enter a name, description, URL, and any authorized redirect URIs.
  4. Click Generate Credentials.

When the page reloads, the Client ID and Client Secret values will display in the Client API Credentials section.

If you add or change any information after initially generating the credentials, make certain that you click Save Changes.

Authorized Redirect URIs

WHMCS uses the redirect URIs that you add as a canonical list of approved redirect locations for credentials. When a referring application makes a request, it must provide a redirect location. WHMCS will verify that that location is in the canonical list and will use it after the user has provided authentication and authorization.

Generate a New Client Secret

You can regenerate the client secret at any time. We recommend this if you want to rotate the secret for better security.

To reset the client secret:

  1. Click Manage for your credentials.
  2. Click Reset Client Secret.
  3. Click OK.

The previous secret will immediately become invalid and the page will reload, displaying the new secret.

Make certain to set this new secret value at the referring application.

Set Up OpenID Connect

The steps below set up OpenID Connect on a cPanel & WHM server. The process for other control panels will be similar.

To allow users to log in to cPanel & WHM with their WHMCS credentials:

  1. Set up the necessary SSL certificates on the cPanel & WHM server.
    OpenID Connect requires a CA-verified SSL certificate. You must install an SSL certificate on the cPanel & WHM server for all applicable ports and for the WHMCS installation itself.
  2. Log in to WHM as the root user.
  3. Go 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 Utilities > System > OpenID Connect. We recommend using the following details, making certain to use the redirect URI you retrieved from WHM:
    Application NamecPanel
    Descriptionhostname.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. For Well Known Config URI, 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 will immediately appear on the cPanel login page (for example, https://host.example.com:2083):
    Log in via WHMCS
    The first time that customers log in using this method, they will need to log in with their WHMCS username (email address) and password and then authenticate using their cPanel account credentials to authorize OpenID Connect.

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 that you connect with your WHMCS installation.

Multiple Hosting Accounts

cPanel does not provide a way to associate multiple cPanel accounts on the same server with a single OpenID Connect subscriber (in this case, a single WHMCS user).

If your client has multiple hosting accounts on the same cPanel & WHM server, they will only be able to pair their WHMCS credentials with one of those hosting accounts.

authentication whmcs-api openid-connect oauth application-links

Last modified: June 14, 2024