OpenID Connect Development

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.

For more information about OpenID Connect, OAuth, and WHMCS, see OpenID Connect.

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

You must use HTTPS for all requests. OpenID Connect requires SSL for all OAuth 2.0 interactions.

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:

ParameterDescription
client_idThe client ID. Obtain this in the Admin Area at Utilities > System > OpenID Connect.
response_typeThe response type. This should always be code.
scopeThe scope. This should always be openid profile email.
redirect_uriThe HTTP endpoint on your server that will receive the response from WHMCS. This must match the URI that you specify when configuring your application inside WHMCS.
You can retrieve endpoint URIs from the discovery document at /oauth/openid-configuration.php in the WHMCS installation. This provides various endpoint URIs, including the Authorization Endpoint URI (authorization_endpoint) and Token Endpoint URI (token_endpoint).
stateThe value of the anti-forgery unique session token, as well as any other information to recover the context when the user returns to your application (for example, the starting URL).

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:

ParameterDescription
codeThe authorization code that the system returned.
client_idThe client ID.
client_secretThe client secret.
redirect_uriThe HTTP endpoint on your server that will receive the response from WHMCS.
grant_typeThis value must be authorization_code.

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:

FieldDescription
access_tokenA token to send to the WHMCS API.
id_tokenA JSON Web Token from WHMCS that contains the user’s identity information. This is a cryptographically-signed Base64-encoded JSON object.
expires_inThe remaining lifetime of the access token.
token_typeThe type of token. The value is always Bearer.

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):

ClaimDescription
issThe issuer identifier for the issuer of the response. This is always the WHMCS System URL value.
subAn identifier for the user that is unique among all WHMCS accounts and that nothing reused. Use sub within your application as the unique identifier key for the user.
audThe intended audience for this ID token. It will be one of your OAuth 2.0 client IDs.
iatThe time at which the system issued the ID token, in Unix time (integer seconds).
expThe time at which the ID token expires, in Unix time (integer seconds).

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: September 10, 2024