Revision as of 19:39, 19 September 2017

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.

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,

The Workflow

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

1. Create an anti-forgery state token
2. Send an Authentication Request to WHMCS
3. Confirm the anti-forgery state token
4. Exchange code for access_token and ID Token
5. Obtain user information from the ID Token
6. 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:

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:

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

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:

Setting up OAuth 2.0 API Methods

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

• ListOAuthCredentials
• CreateOAuthCredential
• UpdateOAuthCredential
• DeleteOAuthCredential