Difference between revisions of "WHMCS Single Sign-On Developer Guide"
From WHMCS Documentation
| (4 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| − | WHMCS Single Sign-on allows trusted applications and third parties to authenticate users into a WHMCS installation automatically, without the user having to re-authenticate. | + | [[WHMCS_Single_Sign-On|WHMCS Single Sign-on]] allows trusted applications and third parties to authenticate users into a WHMCS installation automatically, without the user having to re-authenticate. |
| − | + | ||
Our Single Sign-On implementation is based on the popular and widely used OAuth 2.0 authorization framework which outlines a secure workflow for accessing user data while protecting their account credentials. | Our Single Sign-On implementation is based on the popular and widely used OAuth 2.0 authorization framework which outlines a secure workflow for accessing user data while protecting their account credentials. | ||
| − | + | ||
| + | ==Single Sign-on via API== | ||
| + | The [https://developers.whmcs.com/api-reference/createssotoken/ CreateSsoToken API] is the simplest way to generate SSO Tokens because the action of authenticating with authorized admin API credentials has implicit trust. IE, the API action replaces the first of a two-legged OAuth authentication workflow. | ||
| + | |||
| + | Simply perform the API call and redirect your user to the provided redirect_url. | ||
| + | |||
| + | This method of integration is only appropriate when the remote system is completely isolated from user-level access or modification due to the use of admin level API credentials. | ||
| + | |||
==Single Sign-on Workflow== | ==Single Sign-on Workflow== | ||
| − | + | ||
| − | + | When integrating an application, here's how the process works. | |
| − | + | ||
# The application requests an access token by sending its credentials to the OAuth Token API Endpoint | # The application requests an access token by sending its credentials to the OAuth Token API Endpoint | ||
# If the application credentials check out, the WHMCS auth server will return an access token to the application | # If the application credentials check out, the WHMCS auth server will return an access token to the application | ||
# The application then redirects the user to the Single Sign-On API Endpoint passing in the token and desired destination (scope) | # The application then redirects the user to the Single Sign-On API Endpoint passing in the token and desired destination (scope) | ||
# The user is authenticated and redirected to the requested destination. | # The user is authenticated and redirected to the requested destination. | ||
| − | + | ||
| − | Performing Single Sign-On requires an [https://developers.whmcs.com/api-reference/createoauthcredential/] with the single sign-on grant type. | + | Performing Single Sign-On requires an [https://developers.whmcs.com/api-reference/createoauthcredential/ OAuth Credential Set] with the single sign-on grant type. |
| − | + | ||
| + | This method of integration is appropriate when the remote system provides limited user-level access to input. The trust credentials used (see [https://developers.whmcs.com/api-reference/createoauthcredential/ OAuth Credential Set]) will be limited to the individual user so there is no risk of generating tokens to resources or destinations beyond their ownership. | ||
| + | |||
==Supported Destinations== | ==Supported Destinations== | ||
| − | + | ||
<table class="table table-striped"> | <table class="table table-striped"> | ||
| − | <tr><td>'''Scope Name'''</td><td>'''Destination'''</td></tr> | + | <tr><td>'''Scope Name'''</td><td>'''Destination'''</td><td>'''Variable Input'''</td></tr> |
| − | <tr><td>clientarea:profile</td><td>My Details</td></tr> | + | <tr><td>clientarea:profile</td><td>My Details</td><td></td></tr> |
| − | <tr><td>clientarea:billing_info</td><td>Manage Billing Information/Credit Card</td></tr> | + | <tr><td>clientarea:billing_info</td><td>Manage Billing Information/Credit Card</td><td></td></tr> |
| − | <tr><td>clientarea:emails</td><td>My Emails</td></tr> | + | <tr><td>clientarea:emails</td><td>My Emails</td><td></td></tr> |
| − | <tr><td>clientarea:announcements</td><td>Announcements</td></tr> | + | <tr><td>clientarea:announcements</td><td>Announcements</td><td></td></tr> |
| − | <tr><td>clientarea:downloads</td><td>Downloads</td></tr> | + | <tr><td>clientarea:downloads</td><td>Downloads</td><td></td></tr> |
| − | <tr><td>clientarea:knowledgebase</td><td>Knowledgebase</td></tr> | + | <tr><td>clientarea:knowledgebase</td><td>Knowledgebase</td><td></td></tr> |
| − | <tr><td>clientarea:network_status</td><td>Network Status</td></tr> | + | <tr><td>clientarea:network_status</td><td>Network Status</td><td></td></tr> |
| − | <tr><td>clientarea:services</td><td>My Products/Services</td></tr> | + | <tr><td>clientarea:services</td><td>My Products/Services</td><td></td></tr> |
| − | <tr><td>clientarea:product_details</td><td>Product Details/Information</td></tr> | + | <tr><td>clientarea:product_details</td><td>Product Details/Information</td><td>service_id</td></tr> |
| − | <tr><td>clientarea:domains</td><td>My Domains</td></tr> | + | <tr><td>clientarea:domains</td><td>My Domains</td><td></td></tr> |
| − | <tr><td>clientarea:domain_details</td><td>Domain Details/Information</td></tr> | + | <tr><td>clientarea:domain_details</td><td>Domain Details/Information</td><td>domain_id</td></tr> |
| − | <tr><td>clientarea:invoices</td><td>My Invoices</td></tr> | + | <tr><td>clientarea:invoices</td><td>My Invoices</td><td></td></tr> |
| − | <tr><td>clientarea:tickets</td><td>My Support Tickets</td></tr> | + | <tr><td>clientarea:tickets</td><td>My Support Tickets</td><td></td></tr> |
| − | <tr><td>clientarea:submit_ticket</td><td>Open New Ticket</td></tr> | + | <tr><td>clientarea:submit_ticket</td><td>Open New Ticket</td><td></td></tr> |
| − | <tr><td>clientarea:shopping_cart</td><td>Shopping Cart Default Product Group</td></tr> | + | <tr><td>clientarea:shopping_cart</td><td>Shopping Cart Default Product Group</td><td></td></tr> |
| − | <tr><td>clientarea: | + | <tr><td>clientarea:shopping_cart_domain_register</td><td>Shopping Cart Register Domain</td><td></td></tr> |
| − | <tr><td>clientarea: | + | <tr><td>clientarea:shopping_cart_domain_transfer</td><td>Shopping Cart Transfer Domain</td><td></td></tr> |
| − | <tr><td>clientarea: | + | <tr><td>clientarea:upgrades</td><td>Shopping Cart Addons</td><td>service_id</td></tr> |
| + | <tr><td>sso:custom_redirect (API only)</td><td>Custom path of the WHMCS deployment</td><td>sso_redirect_path</td></tr> | ||
</table> | </table> | ||
| − | + | ||
==Failure Definitions== | ==Failure Definitions== | ||
| − | + | ||
The following are the possible error messages you may receive in working with the Single Sign-On API: | The following are the possible error messages you may receive in working with the Single Sign-On API: | ||
| − | + | ||
''Single Sign-On authentication denied for "Closed" User ID: xx''<br /> | ''Single Sign-On authentication denied for "Closed" User ID: xx''<br /> | ||
Single Sign-On can only be performed for clients in Active or Inactive status. | Single Sign-On can only be performed for clients in Active or Inactive status. | ||
| − | + | ||
''Single Sign-On authentication denied per configuration for User ID: xx''<br /> | ''Single Sign-On authentication denied per configuration for User ID: xx''<br /> | ||
Single Sign-On will not be permitted if the client has disabled it via the Security Settings of their account. | Single Sign-On will not be permitted if the client has disabled it via the Security Settings of their account. | ||
| − | + | ||
''Unable to authenticate with Single Sign-On token for User ID: xx''<br /> | ''Unable to authenticate with Single Sign-On token for User ID: xx''<br /> | ||
If authentication with the given token fails for an unspecified reason. | If authentication with the given token fails for an unspecified reason. | ||
| − | + | ||
''OAuth authorization request denied due to unexpected active login session for "Closed" User ID: xx''<br /> | ''OAuth authorization request denied due to unexpected active login session for "Closed" User ID: xx''<br /> | ||
Indicates the user has an existing active session that they are not permitted to have due to the account status being Closed. | Indicates the user has an existing active session that they are not permitted to have due to the account status being Closed. | ||
Latest revision as of 20:41, 25 August 2020
WHMCS Single Sign-on allows trusted applications and third parties to authenticate users into a WHMCS installation automatically, without the user having to re-authenticate.
Our Single Sign-On implementation is based on the popular and widely used OAuth 2.0 authorization framework which outlines a secure workflow for accessing user data while protecting their account credentials.
Contents
Single Sign-on via API
The CreateSsoToken API is the simplest way to generate SSO Tokens because the action of authenticating with authorized admin API credentials has implicit trust. IE, the API action replaces the first of a two-legged OAuth authentication workflow.
Simply perform the API call and redirect your user to the provided redirect_url.
This method of integration is only appropriate when the remote system is completely isolated from user-level access or modification due to the use of admin level API credentials.
Single Sign-on Workflow
When integrating an application, here's how the process works.
- The application requests an access token by sending its credentials to the OAuth Token API Endpoint
- If the application credentials check out, the WHMCS auth server will return an access token to the application
- The application then redirects the user to the Single Sign-On API Endpoint passing in the token and desired destination (scope)
- The user is authenticated and redirected to the requested destination.
Performing Single Sign-On requires an OAuth Credential Set with the single sign-on grant type.
This method of integration is appropriate when the remote system provides limited user-level access to input. The trust credentials used (see OAuth Credential Set) will be limited to the individual user so there is no risk of generating tokens to resources or destinations beyond their ownership.
Supported Destinations
| Scope Name | Destination | Variable Input |
| clientarea:profile | My Details | |
| clientarea:billing_info | Manage Billing Information/Credit Card | |
| clientarea:emails | My Emails | |
| clientarea:announcements | Announcements | |
| clientarea:downloads | Downloads | |
| clientarea:knowledgebase | Knowledgebase | |
| clientarea:network_status | Network Status | |
| clientarea:services | My Products/Services | |
| clientarea:product_details | Product Details/Information | service_id |
| clientarea:domains | My Domains | |
| clientarea:domain_details | Domain Details/Information | domain_id |
| clientarea:invoices | My Invoices | |
| clientarea:tickets | My Support Tickets | |
| clientarea:submit_ticket | Open New Ticket | |
| clientarea:shopping_cart | Shopping Cart Default Product Group | |
| clientarea:shopping_cart_domain_register | Shopping Cart Register Domain | |
| clientarea:shopping_cart_domain_transfer | Shopping Cart Transfer Domain | |
| clientarea:upgrades | Shopping Cart Addons | service_id |
| sso:custom_redirect (API only) | Custom path of the WHMCS deployment | sso_redirect_path |
Failure Definitions
The following are the possible error messages you may receive in working with the Single Sign-On API:
Single Sign-On authentication denied for "Closed" User ID: xx
Single Sign-On can only be performed for clients in Active or Inactive status.
Single Sign-On authentication denied per configuration for User ID: xx
Single Sign-On will not be permitted if the client has disabled it via the Security Settings of their account.
Unable to authenticate with Single Sign-On token for User ID: xx
If authentication with the given token fails for an unspecified reason.
OAuth authorization request denied due to unexpected active login session for "Closed" User ID: xx
Indicates the user has an existing active session that they are not permitted to have due to the account status being Closed.