Revision as of 22:05, 24 February 2016

WHMCS acts as an OpenID Connect provider to support single sign-on for applications. To support single sign-on, applications need to act as OpenID consumers.

Applications that support OpenID can use the OpenID Connect details from your WHMCS installation so that WHMCS will act as an authentication provider.

Why offer OpenID to your users?

By leveraging WHMCS as an OpenID provider, you enable your clients to authenticate with other systems and applications using the login credentials of your WHMCS Billing & Support system. That means they only have to remember one username and password, and that's the username and password for your website, making things simpler and easier for the end user and keeping your brand in their mind.

How does it work?

When users visit an application that uses WHMCS as an OpenID provider, users will be presented with a "Login with WHMCS" button, which takes them to your WHMCS Client Portal. The user will authenticate using their login credentials for your WHMCS, if they are not already logged in, and then authorize the use of their profile information, if they have not previously done so. WHMCS will return them to the originating application, where an active logged session is established for them.

The referring application never sees the user's password, so there's no risk to the integrity of the client's authentication data. Subsequent logins to the referring application will not require re-authentication WHMCS so long as they are actively logged in there, but instead the two systems perform a background "handshake" on behalf of the user, creating a seamless, one-click login for the user.

Further Reading

• OAuth
• http://www.openidexplained.com/
• http://www.connect2id.com/learn/openid-connect

Supported Applications

The following applications are officially supported by us:

• cPanel (Version 54 and later)

Setting Up

For an application to use the WHMCS authentication system for user login, the WHMCS administrator must create a set of OpenID Connect Credentials for it to use. In this, the administrator must set an Application Name and Redirect URI(s), along with an optional description and logo image used for branding purposes. API's are also made available to perform these actions programatically and are documented in the OpenID Connect Developer Guide.

Generating Credentials

Applications need a credential set (which includes OAuth 2.0 client ID and client secret) to securely relay information with your WHMCS.

To create a new set of credentials, follow these steps:

1. Navigate to Setup > OpenID Connect
2. Click the Generate New Client API Credentials button
3. Enter the information requested (at minimum a name is required to identify the credential set)
4. Click the Generate Credentials button to create your application's OAuth 2.0 credentials
5. Upon re-load, look for the Client ID and Client Secret in the Client API Credentials section
6. If you add or change any information in any other field, make sure to click Save Changes

Set the Authorized Redirect URIs

The Redirect URI(s) that you associate in the Credentials configuration are used by WHMCS as a canonical list of approved redirect locations for the respective credential set. When a referring application makes a request, it must provide a redirect location. WHMCS will verify that location is in the canonical list and use it after a user has provided authentication and authorization.

To find the redirect URIs for your OAuth 2.0 credentials, follow these steps:

1. Navigate to Setup > OpenID Connect
2. Select the Manage button for your Application. If you haven't created it yet, you can do so by clicking the Generate New Client API Credentials button and filling out the requested information.
3. The Authorized Redirect URIs field on this screen allows you to define the redirect URI you require.
4. If you have multiple URIs, you can add then using the Add another button
5. Click Save Changes

Generate a New Client Secret

The Client Secret can be re-generated in the event that you wish to rotate it for security reasons.

To reset the Client Secret, follow these steps:

1. Navigate to Setup > OpenID Connect
2. Select the Manage' button for your Application.
3. Click the Reset Secret button located next to the current secret in the Client API Credentials section of the page

The previous secret will immediately be rendered invalid and the page will re-load displaying the new secret. Don't forget to set this new secret value at the referring application.

Implementing WHMCS OpenID Connect into your Application

For technical information regarding how to integrate WHMCS as an Authentication Provider for your application, please refer to our OpenID Connect Developer Guide.