You're browsing the documentation for an old version of SupportPal. Consider upgrading to the latest version.

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
SimpleAuth for Operators
Error Handling
Sample Code

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 token
email - the email address of the user we would like to login
jti - 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

To run the below code sample you need to also make use of the firebase/php-jwt library.


    <?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);

    // Set login URL
    $loginUrl = rtrim($baseUrl, '/') . '/simpleauth/login';

    // Generate request and access it
    $request = $loginUrl . '?token=' . $jwt . '&redirect=' . urlencode($redirectUrl);
    header("Location: $request");
    exit;