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 develop your own integrations with OpenID Connect and WHMCS using the WHMCS API.

Libraries #

If you want to use OpenID Connect in your third-party application to connect with WHMCS, start by selecting an OpenID 2.0-compliant library that is compatible with your chosen programming language.

RFC URLs #

If your application requires the RFC URL, add the following rewrite rule to the .htaccess file in the main folder for your WHMCS installation (usually, public_html):

# OpenID Discovery Document
(http://openid.net/specs/openid-connect-discovery-1_0.html)
RewriteRule ^.well-known/openid-configuration
./oauth/openid-configuration.php [L,NC]

Adjust /oauth/openid-configuration.php appropriately for WHMCS’s position in the directory structure.

Authenticating #

Authenticating the user involves obtaining an ID token and validating it. When a user attempts to log in to WHMCS, your app must perform the following steps:

1. Create an anti-forgery state token. #

You must protect the security of your users by preventing request forgery attacks. To do this, create a unique session token (or cross-site request forgery (CSRF) token) that holds state between your app and the user’s client. You later match this unique session token with the authentication response from the WHMCS OAuth Login service to verify that the user (and not a malicious attacker) is making the request.

We recommend a string of 32 characters from a high-entropy random number generator or a one-way hash that you generate by signing session state information with a secret key.

2. Send an authentication request to WHMCS. #

Applications need OAuth 2.0 credentials, including a client ID and client secret, to authenticate users and gain access to the WHMCS API.

Basic HTTPS POST requests require the following parameters within the OpenID Connect authentication URI:

For example:

https://www.example.com/whmcs/oauth/authorize.php?client_id=WHMCS-DEMO./hW6JgfqRfZ8eCCIsZHQTg==&response_type=code&scope=openid%20profile%20email&redirect_uri=https://oauth2-login-demo.example.com/code&state=security_token%3D138r5719ru3e1%26url%3Dhttps://oauth2-login-demo.example.com/index

3. Confirm the anti-forgery state token. #

In response to the query above, the system provides a redirect URL that includes the code and state values and a validated redirect_uri value.

For example:

https://oauth2-login-demo.example.com/code? state=security_token%3D138r5719ru3e1%26url%3Dhttps://oa2cb.example.com/index&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

On the server, confirm that this state value matches the session token that you created above. This verification helps to ensure that the user is making the request.

4. Exchange code for the access_token value and the ID token. #

The code value is a one-time, short-lived authorization code that your server can exchange for an access token and ID token. Your server makes this exchange by sending an HTTPS POST request. The POST request goes to the token endpoint (token_endpoint in the discovery document).

The request must include the following parameters in the POST body:

If the endpoint is https://www.example.com/whmcs/oauth/token.php, the request could resemble this example:

POST /whmcs/oauth/token.php HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=WHMCS-DEMO./hW6JgfqRfZ8eCCIsZHQTg==&
client_secret={client_secret}&
redirect_uri=https://oauth2-login-demo.example.com/code&
grant_type=authorization_code

A successful response to this request contains the following fields in a JSON array:

5. Obtain user information from the ID token. #

We highly recommend validating the id_token value. Many API libraries combine the validation with decoding the base64 and parsing the JSON.

An ID token is a JSON object containing a set of name and value pairs. For example:

    {
     "iss":"https://www.example.com/whmcs",
     "sub":"78506140-dc6a-4a66-9faa-a3c9e52531a2",
     "aud":"WHMCS-DEMO./hW6JgfqRfZ8eCCIsZHQTg==",
     "iat": 1448466862,
     "exp": 1448466962
    }

WHMCS ID tokens will contain the following fields (claims):

6. Authenticate the user. #

After obtaining user information from the ID token, you can use the sub value in the token. If you have already associated this value with the user of your application, start a session for that user.

• If you have not previously associated the sub value with a registered user of your system, you can redirect the user to sign up or request their email address from the WHMCS installation.
• To associate the sub value with your users, ask the user to log in with their preexisting credentials. After the user successfully authenticates into your application, store the sub value in your database with the database record for that user.

Available Claims #

If you want to get more information about the user, such as their email address, make a claim request with the access_token value from the same response.

You can request the profile and email claims.

Last modified: October 29, 2024