# Single Sign-On (SSO)

If your customers already have user accounts in your application, you can allow them to log in to your feedback widget using our Single Sign-On (SSO) mechanism. The user does not notice this process at all and so you have an even smoother user experience. 🙌

The Single Sign-On is based on a security mechanism that allows Sleekplan to trust the login requests received from your server. Sleekplan only grants access to users who have been authenticated by you. Sleekplan-SSO uses JSON Web Token (JWT), a technology for the secure exchange of user authentication data.

How does it work?

  • When a user performs an action that requires authentication (such as votes, add feedback), the JavaScript SDKs $sleek.sso function is called.
  • You can hook into the function to generate a token on your server using the private SSO key.
  • Pass the generated token back to your app (The $sleek.sso function has a callback() parameter you can pass the generated token to).
  • We will use the token to authenticate the user.

# 1. Get your SSO secret key

To create a JSON Web Token (JWT), you need the private key for your product. Attention: The private key is only available for the "Starter" and "Business" packages. You can find the private key within the Sleekplan app at Settings -> Developer.

SSO

Make sure that no third party gets access to your private key and that you use it only on the server-side in your application. Otherwise, third parties may gain access to your user data.

# 2. Generate a token on your server

Now you need to generate a JSON Web Token on your server. First, install the appropriate JWT library on your server. Below you can find examples for Node.js, PHP, Python, and Ruby. HMAC with SHA-256 ( HS256 ) is used as an encryption method. Your private key from the previous section is required for this. Replace PRIVATE_SSO_KEY with your private key. In the example below, the parameter localUser represents your local user record.

    Sleekplan requires an email address to uniquely identify the user. In addition to the required attributes listed in the table below, you can also pass additional user and company profile data as needed. This data is synchronized between your user management system and Sleekplan.

    Attribute Required Description
    mail x Email address of the user who is logged in. Used to uniquely identify the user record.
    id - Your internal user identification. It allows you to easily identify users. If provided, this will also be used to identify a user.
    name - Name of the user. The Sleekplan user profile is created or updated according to this value. Use only lowercase letters (a-z), numbers (0-9), and no spaces.
    img - URL to the user's avatar image.
    weight - Assign a weighting (1-10) to a user. You can set this based on your customers' MRR, for example.
    meta - An object or array of key-value pairs to be set for the user.

    # 3. Pass the token into the widget

    Whenever an unauthenticated user performs an action that requires authentication (such as voting, commenting, etc), the SDK method $sleek.sso is called. In your applications JavaScript code, you can assign a function to the sso property as shown below.

    $sleek.sso = function( callback ) {...};
    

    The function must have a callback parameter that passes the JSON Web Token (generated on your server) back to the widget. Now you finally have to get the token from your server. To return the token, an object with a token parameter needs to be passed to the callback({token: 'XXXXXXX'});.







     

     



    $sleek.sso = function( callback ) {
    	// load the current user token from your server side script
    	fetch('https://yourserver.com/your_sso_script/')
    		.then(response => response.json())
    		.then((data) => {
                // get your userToken
    			let userToken = data.ssoToken;
    			// return the generated token to the widget
    			callback( {token: userToken} );
    		});
    };
    

    # 3.1 via setUser() method

    You can also pass a JSON Web Token using the setUser( data ) method. Note that this does not allow you to trigger the SSO process only if authentication is required. Simply call the method and pass an object with your generated token. You can find more information in the related section JavaScript SDK -> Setup user

    $sleek.setUser ( {
        token: 'XXXXXXX', 
    } );