Identity provider (OAuth2/OpenID Connect) authentication for Information Services

Overview

When you use an IdP as the authentication method to access data from an Information Services data source, the process can be summarized in the following steps:

Spotfire sends a request to the identity provider, asking for permissions to access data in the external system. To make the request, Spotfire uses the TokenCredentialsProvider class settings in the data source template to determine the IdP to use and the scopes to request, and the information about the IdP in the Spotfire Server configuration.
In your web browser, you get a prompt to log in to your identity provider, and to confirm that you allow Spotfire to access the external system on your behalf.
Spotfire receives an access token from the identity provider that verifies that Spotfire is authorized to access resources in the external system.
Spotfire passes on the access token to the JDBC driver, with the use of the information in the TokenCredentialsProvider class settings in the data source template.

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, scroll down to Manage logins.

Configuration

To be able to create and use Information Services data sources with an IdP as the authentication method, the following is required:

In your IdP, register your Spotfire Server as a confidential client. For use with Information Services, you must add the following redirect URI:
```
http[s]://<spotfire server>[:<port>]/spotfire/auth/oauth2/return
```
Add your IdP to the Spotfire Server configuration, either with config-oauth-client (for data access only), or with config-oidc (for web authentication in Spotfire and data access).
Create and add a data source template for the data source. In the template, use the TokenCredentialsProvider class, where you can provide information about the IdP, which scopes to request, and how to pass on an access token to the JDBC driver. See Adding a data source template for identity provider authentication below.

Adding a data source template for identity provider authentication

You must create and add a data source template with the TokenCredentialsProvider class. To learn how to add a data source template to the Spotfire Server configuration, see Adding a data source template.

TokenCredentialsProvider

The TokenCredentialsProvider class settings store information about what IdP to use, which scopes to request, and how to pass an access token to the JDBC driver. In your data source template, set the credentials-provider-class to com.spotfire.ws.im.ds.sql.TokenCredentialsProvider.

Example

<credentials-provider-class>com.spotfire.ws.im.ds.sql.TokenCredentialsProvider</credentials-provider-class>
<credentials-provider-init-params>
  <parameter>
      <key>issuer</key>
      <value>https://login.example.com</value>
  </parameter>
  <parameter>
      <key>scope</key>
      <value>scopes</value>
  </parameter>
  <parameter>
      <key>access_token_property_name</key>
      <value>token</value>
  </parameter>    
</credentials-provider-init-params>

Connection properties

Many JDBC drivers have connection properties that determine the authentication method. Add and set any required connection properties in the data source template.

Example

<connection-properties>
  <connection-property>
    <key>Connection property name</key>
    <value>Property value</value>
  </connection-property>
</connection-properties>

Note: A selection of sample data source templates, some of which use identity provider authentication, are available on the Community.

com.spotfire.ws.im.ds.sql.TokenCredentialsProvider

The credentials provider com.spotfire.ws.im.ds.sql.TokenCredentialsProvider is an implementation of the SPI com.spotfire.informationservices.spi.ds.CustomCredentialsProvider, and is included in the Spotfire installation. It picks up the access token retrieved on login to the Spotfire Server and passes it on to the JDBC data source driver.

The credentials-provider-init-params provide information so that Spotfire can correctly pass on the access token.

Parameters

The table lists all initialization parameters for credentials-provider-init-params.


Setting	Description	Default value
`issuer`	String. The issuer claim of the identity provider. Enter the URI up to but not including `/.well-known/openid-configuration` or `/.well-known/oauth-authorization-server`. Required.
`scope`	String. A list of OAuth2 scopes to request for accessing data from the data source. Provide the scopes as a space-separated lists.
`include_access_token`	Boolean. If `True` then an access token will be passed to the driver.	`True`
`access_token_property_name`	String. The name of the connection property that the driver uses to provide the access token. Required if `include_access_token` is `True`.
`driver_supports_refresh_tokens`	Boolean. If `True` a refresh token is passed to the driver.	`False`
`refresh_token_property_name`	String. The name of the connection property that the driver uses to provide the refresh token. Required if `driver_supports_refresh_tokens` is `True`.
`client_id_property_name`	String. The name of the connection property that the driver uses to provide the client secret. Required if `driver_supports_refresh_tokens` is `True`.
`client_secret_property_name`	String. The name of the connection property that the driver uses to provide the client secret. Required if `driver_supports_refresh_tokens` is `True`.
`token_refresh_validity_below_minutes`	Integer. If Spotfire has a refresh token from the IdP, access tokens that have less than this time left of their validity time are automatically refreshed.	`30`
`metadata_url_property_name`	String. The name of a connection property in the JDBC driver, with which Spotfire should provide the URL to the OpenID Connect Discovery Document or the OAuth2 Authorization Server Metadata.
`token_endpoint_url_property_name`	String. The name of a connection property in the JDBC driver, with which Spotfire should provide the token endpoint URL.