OAuth 2.0 Add-on Module Code

The code for the WHMCS OAuth 2.0 Add-on Module is available on GitHub: https://github.com/0-complexity/whmcs-oauth2-addon

Also see the GitBook for this module: https://www.gitbook.com/book/gig/whmcs-oauth-2-0-add-on-module/details

This WHMCS add-on module implements the integration with ItsYou.online, using the "authorization code" grant type flow.

As documented in the ItsYou.online documentation the "authorization code" grant type flow consists of 5 steps:

• Step 1: Compile the URL to request authorization code
• Step 2: User authorizes WHMCS to access their user profile for the requested information
• Step 3: Receive the authorization code
• Step 4: Request the access token
• Step 5: Receive access token
• Step 6: Use the access token to make requests on behalf of the user

Two files are involved in order to implement this process:

• hook_custom_oauth2.php
  • Located in the in the includes/hooks directory
  • This is where the first step is implemented, compiling the URL to request the authorization code
• custom_oauth2.php
  • Located in the modules/addons/custom-oauth2 directory
  • This is where steps 3, 4, 5 and 6 are implemented

There is also a third file involved, oauth2_providers.php where the ItsYouOnlineProvider class is implemented, deriving from the generic class OAuthProvider.

Each of the three files are discussed below.

hook_custom_oauth2.php

At the bottom of the file we indicate that the function hook_template_variables_custom_oauth2 should be hooked to the ClientAreaPage event.

This function implements step 1 of the OAuth flow, compiling the URL to request an authorization code from Itsyou.online, this will only happen if:

• The user is not yet logged in, for wich the clientsdetails variable is checked
• The user is already logged in, but ths access token is not valid anymore, for which the token_expires_on session variable is checked

The URL is compiled from following parts:

- A randomly generated `state`
- `base URL`, `athorize path`, `redirect URI`, `scope` and `client id` as fetched from the settings as specified on the **OAuth 2.0** configutation page you can access in the WHMCS Admin portal under **Setup** | **Addon Modules**

The URL is saved into the template variable $extraTempateVariables[‘custom_oauth2_login_url’]

- custom_oauth2.php

The function custom_oauth2_clientarea() is called every time the user is logged in successfully, and gets redirected to the Redirect URI as set on the OAuth 2.0 configutation page you can access in the WHMCS Admin portal under Setup | Addon Modules.

So here we implement steps 3, 4, 5 and 6:

• Receive the authorization code (step 3)
  • Before using the authorization code we make sure that the 'state' as returned from ItsYou.online is the same as the state send as part of the URL for requesting authorization code
• Request the access token (step 4), using the call get_oauth_access_token() with following parameters:
  • 'client id' and 'client secret' as set on the OAuth 2.0 configuration page
  • the authorization code as requested in step 1
• Receive access token (step 5)
• Use the access token to make requests on behalf of the user (step 6)
  • Using get_identity() the user identify is fetched and used to create a new user in WHMCS if not already existing
  • Using get_client_jwt_token() for getting the JSON web token (JWT), and storing it as a session variable with name "jwt", from where we will retrieve it for using in the VDC Control Panel

When all this completes successfully the user is redirected to the

• Home page if it was an existing user
• Profile page if is a new user

Other functions in this file are:

• custom_oauth2_config() for setting up the configuration panel of the OAuth 2.0 provider, this is panel under Setup | Addons in the WHMCS Admin Portal
• custom_oauth2_activate()
• custom_oauth2_deactivate()
• custom_oauth2_output()

- oauth2_providers.php

Here the ItsYouOnlineProvider class is defined, which implements all of the methods of the generic class OAuthProvider.

This class is needed to parse the identity response (containing user name, email, address and other things) from the service you plan on using.