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.

Contents

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:

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;