All product names, logos, and brands used in this post are property of their respective owners.
Upon review, I have not written about cPanel (my favorite web hosting control panel) since 2018! I figure it is time to revisit an old friend so I am going to document the process of configuring cPanel external authentication with Microsoft Azure Active Directory (using Oauth 2.0, OpenID Connect). External Authentication has existed in cPanel/WHM since version 54 and is one of my favorite “enterprise” features.
The mechanics of setting this up are deceptively easy, but there are a few key details that make it possible. The real magic is in the WHMCS (Web Host Manager Complete Solution) external authentication provider - this is the only out-of-box cPanel external authentication provider that allows you to specify an OIDC well known config URL (OpenID Connect metadata). With this, you can point cPanel/WHM/webmail external authentication to ANY Oauth 2.0/OpenID Connect identity provider.
Let’s take a look at the process.
cPanel (WHM) and Azure AD setup
I like to have Azure AD and the WHM interface open in separate windows that I can copy and paste between. In this step, you must copy the required OIDC configuration parameters between the WHMCS auth provider in WHM and Azure Active Directory.
1 . Login to WHM as a user with root privileges, navigate to Security Center -> Manage External Authentications -> Configure, and click Configure next to Login via WHMCS
2 . If you are inclined, customize the look and feel of the WHMCS external authentication button. To illustrate, I customized the cPanel external login button to reflect Azure AD branding (Button Label: “Log in via Azure AD”, Button color: “FFFFFF”, Button text color: “00BEF2”). If interested, my Base64 encoded SVG of the Azure AD logo is here.
3 . In another window or browser, log in to Azure AD (https://portal.azure.com) with an AAD account with permission to create App Registrations and navigate to the App Registrations page. This is also accessible via Azure Active Directory -> Manage (section) -> App registrations.
4 . Click New Registration and give the app a name (I was super creative and used “cPanel”). Back in your WHM window (WHMCS external authentication configuration screen), copy/paste the Redirect URI for cPanel into the Web Redirect URI box on the Azure AD app registration screen and click Register:
I copied and pasted just the cPanel interface Redirect URL - you can add the other URIs later if desired. You can even add the Redirect URIs from additional cPanel servers if you have more than one and prefer to consolidate under a single App registration. Ensure the Redirect URIs you paste reflect the public-facing hostname of your cPanel/WHM server. If your hostname is misconfigured (example: the Redirect URL is not publically accessible, Azure AD authentication will fail later when it returns the authentication response to the Redirect URI).
5 . Azure AD should direct you to the app overview page - copy the Application (client) ID for the app and paste that into the WHM External Authentication configuration screen:
6 . On the same screen in Azure AD, click Endpoints and copy the OpenID Connect metadata document. Paste the value into the Well Known Config URI box on the WHM External Authentication configuration screen.
7 . Finally, in Azure AD, click the Certificates & secrets link, click New client secret under Client secrets, create a secret (providing a description and expiration), and copy/paste the resulting secret into the Client Secret box on the WHM External Authentication configuration screen:
8 . Lastly, tick the checkbox on the WHM External Authentication configuration screen, click Save, and enable the WHMCS external authentication provider (since I only copied the Redirect URI for cPanel above, I only enabled the provider for cPanel login):
Create a user in Azure AD (optional)
If you already have users in Azure AD, you can skip this step. In my test tenant, I had no users so I created one called “euclid” as follows:
The username and other details do not matter (the UPN and email address do not even need to match the user’s account in cPanel). The user only needs to be able to successfully authenticate against Azure Active Directory.
Create a cPanel account in WHM (optional)
If you already have accounts on your cPanel server, you can skip this step. On my test server, I had no accounts so I created one called “euclid” as follows (similarly to in Azure AD):
The Username, Email, and other details do not matter (no need to match the user’s identity in Azure AD). The user only needs to be able to successfully authenticate and login to the server’s cPanel web interface.
Link the external account in cPanel
The final step is “linking” the external account (identity) to the cPanel (local) account. This is done (manually) as follows. This can also be performed programmatically.
1 . Browse to the server’s cPanel web interface URL (https://servername.domain:2083) and log in with a valid user (in my case “euclid”) - ignore the “Login via Azure AD” external authentication button for now.
2 . Click the username drop-down in the top right, select Password & Security, scroll down to the External Authentication section, and click the Link Account button:
3 . This should initiate the Azure AD login process where you will be prompted to enter the Azure AD identity’s username, password, and provide consent:
You can suppress the Permissions Requested prompt by granting consent on behalf of your organization in the Azure AD App Registration created previously (API Permissions section).
4 . Once Azure AD authentication is completed, the identity is linked to the cPanel account. You can confirm in WHM at Security Center -> Manage External Authentications -> Manage Users:
Test authentication
If all has gone well, cPanel external authentication using Azure Active Directory should be ready to roll. You can test by closing existing cPanel sessions, navigating to the cPanel web interface URL on your server and clicking the “Login via Azure AD” button:
You should be prompted to authenticate with Azure AD:
Once successfully authenticated, you should be directed to the cPanel interface and logged in as the user account you linked (in this case “euclid”):
To confirm, you can check the Azure AD Sign-in log for the Azure AD identity:
Closing thoughts
If you made it this far, I suspect you have unanswered questions. For example, “why did Neil tag this post with MFA?” and “this is great, but why use Azure AD?”. In my opinion, harnessing the power of Azure AD for external cPanel authentication opens up a world of enterprise possibilities.
With cPanel, WHM, and webmail authenticating against Azure AD, you can apply Azure MFA (including Conditional Access if you are licensed) to cPanel/WHM/webmail logins. Even if you do not require MFA for all users, I would argue that applying it to cPanel and WHM administrators and resellers is great starting point.
Additionally, any users authenticating to cPanel with Azure AD (assuming it is your primary IdP) will receive the benefit of single sign-on across your services.
There are other details to consider when hardening an external authentication setup like this in cPanel. For instance, after external identities are linked in cPanel, WHM, etc. (manually or via api) you should consider:
- Resetting their local cPanel password (to something random)
- Disabling the “Password & Security” feature to prevent further local password changes
- Disabling Password Reset functionality
- Modifying the login page to ultimately hide the username and password login options and present only the external authentication button(s)
- Disabling other avenues for privileged server access (i.e. SSH/shell)
Those items should effectively prevent login with local credentials and force external authentication (and multifactor authentication) via Azure Active Directory.
It is worth noting, you can also create your own custom external authentication module for cPanel (leveraging Azure AD as the OpenID Connect IdP) if you prefer not to rely on the built-in WHMCS one.