All eazyBI for Jira eazyBI for Confluence Private eazyBI

MultiPass authentication
Private eazyBI

These are instructions for the Private eazyBI version 3.0 or later.

MultiPass authentication can be used to pass other site's user details to eazyBI. Passed user details will be used to log in user in eazyBI (if user with provided email address exists) or to create new user in eazyBI (if user with provided email does not yet exist in eazyBI).

eazyBI MultiPass authentication is based on the Tender application MultiPass solution. Similar solutions are used also by Desk.com and UserVoice applications.

On this page:

Enable MultiPass authentication

Enable MultiPass authentication by adding multipass subsection in authentication section in config/eazybi.toml file (see config/eazybi.toml.sample file for example). Replace site_key with your application short name that you will use as site_key when generating MultiPass tokens. In addition generate unique secret api_key and specify it. Here is example fragment of eazybi.yml file:

[authentication.multipass.site_key]
api_key = "verysecretkey"
create_user = true
update_name = true
create_account_user = true
update_account_user = true

Specify these options (as true or false) according to your needs:

  • create_user - allow creating new eazyBI users from this external application
  • update_name - allow to update eazyBI user name from this external application
  • create_account_user - allow creating new access to the specified account with the specified role
  • update_account_user - allow to update existing access to the specified account and update with the specified role

Build MultiPass token

MultiPass token is built from list of key / value pairs which is encoded in JSON and then AES encrypted using site_key and api_key.

KeyRequired?Value
emailYesUser email which is used as unique user identifier in eazyBI.
nameYesUser full name which will be used as user display name in eazyBI.
expiresYesMultiPass expiration date in ISO 8601 format. MultiPass token will not be valid after expiration. Typically expiration date is set as very near future time (e.g. 5 minutes from now).
toNoURL to redirect user after successful authentication. Just relative URL path (e.g. /eazybi/home) can be provided. If this key is not provided then user is redirected to eazyBI default home page after authentication.

account_id

account_name

NoSpecify either account_id or account_name to which user should have access. Will be used only if create_account_user and/or update_account_user options are enabled.
roleNoSpecify one of the following account user roles - user_admin, data_admin, reports_admin, user, viewer or dashboards_viewer.
data_access_rolesNoIn case of custom schema account specify data access roles (as JSON array of strings, for example, ["California manager"]) if they are defined in custom schema definition.

See Ruby, PHP and JavaScript (Node.js) code examples in examples/multipass directory how to generate MultiPass token using provided key / value pairs.

Use MultiPass token for authentication

Redirect user to the following eazyBI URL for MultiPass authentication:

<eazyBI host and port>/eazybi/users/multipass/site_key?multipass=multipass_token

Replace site_key with your site key specified in eazybi.yml and replace multipass_token with generated token as described in previous section. If you have changed eazyBI URL prefix (with EAZYBI_PREFIX environment variable) then use it instead of default /eazybi prefix.

After successful authentication user will be redirected either to default home page or to URL specified in MultiPass to key value. If authentication will be unsuccessful then user will be redirected to eazyBI login page as well as unsuccessful MultiPass authentication will be registered in system events and in eazyBI log file.

Use MultiPass authentication for embedded reports

If you have created report in eazyBI then you can click </> toolbar icon to get iframe code for embedding in another HTML page. In src attribute it will contain link to corresponding report:

<eazyBI host and port>/eazybi/accounts/account_id/embed/report/report_id

To use MultiPass authentication when embedding iframe in another web page you need to make the following modifications:

  • When making MultiPass token you need to include in it to attribute which is relative URL of the embedded report:
    /eazybi/accounts/account_id/embed/report/report_id
  • In iframe src attribute use:
    <eazyBI host and port>/eazybi/users/multipass/site_key?multipass=multipass_token
    After successful authentication iframe content will be redirected to to attribute URL with embedded report.

If you have page in your application with very many embedded iframes then another solution with fewer redirects would be more efficient for that:

  • Store in your application session if user is already authenticated in eazyBI.
  • If user clicks in your application on some page link which contains eazyBI reports then you check in user session if eazyBI authentication has been already made. If not then construct MultiPass token and in to attribute specify full URL back to your application page. So user will be redirected to eazyBI and back again to your application (if authentication was successful then user will not even notice these redirects).
  • Then in your application page use iframes with eazyBI embedded report URLs and they will display successfully as their browser will now have also cookie for eazyBI session.