Implementing single sign-on

An administrator can implement single sign-on to allow users to log in once to access multiple applications rather than logging in to the individual applications. Single sign-on can be enabled using SAML 2 or the Custom option.

Access to the single sign-on feature is dependent on your Klipfolio pricing plan. Contact us for more details.

Note: Restriction settings for single sign-on are only available with the Branding+ feature enabled.

This article includes:

Enabling single sign-on using SAML 2

SAML 2 is a secure single sign-on technology that allows you to integrate with a number of different service providers.

Before enabling single sign-on in Klipfolio using SAML 2, have the certificate information you received from your identity management service.

To enable SAML 2 single sign-on:

  1. In Klipfolio, click on your account name and select click Account > Settings.
  2. Click Single Sign-On.
  3. Click Edit.
  4. At Single Sign-On (SSO), select SAML 2.
  5. In the Certificate field, paste your certificate information.
    Note: You will need to remove the lines BEGIN/END from your certificate details.
  6. In your identity management setup, enter the endpoint https://app.klipfolio.com/SAML/consume.
  7. Click Save.
  8. Log in to your identity management service to test your connection.

Enabling custom single sign-on

You can create a custom single sign-on in Klipfolio using your choice of programming language.

To use custom single sign-on, you will need to first enable custom single sign-on in Klipfolio and then configure your connection.

How do I enable custom single sign-on?

To enable custom single sign-on in Klipfolio:

  1. In Klipfolio, click on your account name and select click Account > Settings.
  2. Click Single Sign-On.
  3. Click Edit.
  4. At Single Sign-On (SSO), select Custom.
  5. If you don’t have an existing SSO Secret Key, click Generate New Secret Key.
  6. Click Save.

Important: Generating a new secret key will disable the existing secret key and all users using the existing key will lose access to their dashboards. If you regenerate your secret key, you will need to update the encryption code with your new key.

How do I configure my custom single sign-on?

In order to securely use custom single sign-on, you will need to have an encrypted JSON string. After encrypting your JSON string, you will then need to post to the authentication endpoint. See guidelines for custom single sign-on for more details.

Before you begin to configure your custom single sign-on, make sure you have your Secret Key and your Company ID from your Klipfolio account.

To configure your custom single sign-on:

  1. Use the secret key and company id as part of the salt.
  2. Encrypt using AES/CBC/PKCS5Padding.
  3. Prepend the initialization vector to the encrypted token.
  4. Encode with ciphertext Base64.
  5. POST the encrypted token to the authentication endpoint: /users/sso_auth

Note: The POST must contain the single sign-on token and the ID of the company making the request.

The token can either be sent in:

  • the request header 'KF-SSO' or
  • the request query string parameter 'sso' (url-encoded)

The company ID can either be sent in:

  • the request header 'KF-Company' or
  • the request query string parameter 'company'

Optional: To end a user's session, you can also POST the token to the /users/sso_logout directory.

Tip: You can validate the generated single sign-on token for any error messages at the Klipfolio SSO Test Page.

Guidelines for custom single sign-on

The following are guidelines for creating a single sign-on token for Klipfolio and include a sample of specific implementations based on different languages or platforms.

For users accessing Klipfolio with a modern web browser, such as the latest version of Google Chrome, Apple Safari, Mozilla Firefox, or Microsoft Edge, we suggest you use the POST method to implement single sign-on. Find a list of our supported browsers here.

You must provide Klipfolio with a JSON string that describes the user who is trying to authenticate. The string must be encrypted using AES encryption. The JSON string must include an email address that uniquely identifies the user.

The following table lists the JSON string attributes.

Name Description
email Email address.
expires Token expiry date, specified in Unix time format.
logout_url Optional: Redirection location after logging out.
Note You must select an email address.

Code samples

The following block of code is provided as examples.

Example of a user token that is identified by email:

{

    email : "user@acme.com",

    expires: "1377272230"

}

Language code snippets

Click the following links to download code snippets for most major languages.

Example Transport Code: JavaScript

The following example uses jQuery to POST the single sign-on token to Klipfolio.

In this example, to create a token for a specific user, the value of encrypted token is generated on the server first, and then passed to the user interface.

function initKlipfolioSSO( onSuccess, onError ){

    $.ajax({

        url : "https://app.klipfolio.com/users/sso_auth",

        type: "post",

        xhrFields:{

            withCredentials:true

        },

        headers:{

        "KF-SSO":"<encrypted token>",

            "KF-Company":"<company id>"

        },

        dataType:"json",

       

// on success, the data object will contain information about

        // the authenticated user

        // ----------------------------------------------------------

        success : function(data){

            console.log(data);
                    onSuccess(data);

        },

        // on error, err.responseJSON will contain an error code

        // -----------------------------------------------------

        error : function(err){

            console.log("sso auth failed",err.responseJSON);

                    onError(data);

        }

})

}

After the POST is completed, the user is provided with an authenticated session to Klipfolio. As a best practice, only request a session when a user intends to interact with their dashboard.

// create an SSO session on page-load.

// ------------------------------------------------

$( initKlipfolioSSO() );

 

 

For example, the above code is not recommended as it sends a session request for every page load and will return invalid usage data. Instead, it is preferable to only create the single sign-on session on demand as shown below.

// only request an SSO session when the user wants to view their dashboard

// ---------------------------------------------------------------------------

 

$("#dashboard-link").click( function( ){

    initKlipfolioSSO(

        function(data){

            document.location = "https://app.klipfolio.com/dashboard"

        },

        function(data){

            alert("Dashboard is temporarily unavailable.");

        },

);


})

Troubleshooting single sign-on

The following section includes troubleshooting and resources for the following:

Custom single sign-on fails when logging into Klipfolio

If the single sign-on token for a company account expires, or if a company’s single sign-on token is regenerated, a user might not be able to log into Klipfolio.

To troubleshoot this problem:

  1. Validate a user’s single sign-on token using our Testing Tool.
    Note: You must use a user’s single sign-on token, and not the company’s single sign-on key to perform this test.
  2. Take note of any generated error message.
  3. Go to the error handling section and review the description associated with you error message.
  4. Take corrective action.

If the problem persists, send an email to our Support Team at support@klipfolio.com that includes details of the user’s single sign-on token and the generated error message.

Error handling

The JSON response can help you troubleshoot problems related to single sign-on. A successful request provides information about the authorized user. An unsuccessful request provides one of the following error codes.

Code

Error

Description

1 no_sso_support Single-sign-on is not enabled.  Enable SSO in Account > Settings > Single-Sign-On.
2 token_expired The current time is greater than the token’s specified ‘expires’ time.
3 token_parse Unable to parse the token as a JSON object.
4 no_user_found Unable to find a user for a given email address.
5 user_does_not_belong_to_company The resolved user does not belong to the company making the request.
6 decryption Unable to decrypt the token. Ensure that the token is encrypted/transported to specification.
7 no_token_param The request does not contain the SSO token in either the request header or query string.
8 no_company_param The request does not contain the company-id in either the request header or query string.
9 no_company Unable to find the company for the given id.
10 expires_date_parse Unable to parse the ‘expires’ field. Specify the date in Unix time format.

Related Links

Have more questions? Submit a request