Using Web Access Tokens
  • 25 May 2022
  • 16 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Using Web Access Tokens

  • Dark
    Light
  • PDF

General Information

Introduction

The Web Access Token feature grants a secure, scalable and highly customizable Viewer role experience while interacting with Sisense assets, all done without providing credentials or utilizing cookies in the flow. This experience is intended to be compatible with all types of embedding, as well as standalone deployments, and should therefore cover a big portion of the Sisense use cases that were previously not possible.

Note:

Web Access Tokens are only supported for Sisense applications that have the Web Access Token feature included in their Sisense license agreement.

Intended Users

One of the main advantages of a Web Access Token is the ability to generate sessions with parameters and override any existing context and settings in the application. All end user actions are volatile and stateless, meaning that several users can outreach to analytical content simultaneously and interact with this content on the viewer level, without affecting one another or changing the asset’s original content.
This ability enables mostly large enterprise and OEM customers to infuse Sisense with both anonymous and public access to their assets, while at the same time having strong control over end user permissions.

Technical Basics

Web Access Tokens exist in the form of JSON Web Encryption (JWE). The tokens conform with IETF standards, providing a standardized syntax for exchanging encrypted data based on JSON and Base64, defined by RFC7516. Along with JSON Web Signature (JWS), a Web Access Token is one of two possible formats of a JWT (JSON Web Token). JWE forms part of the JavaScript Object Signing and Encryption (JOSE) suite of protocols.
In a nutshell; JWE, like JWT, is a URL-safe representation of the data segments separated by “.”, the main difference being that the payload in JWE is compressed and encrypted with the public key, making it impossible for end users to determine the token’s payload, and preventing them from gaining a personal advantage.
There are libraries on key development platforms supporting the generation of JWE tokens. References to the libraries are available in the examples of the Web Access Tokens generation methods, outlined below.

Setup Flow

Enabling Web Access Token-based access is done by performing a combination of the following two processes:

  • The conventional Sisense flow of designing assets in the application, including creating a dashboard with widgets, applying filters and security rules, sharing with team members if required, etc,.
  • To prepare the payload with claims that represent permissions and customization to be overridden per token, and to generate a Web Access Token based on these parameters.

Once the token-based link is generated, it can be issued to any end user analytic consumer, who in turn gains Viewer access to the asset which is overridden by the desirable customization and/or settings when included into the token’s claims.

Getting Started

This section describes how to design token-based access to your assets and how to start using the Web Access Token feature.

  1. Contact your organisation’s CSM with a request to activate Web Access Token license.

  2. Navigate to the Admin page and select Feature Management to activate the Web Access Token feature.
    Activate_WAT.png

  3. Create or select a Sisense dashboard or widget intended to be made accessible via the Web Access Token.

  4. Create or select a target Viewer role user intended to be granted access, and share the widget or dashboard with them. The end analytical consumer is granted access to the asset, on behalf of this Viewer role user, to whom the asset is shared.

  5. Navigate to the Admin page and select Web Access Tokens.

  6. Create a new token configuration. You need to know the values of Secret and Key ID for steps 7 and 9, below.

Notes:

Make sure to store 'Secret' (public key) in a secure and accessible place for future usage, as it cannot be retrieved from the application afterwards.
‘Secret’ and ‘Key ID’ values are shown in the Add Key configuration dialog box - once only - upon creation, as shown below.

Add_Key.png

  1. Have your development environment prepared, and design your internal tool for generating JWE tokens.
    List of the approved libraries:

An example of the above-mentioned library usage is a part of the documentation package.

  1. Prepare the data for the token’s header, which should include:

    • “typ“:“JWT” → fixed value - defines the type of the content
    • “alg“:“RSA-OAEP-256“ → fixed value - encryption algorithm of the Content Encryption Key (CEK)
    • “enc”:“A128GCM” → fixed value - encryption algorithm for the JWT claims
    • “zip”: “DEF” → fixed value - compression algorithm
    • “kid”: “Key ID value of the created token configuration“
      • Displayed while creating a new token configuration, or available by navigating to the Admin page and selecting Web-Access Tokens > Token Configuration > Edit.
  2. Prepare the token’s payload data, which should include:

    • “sub“: “user’s Sisense ID on behalf of which access is granted“
      • Can be retrieved from Admin → Users → Edit → [ Copy user Identifier ]
  3. Any other optional claim, depending on your needs. “sub“ is the only one required at the moment.

  4. Generate the JWE token via your internal toolbox or Sisense POST​/wat​/generate endpoint, based on the header, payload, and public key.

    Note:

    Click here for simple examples of implementing the token generation tool and utilizing Web Access Token.

  5. Insert the token into the asset’s link in accordance with the following format:​
    mysisense.com/wat/insert_your_generated_token/app/main#/dashboards/dashboard_id/widgets/widget_id

  6. Carefully test the newly-created Web Access Token by accessing it and checking what the end user sees and is able to do.

  7. Share the link with the users. Alternatively, you can perform the steps for generating a Web Access Token for embedding, if that is your business case.

Supported Claims

Web Access Tokens are mostly intended for users with a programming background, for dynamic control over session lifetimes, data permissions, and user experiences. At the same time, there is the ability to grant access with an as-is reference to a specific 'sub' user’s settings.

Opaque Tokens (By Reference)

To use this approach, enter the Web-Access Token’s minimal required parameters, listed below:

  • Header
token_header = {
    #  --- Fixed set of fields in the token Header ---
    # Type of token
    'typ': "JWT",
    # Encryption algorithm of the Content Encryption Key (CEK)
    'alg': 'RSA-OAEP-256',
    # encryption algorithm for the JWT claims
    'enc': 'A128GCM',
    # Compression algorithm
    'zip': 'DEF',
    # --- Sisense WAT specific fields in the token header ---
    # Unique identifier of the token configuration
    'kid': "6102ad6c86792300351fd952"
}
  • Payload
{
  "sub": "6128c62ea23e09002c411453"
}
 
  • Signature
-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAq/38zSIYIwreL3eKC8ZqCEr+h8ohYgVh4FLlknO+sO+kTC9eln+mHnMExnYPQiBOIFDbY4WL2oa3jB21mo8ooZEJUyJ5fU473YUVKY6nO/OuWjkGyCPZUQ2nXlqIgFV7QZ3KBbkvYM52+TasO6+39+30j1s8tw+57LduzoQIuipOV3JsJQOY/RgKYfUhj6Hz1nrvhDGm/PPx23rf3hYje2QCCuWtk0nNGDmGqQGly3dfpLJukVRViBYPbC2ic6dY1VNHrQvCu7ZzbOqq25a3Qr+PBW1RJ8nsPwEpz4MsdyDbG77nndNHgO4+fp7XbJ4KHfwGAtqB+5Ehygin/mRJuQIDAQAB-----END PUBLIC KEY-----

Structured Tokens (By Value)

Sisense enables you to parameterize context and user permissions per token session, according to business needs. If the token’s payload includes the claim, it overrides the existing (native) Sisense value, or permission.
Required parameters for the token’s header and payload are identical to that of the Opaque Token approach shown above.
Supported optional claims for Web Access Tokens that can be specified currently in the payload, are as follows:

  1. “exp“
    The "exp" (expiration time) claim identifies the expiration time on, or after which, the JWT MUST NOT be accepted for processing.
    Suggested modes of utilizing this claim:

    • Security: Dynamically generate an expiration value based on the time needed for the initial system to load, per individual user session. This prevents unauthorized access in the event that the token was exposed.
    • Timeline: Specify a timeframe for token-based access to the asset. For example, make it available for a 24 hour period.
    • Infinite: Null value or not including ”exp" into the payload sets the asset as accessible forever.

Type → Unix timestamp

Example:

{
"exp": 1757326503
}

  1. “nbf“
    The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing.

Type → Unix timestamp

Example:

{
    "nbf": 1631098685
}
  1. “iat“
    The "iat" (issued at) claim defines the time at which the JWT was issued. Currently, there is no logic implemented in Sisense for this claim and it can therefore be defined as per the customer’s preferences.

Type → Unix timestamp

Example:

{
"iat": 1631098710
}

  1. “iss“
    The "iss" (issuer) claim identifies the principal that issued the JWT.
    Currently, there is no logic implemented in Sisense for this claim and it can therefore be defined as per the customer’s preferences.

Type → String

Example:

{
"iss": "any string
}

  1. “grants”
    Structural (parent) claim for specifying token permissions(“res”, “flt”, “prm”) within. Permissions entered outside of “grants” are ignored.

Type → Object

Example:

{
    "grants": {
        "res": ["dashboards/ID1", "dashboards/ID2"],
        "flt": [{
            ... JAQL Filter 1 ...
        }, {
            ... JAQL Filter 2 ...
        }]
    }
}
  1. “res“
    Specifies the list of dashboards that are allowed to be accessed via the Web-Access Token. This should be specified in the following format:
    “dashboards/dashaboard_id“ separated by a comma. The simplest way to obtain it is by copying it directly from the Sisense URL.
    If you want to provide access to the widget, and your Web-AccessToken-based link leads to the widget accordingly, there is no need to specify widget_id in the "res", as having a parent dashboard is enough.

    • “res“ is not included in the token’s payload: Sharing permissions from native Sisense are inherited, meaning that the end user is able to access the same dashboards as "sub" users in the native Sisense system.
    • "res": [ ]: The user is unable to access any of the dashboards or widgets.
    • "res": ["dashboards/ID1", "dashboards/ID2"]: The user is able to access only dashboards ID1 and D2, regardless of what dashboards are available for "sub" user in the native Sisense system.

Type → Array of objects

Example:

{
    "grants": {
        "res": ["dashboards/ID1", "dashboards/ID2"],
        "flt": [{
            ... JAQL Filter 1 ...
        }, {
            ... JAQL Filter 2 ...
        }]
    }
}
  1. "flt"
    Specifies filters that should be applied on the dashboard level of the asset in a Web Access Token-based environment. Widget filters are inherited as-is from the native Sisense application. Filters should be specified as per the official Sisense JAQL Syntax Reference.​

    • “flt“ not included: Inherits as-is filters from the native Sisense system for both widget and dashboard levels.
    • "flt": [ ]: Erases all existing filters from dashboard level only, and inherits widget level filters, if there are any in the native Sisense system.
    • "flt": [{jaql filter1}, {jaql filter2}]: Overrides the original Sisense dashboard filters if any are applied with the ones from the claim:

The filter from the “flt“ claim only applies to the dashboard level (regardless of whether a token's link destination is a dashboard or widget).

Type → Array of objects

Example:

{
    "grants": {
        "flt": [
            {
                "jaql": {
                    "table": "Commerce",
                    "column": "Condition",
                    "dim": "[Commerce.Condition]",
                    "datatype": "text",
                    "filter": {
                        "members": ["New"]
                    },
                    "title": "Condition"
                }
            }
        ]
    }
}

8."acl"
The Web Access Token enables applying data security rules for each token, and in doing so, dynamically defining the scope of available data for the end analytical consumer, on a per business case basis.

"grants": { "acl": [ {acl1}, {acl2}, etc ] }

The overall approach of processing "acl" is similar to other available claims:

  • "acl" is not specified or outside of the "grants": { } claim → inherits as-is data security from the native Sisense system, if any exist and were applied to the user from "sub".
  • "acl": [ ] → erases all existing data security rules applied to a "sub" user in the native Sisense system. In such cases there is no data security whatsoever applied.
  • "acl": [ {acl1}, {acl2}, etc ] → overrides any existing data security applied to a “sub“ user in native Sisense to those received from the token.

Structure and format a token’s data security as follows:

"grants": {
	"acl": [
		{
			"dataSourceTitle": "Sample ECommerce",
			"table": "Commerce",
			"column": "Gender",
			"allMembers": null,
			"datatype": "text",
			"members": [
				"Male"
			],
			"exclusionary": false
		}
	]
}

To correctly apply data security, you must include the new "dataSourceTitle" parameter (containing the title of the queried data source) to each "acl" claim object.

Note:

The data security rule is ignored if no widgets are based on the same data source as specified in "dataSourceTitle". Data security, as well as other claims in a Web Access Token flow do not work in 'addition' mode. Settings are either inherited from the native Sisense or replaced with the settings from the "acl" claim, as long as the claim is included in the payload. Therefore, the data security rule is ignored if no widgets are based on the same data source as specified in "dataSourceTitle".
Example:

  • A dashboard is based on four different data sources; A, B, C and D, each of which has data security configured in native Sisense.
  • Passing "acl": [{"dataSourceTitle": "A", ....}] applies data security in the Web Access Token environment to any widget based only on data source A.
  • The widgets based on data sources B, C and D have no data security applied or inherited from native Sisense.

Therefore, make sure to specify data security per data source, if such is required in your business case. Alternatively, if you want native Sisense data security to be inherited, do not include the “acl“ claim.

  1. “prm“
    Specifies end user permissions for the Web Access Token environment within the scope of the ‘Viewer’ role level.

Type → Array of strings

Example:

{
  "grants": {
    "prm": [
      "filter",
      "export"
    ]
  }
}

  1. “prm“: [“filter“]
    Regulates the ability to work with filters on the ‘Viewer’ role level:
    • “prm” not included: The user can work with filters on the default ‘Viewer’ role level.
    • "prm": [ ] / "prm": ["export"]: The ability to work with filters is blocked. The user is able to see the filters applied, yet unable to manipulate them. The filter’s panel is in read-only mode.
    • "prm": ["filter"]: The user can work with filters on the ‘Viewer’ role level.

Type → String

Example:

{
  "grants": {
    "prm": [
      "filter",
      "export"
    ]
  }
}
 
  1. “prm“: [“export“]
    The exporting of WAT-based assets is only supported when the New Exporting service is utilized in the Sisense instance.

The following claim configurations and settings are considered in the asset’s exported copy:
* Filters (including user manipulations)
* Data security
* Look and feel themes
* Interface language

Type → String

Example:

{
  "grants": {
    "prm": [
      "export"
    ]
  }
}
  1. “lng“

The Web Access Token feature supports defining the interface language per each Web Access Token at any stage, by including the "lng" claim with its value, into the token’s payload.

Listed below are the supported languages and associated corresponding formats:

  • Chinese (PRC) “zh-CN”
  • Dutch “nl-NL“
  • English (US) “en-US“
  • French “fr-FR“
  • German “de-DE“
  • Italian “it-IT“
  • Japanese “ja-JP“
  • Korean “ko-KR“
  • Portuguese “pt-BR“
  • Russian “ru-RU“
  • Spanish (Argentina) “es-AR“
  • Spanish (Spain) “es-ES“
  • Turkish “tr-TR”

Type → String

Example:

{
"lng": "de-DE"
}

See Changing Sisense’s Language for further information on changing the language in Sisense.

  1. “thm"

The Web Access Token feature supports defining the Look and Feel (appearance) for end analytical users, by including the desired theme's oid into the token’s payload. Having a specified UI customization theme affects any user who access analytical assets via the token. Otherwise another UI theme, based on the priority, is applied.

Type → String

Example:

{
"thm": "62011a15c2eb04001bbf85e8"
 
}

Using Embedding

Sisense helps you deliver insights at the point of decision making by enabling you to embed Sisense within your application using Web Access Token. Read more information on embedding Sisense here.

Iframe

The Web Access Token feature is compatible with Iframe embedding, meaning that you can infuse Sisense analytical content using Iframe and enable users to access it via the token.
The process is similar to configuring access with native Sisense.
To infuse Sisense analytical content using Iframe:

  • Generate a link for an embedded solution with additional parameters, according to your needs: mysisense.com/app/main#/dashboards/dashboard_id?embed=true&l=false&r=true;
  • Generate a Web Access Token.
  • Insert the token into the embedding link to the asset, according to the following format: mysisense.com/wat/insert_your_generated_token/app/main#/dashboards/dashboard_id?embed=true&l=false&r=true
  • Utilize the link in your embedding solution.

Embed SDK

A dedicated wat parameter is available to enable token-based access to the Embed SDK solution. Include the wat parameter with a generated Web Access Token while configuring your Embed SDK and enrich your infusion experience.
See Embed SDK - Getting Started for further information on configuring Embed SDK.

The WAT-based environment provides limited Embed-specific SDK actions usage for aligning a feature's viewer role experience with the Embed SDK capabilities.
The following actions are supported and synchronized with the permissions granted, per token, in a "prm" claim:

  • dashboard.applyFilters
  • dashboard.export

The following actions are blocked:

  • dashboard.removeFilters(filters, persist)
  • dashboard.openSimplyAsk()
  • dashboard.createWidget()
  • dashboard.createTextWidget()
  • dashboard.share()

The other Embed SDK actions are unaffected.

The following table describes the matrix for applying filters in WAT-based Embed SDK dashboard:
WAT_ Apply_Viewer-role_Embed_SDK_2.png

Sisense.js

Enhance your company’s embedding needs using Sisense.js, a JavaScript library that enables you to embed Sisense components in web pages without the use of iFrames.
You can access analytical content embedded via the Sisense.js based on the Web Access Token authentication method. Generate the Web Access Token (containing the required configuration and customization) and include it into the Sisense.js constructor’s dedicated WAT parameter.
End user experiences in Sisense.js are volatile and are limited to the Viewer role level (as are all Web Access Token use cases).
For more information on configuring Sisense.js, see Sisense.JS - Getting Started.

Working with UI Theme in the Embedding

As a Look and Feel theme can be defined in several places, the following hierarchy of priorities should be taken into consideration:

  1. Embedded parameter (Iframe/Embed SDK/Sisense JS)
  2. Web Access Token
  3. Group association
  4. System-level (Default)

For more information about customizing Look and Feel, see Customizing the Sisense User Interface.

Using Add-ons

Sisense is currently developing full support and compatibility for Sisense-certified add-ons in Web Access Token-based environments.
The only add-on currently aligned and approved for Web Access Token usage is Jump to Dashboard.
All other add-ons are currently undergoing verification and alignment, and therefore should be used at your own risk and responsibility.

Testing

An API is provided for testing an (existing) generated token for its structure, logic, and data validation to determine any reason(s) why a token may be faulty, or simply to ensure it has been properly generated. Check REST API 1.0 /web-access-tokens.

Monitoring Usage Statistics

The term 'usage' specifically refers to each successfully established Web Access Token-based session, or in other words; when a user clicks the Web Access Token link and a token “session” is created, or a Web Access Token-based asset, embedded into the third party's website, loads.

Note:

A Web Access Token provides public and anonymous access to the actual asset and does not create or process end-user context in the flow. Therefore, each new Web Access Token-based request is considered as a brand new session, and reflected in the statistics results. For example, if the token user opens the Web Access Token-based link in several tabs of the same browser, or refreshes the tab, each of these actions will be a brand new request reflected in the statistics.

To review a token’s usage based on the specific token's configuration:

  1. From the Admin page, select Web Access Tokens.
  2. Click the icon for the token configuration you wish to review, and select View Usage Statistics, as shown below.
    Admin_WAT_ViewUsageStats.png

The Usage Statistics window opens showing the current relevant usage statistics, as shown below.
UsageStats.png

The following Usage statistics are displayed:

  • Last Used: The last time any of the tokens generated with the chosen token configuration
  • Total Usage Today: The total amount of sessions since the beginning of the current day
  • Total Usage: The total amount of sessions based on this token configuration
Note:

Usage statistics are nil if any of the tokens based on this token configuration has not been used.

Usage Statistics data is displayed depending on your specific time zone. All the data is stored in Coordinated Universal Time (UTC), irrespective of your current location. Sisense receives the data stored in UTC time zone, and the data transforms to your specific user time zone, following which you are able to view it.

Using WAT with RESTful API

In addition to Sisense's UI capabilities to work with Web Access Token configurations, RESTful API commands can be used to achieve the same results. See REST API 1.0 /web-access-tokens.

Limitations

  • Any feature or capability not described in this document cannot be considered as fully-supported. For additional information contact Support.

Was this article helpful?