Revision as of 16:38, 25 November 2015

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,

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:

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

xxxxxx After obtaining user information from the ID token, you should query your app's user database. If the user already exists in your database, you should start an application session for that user.

If the user does not exist in your user database, you should redirect the user to your new-user sign-up flow. You may be able to auto-register the user based on the information you receive from WHMCS, or at the very least you may be able to pre-populate many of the fields that you require on your registration form. In addition to the information in the ID token, you can get additional user information using one of our available claims. 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 ListOpenIDCredentials CreateOpenIDCredential UpdateOpenIDCredential DeleteOpenIDCredential