SimpleAuth (SSO)
SimpleAuth is an automatic authentication (single sign-on) method to allow you to log users in to SupportPal from third party code/software. Useful in integrations with other client management software, it will generate a session for the user without them having to do anything or requiring the user's password.
Using SimpleAuth
To use SimpleAuth, we need to generate a secure access token for each request. JSON Web Tokens (JWT) are an open, industry standard RFC 7519 method for securely representing claims between two parties. A number of libraries have been written to generate JWT tokens in various programming languages.
The payload of the JWT token must contain the following components:
exp
- expiry time of the tokenemail
- the email address of the user we would like to loginjti
- unique identifier for the token
The token should then be encoded using your SimpleAuth key. The key can be found under Settings -> General Settings -> SimpleAuth in the operator panel.
Once the token has been generated, it can be used on the below routes:
Route | Method | |
---|---|---|
Login URL | /simpleauth/login |
HTTP GET or POST |
Logout URL | /simpleauth/logout |
HTTP GET or POST |
Each of the above routes accept the following parameters:
Parameter Name | Description | Example |
---|---|---|
token |
JWT token as described above. | ?token=bdc391437d78377767b5d435356e04eb |
redirect |
Optional. Redirect the user to the specified URL after logging in / out, falls back to the SupportPal home page. | ?token=bdc391437d78377767b5d435356e04eb&redirect=http://domain.com/clientarea.php |
brand_id |
Optional. Brand ID that the user belongs to, if not specified will attempt to detect the brand based on the URL. | ?token=bdc391437d78377767b5d435356e04eb&brand_id=1 |
SimpleAuth for Operators
SimpleAuth can also be enabled for operators to allow automatic logging in. This feature is disabled by default and can be enabled by going to Settings -> General Settings -> SimpleAuth in the operator panel and toggling the Allow for Operators option.
The same as above applies, however the route also contains the admin folder. Taking the example above and where the admin folder is set to the default of 'admin', this would become
<base_url>/admin/simpleauth/login?token=bdc391437d78377767b5d435356e04eb&redirect=http://domain.com/clientarea.php
Error Handling
If the token is invalid, the script will return a json string that contains details of the error.
Sample Code
<?php
use \Firebase\JWT\JWT;
$baseUrl = 'https://www.supportpal.com/support';
$redirectUrl = 'https://www.supportpal.com/manage/clientarea.php';
$simpleAuthKey = 'RhqFi31PpIe0eIyP08fNqA';
// Generate token
$token = array(
'exp' => time() + 60,
'email' => '[email protected]', // <-- Change me
'jti' => uniqid() . mt_rand(100000, 999999)
);
// Encode token with simple auth key
$jwt = JWT::encode($token, $simpleAuthKey, 'HS256');
// Set login URL
$loginUrl = rtrim($baseUrl, '/') . '/simpleauth/login';
// Generate request and access it
$request = $loginUrl . '?token=' . $jwt . '&redirect=' . urlencode($redirectUrl);
header("Location: $request");
exit;