This article provides instructions for configuring Single Sign-On between your website/application authentication system and PHPKB knowledge base software.
PHPKB supports Single Sign-On (SSO) which will allow you to authenticate your end users using your authentication service, such as your web application's login. Once verified, your end users can then view your knowledge base. However, if your end users navigate directly to your knowledge base without first authenticating, they would be redirected to your login page. With SSO user just needs to login once to your website or other application and he immediately and automatically gets authenticated to PHPKB. SSO feature makes user, who's logged into your system, authenticated to your knowledge base. We also provide a simple PHP example that shows how SSO works.
To set up the SSO, you need to configure a few settings from the Miscellaneous tab of "Manage Settings" section in the admin panel.
After setting up the SSO in the knowledge base settings, next task is to call the SSO URL in your script. SSO can be accessed at
<path to your kb> /sso.php
In the above example URL, some parameters namely mode , query and hash are passed to the sso.php script. We will learn about these parameters and how to prepare their values in the steps below.
Next step is prepare the query string parameters for the SSO script. The SSO script operates in two modes; login and logout . Login mode can be accessed only through GET that means query parameters should be passed as $_GET method, however, logout mode can be accessed via both GET and POST.
Query string parameter is mode and possible values for it are login and logout
Important: The mode=login requires two additional parameters " query " and " hash " along with the mode parameter. Details of both query and hash parameters are given below.
a) query: This parameter contains the base64 encoded value of all the important parameters that are passed to the script. There are three mandatory parameters without which script will halt; these parameters are username, name, email. Time stamp (t) is optional but also required if verify timestamp setting is enabled in SSO settings. Along with these, you can also pass groups (comma separated Group IDs) and dl (default language, only in case of multi-language edition) parameters.
You can experiment with timestamp value with online converter: https://www.timestampconvert.com
The Base64 encoded value of the above query string becomes as shown below. You can use this online base64 encoder for testing.
You need to pass this base64 encoded string to the query parameter as shown below.
b) hash: This parameter contains the token required to check the authenticity of the data sent to SSO script. Hash is a sha256 representation of query parameter and secret token specified in the SSO settings.
sha256(base64encoded_query + secret_token)
Important: The plus (+) symbol shown above is only used to represent contactination of Base64 Encoded Query String and the Secret Token. It does not mean that plus (+) symbol is to be used between both while generating SHA256 Hash. So, with the base64 value of query string mentioned above and the secret token used in our SSO settings (in the screenshot above), the concatenated string becomes:
where GTYIY468D4568974 is the value of secret token.
You can use this SHA256 hash generator for testing.
So, the SHA256 value is passed to the "hash" parameter as shown below.
The complete SSO URL with parameters that you can link from your site would look like:
The Logout mode can be called in both ways either through POST or GET. When a user logs out from your site/application, you can either make a call to the SSO script with mode=logout
or can call the above URL through your script with POST call. POST call would return the success status code 200 in JSON format. You can use it to confirm a successful logout of user from the knowledge base.
|400E1||Missing required URL parameter.|
|400E2||Invalid URL parameter received.|
|400E3||Timestamp parameter too old.|
|400E4||User account can not be created because duplicate usernames are not allowed.|
|401E1||Authentication failed; could not authenticate user because of invalid hash.|
|401E2||Could not authenticate request because of invalid domain referrer.|
|404E1||The requested user account is inactive.|
|404E2||The requested user account not found in database.|
|503E1||SSO is not available. SSO is currently disabled.|
Article ID: 180
Created: Wed, May 1, 2019
Last Updated: Thu, Jul 4, 2019
Author: KB Administrator
Online URL: https://www.knowledgebase-script.com/kb/article/phpkb-single-sign-on-sso-reference-guide-180.html