PHPKB SAML Single Sign-On (SSO) Reference Guide
This article provides instructions for configuring Single Sign-On between your website/application authentication system and PHPKB knowledge base software.
How Single Sign-On (SSO) works with PHPKB 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.
1. Enabling Single Sign-On (SSO)
To set up the SSO, you need to configure a few settings from the Miscellaneous tab of the "Manage Settings" section in the admin panel.
2. Connecting to SSO
After setting up the SSO in the knowledge base settings, the 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.
3. Preparing SSO Query Parameters
The next step is to 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 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 concatenation 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:
c) redirecttype: When a non-logged in user tries to access the article or category page, the SSO script redirects him to URL specified in 'Return URL' setting along with this parameter which can have any of the two values article or category. After a user logs in to your portal, you can send this parameter back to SSO script to transfer the user to the page which he/she was trying to access.
d) redirectid: This parameter defines the ID of the article/category depending upon the value of the redirecttype parameter. You should send this parameter along with redirecttype parameter to send the user to a precise location.
Now, the complete URL will 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.
|Posted by: KB Administrator - Wed, May 1, 2019. This article has been viewed 1897 times.|
|Online URL: https://www.knowledgebase-script.com/kb/article/phpkb-saml-single-sign-on-sso-reference-guide-180.html|
Powered by PHPKB (Knowledge Base Software)