Authentication with an identity provider (OAuth2) to access external systems

Spotfire supports using your own identity provider, such as Okta, Keycloak, or Google, for authentication when accessing certain external systems, such as data with connectors or a WMS server in the map chart.

Once you have configured your Spotfire environment, you can use the same identity providers for authentication towards several different external systems. If you use the same identity provider for authentication in your Spotfire environment, you can even enable a full single sign-on experience.

Follow the steps below to configure your Spotfire environment so that users can log in with an identity provider when they access external systems.

Note: The functionality described here is only applicable to on-premises Spotfire environments.

Before you begin

The following are prerequisites and other important information to be aware of before you start.

Prerequisites

Your identity provider uses one of the following protocols:
- OAuth2
- OpenID Connect
You have configured the external system that you want to access data from to use your identity provider for authentication.
You have registered client applications for Spotfire with your identity provider, one confidential and one public. The public client application is required for the Spotfire installed client, and the confidential client is required for Spotfire Server and Spotfire web clients.

Note: With Automation Services and Scheduled Updates, you cannot use any part of an analysis that uses an identity provider for authentication.

Is my identity provider supported?

Spotfire's support for authentication with an identity provider is built to be generic, and it is not tailored to any specific identity provider solution. An important prerequisite is that the identity provider is supported by the external data source.

The following are details about the Spotfire implementation, to help you understand the requirements and limitations on your identity provider:

The identity provider must expose an OAuth2 or OpenID Connect authorization server, and Spotfire uses the Authorization Code Grant Flow to get an access token from the authorization server.
Spotfire does not support adding custom headers in the authorization request
Spotfire does not support adding custom query parameters in the authorization request

Configuring Spotfire to use an identity provider to access external systems

To be able to use an identity provider to log in to an external system from Spotfire, you must add the details about your identity provider.

There are two places in the Spotfire configuration where you must add your identity provider information; in the OpenID Connect settings on the Spotfire Server, where you use your confidential client application details, and in the preference OAuth2IdentityProviders in the Administration Manager, where you use your public client application details. It is important that you configure both, so that you can log in and access your data both in the Spotfire web client and in the Spotfire installed client.

In broad strokes, you must perform the following steps to complete the configuration:

Collect information about your identity provider, and your client applications for Spotfire.
Add your identity provider on your Spotfire Server, with your confidential client application details.
Add your identity provider to the OAuth2IdentityProviders preference, with the public client application details.
Use your identity provider for authentication towards external systems.

Tip: On the My account page in the Spotfire web administration pages, you can view and manage the active access and refresh tokens.

In a web browser, go to your Spotfire Server, and log in.
Go to the library. In the navigation panel to the left, click your username.
On the My account page, go to the Manage logins tab.

When you revoke access by clicking Log out here, you must also log out from the web client for the changes to take effect because tokens are cached in the web client session.

1. Collecting information about your identity provider

Before you start, collect the following information about your identity provider:

What protocol does it use; OpenID Connect or OAuth2?
The issuer identifier URL.
Details about the client applications you have registered for Spotfire with your identity provider; client ID and client secret (if applicable).
The scopes for the permissions required for accessing data in the external system.

Depending on your identity provider, additional details might be required. For information about all the available settings, see the reference documentation about the OAuth2IdentityProviders preference in the Table 12.

2. Adding your identity provider on your Spotfire Server

To be able to use single sign-on, and also to be able to use your data connections in Spotfire web clients, you must add your identity provider and the confidential client application information to the Spotfire Server. Depending on your use case, you have two options:

To use the identity provider for authentication on the Spotfire Server and for accessing external systems, add the identity provider to the OpenID Connect settings on the Spotfire Server. See Configuring OpenID Connect.
To use the identity provider for authentication only for accessing external systems, add the identity provider on the Spotfire Server with the config-oauth-client command.

3. Adding your identity provider to the OAuth2IdentityProviders preference

Start the installed Spotfire client, and log in as a user with administrator privileges.
On the menu bar, select Tools > Administration manager
In the Administration Manager dialog, on the Preferences tab, click to select the user group you want to edit preferences for.
On the Preferences tab, click Edit.
In the Edit Preferences dialog, navigate to the preference Application > OAuth2Preferences > OAuth2IdentityProviders.
To edit the OAuth2IdentityProviders preference, select the preference and click the edit button [...].
In the String Collection Editor dialog, add your identity provider and the public client details as a JSON object.
Important: Only use the public client application from your identity provider here, and not the confidential client application. You can add your details to the sample below, which contains commonly used settings:
```
[
 {
    type: "<OAuth2 or OpenId>",
    displayName: "<My Identity Provider>",
    issuer: "<https:\\issuer1.example.com>",
    publicClient: {
       id: "<Client name or ID>",
      redirectUrl: "<redirect-url>",
      redirectPorts: "<port-number>"
       },
    defaultScope: "<myScope>"
 }
]
```
To save your changes, click OK.

Note: For more information about all the possible settings, see the reference documentation about the OAuth2IdentityProviders preference in the Table 12.

4. Using your identity provider for authentication towards external systems

Creating a data connection with your identity provider for authentication

To use your identity provider for authentication in a data connection, create a new data connection or connection data source and select the authentication method Identity provider (OAuth2). You can select your identity provider (listed with its display name from the OAuth2IdentityProviders preference) in the Identity providers drop-down menu.

Using your identity provider for authentication with an external library

Some connectors support both authentication with an identity provider and configuring an external library. In such cases, you can use identity providers that you have added to Spotfire for logging in to the external library.

When you set up an external library in the External library configurations, add the following settings:

authenticationMethod = "OAuth2"
issuer = "[Issuer URL of your Identity Provider]"

For more information, see Configuring an external library for TIBCO Data Virtualization.

Adding a WMS layer to a map chart using your identity provider for authentication

When adding a WMS layer to a map chart, you can select an identity provider (OAuth2) for authentication towards the WMS server. See Adding a WMS layer for more detailed instructions.