Difference between revisions of "OpenID Connect"

From WHMCS Documentation
(→‎Generating Credentials)
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
<div class="docs-alert-info">OpenID Connect is the new emerging standard for single sign-on and identity provisioning on the internet. Its formula for success: simple JSON-based identity tokens (JWT), delivered via the OAuth 2.0 protocol.</div>
+
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.
  
−
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.
+
You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > OpenID Connect'''.
−
 
−
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?==
+
<div class="docs-alert-success">
 +
<span class="title">More Information</span><br />
 +
* For more information on single sign-on using OpenID and a guide to setting this up with cPanel & WHM, see [[WHMCS OpenID and cPanel Setup Guide]].
 +
* For technical information on integrating WHMCS as an authentication provider for your application, see [[OpenID Connect Developer Guide]].
 +
</div>
  
−
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.
+
===Generating Credentials===
−
 
+
−
==How does it work?==
+
To generate a new set of credentials:
−
 
+
# Click '''Generate New Client API Credentials'''.
−
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.
+
# Enter a name, description, URL, and any authorized redirect URIs (see below).
−
 
+
# Click '''Generate Credentials'''.
−
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)
+
When the page reloads, the '''Client ID''' and '''Client Secret''' values will display in the '''Client API Credentials''' section.
  
−
==Setting Up==
+
If you add or change any information after initially generating the credentials, make certain that you click '''Save Changes'''.
  
−
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:
 
−
 
−
# Navigate to ''Setup > OpenID Connect''
 
−
# Click the '''Generate New Client API Credentials''' button
 
−
# Enter the information requested (at minimum a name is required to identify the credential set)
 
−
# Click the '''Generate Credentials''' button to create your application's OAuth 2.0 credentials
 
−
# Upon re-load, look for the '''Client ID''' and '''Client Secret''' in the Client API Credentials section
 
−
# If you add or change any information in any other field, make sure to click '''Save Changes'''
 
−
 
 
===Set the Authorized Redirect URIs===
 
===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.
+
WHMCS uses the redirect URI(s) that you add as a canonical list of approved redirect locations for the credentials. When a referring application makes a request, it must provide a redirect location. WHMCS will verify that that location is in the canonical list and will use it after the user has provided authentication and authorization.
 
   
 
   
−
To find the redirect URIs for your OAuth 2.0 credentials, follow these steps:
+
To find the specified redirect URIs for your OAuth 2.0 credentials, follow these steps:
  
−
# Navigate to ''Setup > OpenID Connect''
+
# Click '''Manage''' for your credentials.
−
# 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.
+
# Find the '''Authorized Redirect URIs''' section.
−
# The '''Authorized Redirect URIs''' field on this screen allows you to define the redirect URI you require.
+
# Make any desired changes.
−
# If you have multiple URIs, you can add then using the '''Add another''' button
+
#* Click '''Remove''' to delete a URI.
−
# Click '''Save Changes'''
+
#* Click '''Add Another''' to add more URIs.
 +
# When you have finished updating your URIs, click '''Save Changes'''.
  
 
===Generate a New Client Secret===
 
===Generate a New Client Secret===
  
−
The Client Secret can be re-generated in the event that you wish to rotate it for security reasons.
+
The client secret can be regenerated if, for example, you want to rotate it for security reasons.
−
 
 
−
To reset the Client Secret, follow these steps:
 
−
 
 
−
# Navigate to ''Setup > OpenID Connect''
 
−
# Select the ''Manage''' button for your Application.
 
−
# 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.
+
To reset the client secret, follow these steps:
  
−
==Implementing WHMCS OpenID Connect into your Application==
+
# Click '''Manage''' for your credentials.
 +
# Click '''Reset Client Secret'''.
 +
# Click '''OK'''.
  
−
For technical information regarding how to integrate WHMCS as an Authentication Provider for your application, please refer to our [[OpenID Connect Developer Guide]].
+
The previous secret will immediately become invalid and the page will re-load displaying the new secret.  Don't forget to set this new secret value at the referring application.

Latest revision as of 20:45, 26 April 2022

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 access this feature at Configuration () > System Settings > OpenID Connect.

More Information

Generating Credentials

To generate a new set of credentials:

  1. Click Generate New Client API Credentials.
  2. Enter a name, description, URL, and any authorized redirect URIs (see below).
  3. Click Generate Credentials.

When the page reloads, the Client ID and Client Secret values will display in the Client API Credentials section.

If you add or change any information after initially generating the credentials, make certain that you click Save Changes.

Set the Authorized Redirect URIs

WHMCS uses the redirect URI(s) that you add as a canonical list of approved redirect locations for the credentials. When a referring application makes a request, it must provide a redirect location. WHMCS will verify that that location is in the canonical list and will use it after the user has provided authentication and authorization.

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

  1. Click Manage for your credentials.
  2. Find the Authorized Redirect URIs section.
  3. Make any desired changes.
    • Click Remove to delete a URI.
    • Click Add Another to add more URIs.
  4. When you have finished updating your URIs, click Save Changes.

Generate a New Client Secret

The client secret can be regenerated if, for example, you want to rotate it for security reasons.

To reset the client secret, follow these steps:

  1. Click Manage for your credentials.
  2. Click Reset Client Secret.
  3. Click OK.

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

Retrieved from "http://3.17.75.209/index.php?title=OpenID_Connect&oldid=32441"