OpenID Connect Developer Guide

Looking for the OpenID Connect User Guide? Click here...

Getting Started

To get started, you'll need to select an OpenID 2.0 compliant library compatible with your programming language.

The best place to look is the Getting Started Guide on OpenID.net. Google's OpenID documentation is also very useful. There are dozens of libraries in all major languages.

If you application needs to use the RFC URL , please add the following rewrite rule to the .htaccess file in the main folder of the website where WHMCS is installed (usually called public_html), adjusting /oauth/openid-configuration.php accordingly if WHMCS is installed in a sub-folder:

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

Authenticating the User

The OAuth 2.0 APIs in WHMCS can be used for both authentication and authorization. This document describes our OAuth 2.0 implementation for authentication, which conforms to the OpenID Connect specification.

Authenticating the user involves obtaining an ID token and validating it. ID tokens are a standardized feature of OpenID Connect designed for use in sharing identity assertions on the Internet.

Authorization Endpoint

You should retrieve the Authorization Endpoint URI and all other Endpoint URIs from the Discovery document located at https://www.example.com/whmcs/oauth/openid-configuration.php. This provides various endpoint URIs, including the Authorization Endpoint URI and Token Endpoint URI, defied as authorization_endpoint and token_endpoint,

Important Note: HTTPS must be used for all requests. SSL is required for all OAuth 2.0 interaction per the OpenID Connect specification.

The Workflow

When a user tries to log in with WHMCS, you need to:

Create an anti-forgery state token
Send an Authentication Request to WHMCS
Confirm the anti-forgery state token
Exchange code for access_token and ID Token
Obtain user information from the ID Token
Authenticate the User

Create an anti-forgery state token

You must protect the security of your users by preventing request forgery attacks. The first step is creating a unique session token that holds state between your app and the user's client. You later match this unique session token with the authentication response returned by the WHMCS OAuth Login service to verify that the user is making the request and not a malicious attacker. These tokens are often referred to as cross-site request forgery (CSRF) tokens.

Best practices for generating state tokens is beyond the scope of this document. At a minimum, we suggest a string of 32 characters constructed by a high-entropy random number generator. Another suggest is a one-way hash generated by signing session state information with a key that is kept secret on your back-end.

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. Instructions for provisioning these can be found in the OpenID Connect End User Documentation.

For a basic HTTPS POST request, the following parameters are required:

client_id which you obtain from the OpenID Connect Management interface within WHMCS
response_type which should be code.
scope which in a basic request should be openid profile email.
redirect_uri should be the HTTP endpoint on your server that will receive the response from WHMCS. This must match the URI you specified when configuring your Application inside WHMCS.
state should include the value of the anti-forgery unique session token, as well as any other information needed to recover the context when the user returns to your application, e.g., the starting URL.

Here is an example of a complete OpenID Connect authentication URI, with line breaks and spaces for readability:

 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

Confirm the anti-forgery state token

In response to the query above, a redirect is performed where in the target URL will be the provided (and validated) redirect_uri with a code parameter and the state that you specified in the request. All responses are returned in the query string, as shown below:

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

On the server, you must confirm that the state received from WHMCS matches the session token you created in Step 1. This round-trip verification helps to ensure that the user, not a malicious script, is making the request.

Exchange code for access token and ID Token

The response includes a code parameter, 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 is sent to the token endpoint, which you should retrieve from the Discovery document using the key token_endpoint. The following discussion assumes the endpoint is https://www.example.com/whmcs/oauth/token.php. The request must include the following parameters in the POST body:

code	The authorization code that is returned from the initial request.
client_id	The client ID that you obtain from the Developers Console, as described in Obtain OAuth 2.0 credentials.
client_secret	The client secret that you obtain from the Developers Console, as described in Obtain OAuth 2.0 credentials.
redirect_uri	The URI that you specify in the Developers Console, as described in Set a redirect URI.
grant_type	This field must contain a value of authorization_code, as defined in the OAuth 2.0 specification.

The actual request might look like the following 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:

access_token	A token that can be sent to a WHMCS API.
id_token	A JWT that contains identity information about the user that is digitally signed by WHMCS.
expires_in	The remaining lifetime of the access token.
token_type	Identifies the type of token returned. At this time, this field always has the value Bearer.

Obtain user information from ID Token

An ID Token is a JWT (JSON Web Token, https://tools.ietf.org/html/rfc7519), that is, a cryptographically signed Base64-encoded JSON object.

We highly recommend validating this signed token. Many API libraries combine the validation with the work of decoding the base64 and parsing the JSON, so you will probably end up validating the token as you access the fields in the ID token. You may also what to visit http://jwt.io/ for more information on JWT.

An ID token's payload

An ID token is a JSON object containing a set of name/value pairs. Here’s an example, formatted for readability:

{
 "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 (known as claims):

iss	The Issuer Identifier for the Issuer of the response. Always the System SSL URL for your WHMCS installation
sub	An identifier for the user, unique among all WHMCS accounts and never reused. Use sub within your application as the unique-identifier key for the user.
aud	Identifies the audience that this ID token is intended for. It will be one of the OAuth 2.0 client IDs of as generated by your WHMCS installation and used by your application.
iat	The time the ID token was issued, represented in Unix time (integer seconds).
exp	The time the ID token expires, represented in Unix time (integer seconds).

Authenticate the User In Your Application

After obtaining user information from the ID token, you can utilize the sub value in the token. This value is unique to the user that has been authenticated and provided authorization at your WHMCS Billing & Support installation. If you have already associated this value with the user of your application you should start an application session for that user.

If you have not previously associated the sub with a registered user of your system, you can can either redirect the user to your new-user sign-up flow or request more information about the user from the WHMCS Billing & Support installation in order to receiver their email address. The latter would only be beneficial if you need the user's email as part of your association process or if you wish to pre-populate any fields for a registration or login form.

Associate the sub value with your users can be done once by asking the user to login with their pre-existing credentials in your application. After the user successfully authenticates into your application, you would store the sub value in your database related to your database record for that user.

If you want to get more information about the user, such as their email address, you would make a claim request with the access_token that was provided in the same response as the JWT.

Available Claims

The following claims are available:

Claim Name	Supported Version
profile	6.2.0+
email	6.2.0+

Setting up OAuth 2.0 API Methods

The following API commands exist for interacting with OAuth/OpenID Connect credentials in WHMCS:

Documentation