[Tutorial] WHMCS OAuth2.0 SSO Integration

[Jon Erickson]

Greetings, with the industry standard of Single Sign-On (SSO) continually increasing, the need to provided authentication and authorization across your independent software systems is paramount for system administrators and web development engineers. For those who run WHMCS, a popular web hosting control platform, here is a quick tutorial to use your installation of IPB as an OAuth2.0 client and WHMCS as the OAuth2.0 server to provide SSO capabilities for your IPB and WHMCS systems.

Step 1: Make sure your IP is whitelisted within the WHMCS control panel. We will be using the WHMCS API to manage and create our OAuth2.0 credentials. You can add your IP to the whitelisted IP's under Setup -> General Settings -> Security Tab -> "API IP Access Restriction".

Step 2: Create a set of API credentials that we will use to access the WHMCS API that will allow us to create our OAuth2.0 credentials. You can add your API credentials within WHMCS control panel by going to Setup -> Staff Management -> Manage API Credentials. Create a new API credential - making sure to copy the identifier and secret. Your API credential will need access to an API role that has all "Authentication" permissions.

Step 3: Download an application you can use to run REST API requests. I use Postman which is free and provides everything you will need. You can also use cURL.

Step 4: Create an OAuth2.0 credential that will be used by IPB to obtain an authorization code my making a POST request to the WHMCS API. Make sure to fill in 'username' and 'password' with your API identifier and secret, respectively. You can obtain your IPB_OAUTH_REDIRECT_URI by logging into the IPB admin control panel, visit Login & Registration -> Create New -> Other OAuth2.0 -> Application Settings. 
 

cURL Request

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.example.com/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'CreateOAuthCredential',
            'username' => 'WHMCS_API_IDENTIFIER',
            'password' => 'WHMCS_API_SECRET',
            'granttype' => 'authorization_code',
            'scope' => 'clientarea:sso clientarea:profile clientarea:billing_info clientarea:emails clientarea:announcements clientarea:downloads clientarea:knowledgebase clientarea:network_status clientarea:product_details clientarea:invoices clientarea:tickets clientarea:submit_ticket clientarea:shopping_cart_domain_register clientarea:shopping_cart_domain_transfer clientarea:upgrade',
            'description' => 'OAuth2.0 credentials for IPB SSO.',
            'responsetype' => 'json',
            'redirectUri' => 'IPB_OAUTH_REDIRECT_URI',
            'name' => 'IPB SSO'
        )
    )
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

Postman

Step 5: Copy the clientIdentifier and clientSecret you received.

Step 6: Fill out IPB OAuth2.0 form with your known settings.

• Grant Type: Authorization Code
• Client Identifier: Your copied clientIdentifier
• Client Secret: Your copied clientSecret
• Client Authentication: Request Body
• Scopes to Request: openid, email, profile (Each one as a new line)
• Authorization Endpoint: https://www.linktowhmcsinstallation.com/oauth/authorize.php
• Authorization for AdminCP: Use the same endpoint as normal logins
• Token Endpoint: https://www.linktowhmcsinstallation.com/oauth/token.php
• User Information Endpoint: https://www.linktowhmcsinstallation.com/oauth/userinfo.php
• User ID Parameter: sub
• Display Name Parameter: name
• Email Address Parameter: email

Step 7: Try it out! 

If you have any questions, feel free to post to this topic and I will answer as soon as possible.

You can see it live in action at: https://community.deschutesdesigngroup.com

 

 

[Revo2020]

is it possible to setup so logins only work if the client has a product or service?

[Jon Erickson]

@Revo2020, yes, you would need to hook CreateOAuthCredential and perform an authorization check before the action is executed.