Authentication & Security

There are some authentication and security concerns you need to address in order to start using Compose SDK in an application.

Authentication

To retrieve data using Compose SDK you need to authenticate your application against a Sisense instance.

There are several ways you can authenticate your application:

• Single Sign On (SSO)
• Web Access Token (WAT)
• API Token

Single Sign On

Single Sign On (SSO) allows the users of your application to authenticate with Sisense using an external identity provider.

Set up SSO

Set up your Sisense instance to authenticate users with SSO using one of the following:

• JSON Web Token (JWT) (opens new window)
• Security Assertion Markup Language 2.0 (SAML) (opens new window)
• OpenID Connect (opens new window)

Note

If you're experiencing difficulties or unexpected behavior when using SSO, the cause may be a hidden feature configuration. To resolve the issue, you can:

• Contact support (opens new window) to validate you Fusion configuration settings
• See this community post (opens new window) to try to resolve the issue yourself

Authenticate with SSO

Once you’ve set up SSO access, you can use it to authenticate within your application:

• For React apps use the ssoEnabled property of the <SisenseContextProvider /> component:

<SisenseContextProvider
  url="https://sisense-instance-url"
  ssoEnabled=true
>

• For Angular apps use the ssoEnabled property of the SisenseContextConfig object:

export const SISENSE_CONTEXT_CONFIG: SisenseContextConfig = {
  url="https://sisense-instance-url"
  ssoEnabled=true
};

• For Vue apps use the ssoEnabled property of the <SisenseContextProvider /> component:

<SisenseContextProvider
  :url="https://sisense-instance-url"
  :ssoEnabled="true"
>

Web Access Token

Sisense Web Access Tokens (WATs) impersonate specific Sisense users. Typically, in a production environment you create a Sisense user specifically for using Compose SDK. You grant that user the permissions you want to expose in your application and use a WAT that impersonates that user.

Note

When using a Structured Token (By Value) you can enforce row level security using an acl claim. All other claims are not supported.

Create a WAT

Before creating a WAT, you need to create a token configuration (opens new window) to generate a token secret and key ID.

Once you have a token secret and key ID, you can generate a WAT to use in your application in one of the following ways:

• Go to Web Access Tokens in the Sisense UI (opens new window)
• Send a request to the wat/generate (opens new window) endpoint of the Sisense REST API
• Use self-hosted token generation (opens new window)

Authenticate with a WAT

Once you’ve created a WAT, you can use it to authenticate within your application:

• For React apps use the wat property of the <SisenseContextProvider /> component:

<SisenseContextProvider
  url="http://sisense-instance-url"
  wat="eykZjkFhMGYzYmJl…"
>

• For Angular apps use the wat property of the SisenseContextConfig object:

export const SISENSE_CONTEXT_CONFIG: SisenseContextConfig = {
  url="http://sisense-instance-url"
  wat="eykZjkFhMGYzYmJl…"
};

• For Vue apps use the wat property of the <SisenseContextProvider /> component:

<SisenseContextProvider
  :url="http://sisense-instance-url"
  :wat="eykZjkFhMGYzYmJl…"
>

API Token

Sisense API Tokens are issued per user. Typically, you create a Sisense user specifically for using Compose SDK. You grant that user the permissions you want to expose in your application and use that user's API Token.

WARNING

Be sure to use API tokens in a secure manner. Typically, API tokens are not a good choice for production environments.

Create an API Token

You can get an API Token to use in your application in one of the following ways:

• Go to a user profile in the Sisense UI (opens new window)
• Send a request to the authentication/login (opens new window) endpoint of the Sisense REST API
• Run the following command using the Compose SDK CLI tool:

npx @sisense/sdk-cli@latest get-api-token --url <your_instance_url> --username <username>

Notes:

• Be sure to replace <your_instance_url> with the URL to your Sisense instance and <username> with the username of the user you want to create the API token for.
• For Windows, use double quotes around the URL and username arguments. For Mac/Linux, only use double quotes for arguments that contain white space.

Authenticate with an API token

Once you’ve obtained an API token, you can use it to authenticate within your application:

• For React apps use the token property of the <SisenseContextProvider /> component:

<SisenseContextProvider
  url="http://sisense-instance-url"
  token="eRykZjVxkFdhMaGYzYmqJl..."
>

• For Angular apps use the token property of the SisenseContextConfig object:

export const SISENSE_CONTEXT_CONFIG: SisenseContextConfig = {
  url="http://sisense-instance-url"
  token="eRykZjVxkFdhMaGYzYmqJl..."
};

• For Vue apps use the token property of the <SisenseContextProvider /> component:

<SisenseContextProvider
  :url="http://sisense-instance-url"
  :token="eRykZjVxkFdhMaGYzYmqJl..."
>

Cross-Origin Resource Sharing (CORS)

By default, browser same-origin policy prevents client-side web applications located in one domain from obtaining data from a different domain. That means an application you build with Compose SDK can't get data from your Sisense instance without some initial setup.

To get around this problem, you enable CORS (opens new window) for specific origins for which you want to allow resource sharing. Doing so instructs the Sisense server to respond to requests from your application with a header that tells the browser your application can use the data returned from Sisense even though it comes from a different domain.

Set up CORS

Set up CORS on your Sisense instance using one of the following:

• Add your application's domain to the CORS Allowed Origins in the Sisense UI (opens new window)
• Send a request to the settings/system (opens new window) endpoint of the Sisense REST API and include your application's domain in the allowedOrigins array:

"cors": {
  "enabled": true,
  "allowedOrigins": [
    "https://your-application-url"
  ]
}

Notes

• Do not include the trailing slash (/) when adding a domain to the CORS Allowed Origins
• Save your settings changes after adding your domain.

Third-Party Cookies

Most modern browsers block third-party cookies. This affects cookie-based authentications such as SSO.

Therefore, the best practice is either to:

• Use the same domain for the different apps and put it behind a specific path. This prevents Sisense cookies from being third-party cookies. For example: companyA.com/analytics.
• Leverage the Web Access Tokens (WAT) feature for authentication. Note that WAT requires special licensing.
• Allow third-party cookies via your browser settings. See this doc (opens new window) for detailed instructions.

WARNING

The Cookies Having Independent Partitioned State (CHIPS (opens new window)) solution is not compatible with Compose SDK.