Setting up Single Sign-On for Embedded Reports and Dashboards

You can embed reports and dashboards in other applications using a single sign-on (SSO) mechanism. This allows your own authentication mechanism to authenticate the user within your application, after which your application requests an authentication token for the user to access embedded Birst reports and dashboards, for example, in an HTML Iframe. The authentication token is opaque, single use, and has a limited lifetime. All requests (token request, embedding) can be IP restricted on a per-user basis if required. With this approach there is no need for Birst to call back to your authentication system to validate credentials or for Birst and your system to synchronize credentials.

Important: The code for SSO must run on the server side, not on the client side.

There is a two-step process because Birst first needs an SSL encrypted POST to pass the initial credentials (the HTTPS POST to the token generator). Birst can then safely access the reports and dashboards. You only have to pass the birst.SSOToken in the initial request. Subsequently, the session is already established and the user has been authenticated. Remaining requests will pass information via a session-specific cookie (handled transparently via the browser).

Important: Cookies and JavaScript must be enabled on the client browser for Birst to function.

For a list of supported parameters see SSO Parameters.

To enable a space for SSO, perform these steps once

  1. Go to Admin - Manage Space - Modify Properties.  
  2. Check Enable Single-Sign-On.
  3. Click Generate SSO Password to generate a new SSO password.
  4. Click Toggle to show the password, then copy it.
  5. Click Save.

Perform the following steps each time you want to use SSO with your space

  1. Make a POST request to the Birst token generator using the following URL:
    https://<BirstURL>/TokenGenerator.aspx
    1. With the form data being the parameters, such as:
      •  birst.username
      •  birst.ssopassword
      •  birst.spaceId

        POST only – the URL format is for example only – in production the parameters must be posted for security reasons.

        Most parameters start with "birst", but not always. For a list of supported parameters see SSO Parameters. The following parameters are required:
        • birst.username: the account username that will be used for SSO authentication, typically a generic or admin user ID. The user represented by birst.username must already have access to the target space.
        • birst.ssopassword: the one generated for the space in Modify Properties, as described in the previous instructions.
        • birst.spaceId: the ID of the space to be accessed via SSO. The space ID is available from Admin - Manage Space - Modify Properties.
  2. The POST operation returns an opaque token specific to birst.username and birst.SpaceId. The token generator servlet also returns, in the HTTP response header, the base URL that should be used for the SSO servlet. This URL is based upon the URL that the user should be redirected to when they log in (from their release setting). This token has a limited lifetime (15 seconds) and is single use. For example, here is a snippet from the PHP example code:
    global $redirectURLBase;
    if (startsWith($header_line, "BirstURL: ")) # get the redirection URL
    {
    $redirectURLBase = rtrim(substr($header_line, strlen("BirstURL: ")));
    }
    You then use the token to access Birst:
    https://<BirstURL>/SSO.aspx?birst.SSOToken=649...a8eb6

Tip: If your application has multiple pages that embed Birst, you can request the token only on the first time you want to bring up a dashboard and then just reuse it in the IFrame SSO request each additional time. Reusing the same token when a session already exists that was created with that token is allowed and does not cause any errors. Alternatively, use Birst dashboards for navigation. See the ThinkTank thread on this topic.

Setting Session Variables

With the initial SSO token generation request, it is also possible to set session variables:

...&birst.sessionVars= myVar='a','b','c';
Birst$Groups='G1','G2','G3'

Multiple session variables are semi-colon (;) separated. For a given multi-value session variable, values are comma (,) separated. For dynamically assigning a user to groups, use the internal session variable Birst$Groups. All string values, including group names, need to be single-quoted. All date values need to be “#” quoted. If values are not single-quoted or “#” quoted, Birst treats them as Integer.

Note: Session variables have a 255 character limit. Session variables must be 255 characters or less when embedding Birst.

Embedding Birst Reporting or Dashboards in an IFrame

The following examples show how to embed Birst reporting or dashboards directly in an IFrame in your existing web application or portal.

To redirect to original Dashboards:

https://<BirstURL>SSO.aspx?birst.SSOToken=
649...a8eb6&birst.module=dashboard

To go to a specific original dashboard:

https://<BirstURL>SSO.aspx?birst.SSOToken=
649...a8eb6&birst.module=dashboard&birst.dashboard=
<name_of_dashboard>

To go to a specific original dashboard and pass prompt values:

https://<BirstURL>SSO.aspx?birst.SSOToken=
649...a8eb6&birst.module=dashboard&birst.dashboard=
mydashboard&birst.page=mypage&Time.Year=2000

To redirect to Designer or Visualizer  (reporting):

https://<BirstURL>SSO.aspx?birst.SSOToken=
649...a8eb6&birst.module=designer

Or:

https://<BirstURL>SSO.aspx.SSOToken=
649...a8eb6&birst.module=visualizer

To end your session:

…/SSO.aspx?birst.logout=true

Sample Files

See Also
Adding a Tab for Birst in Salesforce.com
Adding a Birst Dashboard to a Visualforce Page
SSO Parameters