PowerMetrics: 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.

If single sign-on is not included in your pricing plan, you can purchase the Single sign-on (SSO) add-on or upgrade your plan.

This article includes:

• Enabling single sign-on using SAML 2
• Enabling custom single sign-on
  • Guidelines for custom single sign-on
  • Troubleshooting single sign-on

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, make sure you have the certificate information you received from your identity management service.

To enable single sign-on using SAML 2:

1. Click your Account Name (located at the bottom of the left navigation sidebar) and select Account > Settings.
   If you don’t see the above option, click the button in the left navigation sidebar and select 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 set up custom single sign-on, you need to:

1. Enable custom single sign-on in Klipfolio.
2. Configure your custom single sign-on connection.

Enabling custom single sign-on in Klipfolio

To enable custom single sign-on in Klipfolio:

1. Click your Account Name (located at the bottom of the left navigation sidebar) and select Account > Settings.
   If you don’t see the above option, click click the button in the left navigation sidebar and select 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.

Configuring your custom single sign-on connection

To securely use custom single sign-on, you need an encrypted JSON string. After encrypting your JSON string, you 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 connection:

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. Go here for a list of our supported browsers.

SSO implementation may not be supported for browsers in private/incognito mode. If you run into issues, please enable third-party cookies.

If you want to use SSO with Safari, you need to turn off the “Prevent cross-site tracking” option, located in Safari’s privacy settings.

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.

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:

• Ruby
• Python
• PHP
• Perl
• CS
• Java

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
• Error handling

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 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:

Related Links

• Klipfolio API Reference Guide