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

You can use an OAuth2/OpenID Connect identity provider (IdP) as the authentication method in Information Services data sources. Depending on your use case, you can set up data sources with a traditional login flow where each user logs in, or your can set up data sources with automatic authentication using a service account.

Traditional login flow (Authorization Code Grant & Refresh Token Grant)

For a traditional login flow, where each user logs in to the data source with their own credentials in the identity provider, configure a data source template with the custom credentials provider TokenCredentialsProvider. In OAuth2 this flow is called Authorization Code Grant. Also, the Refresh Token Grant is supported.

Overview

When you use the TokenCredentialsProvider class to log in with an identity provider in 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, go to the Manage logins tab.

Configuration

In your IdP, register your Spotfire Server as a confidential client. Add the following redirect URI:
```
http[s]://<spotfire server>[:<port>]/spotfire/auth/oauth2/return
```
Add your IdP details 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 database. In the template, use the TokenCredentialsProvider class. See Adding a data source template.
Note: Remember to add any required connection properties, for example for setting the authentication method, in the data source template.

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

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 takes the access token retrieved on login to the Spotfire Server and passes it on to the JDBC driver.

To use the TokenCredentialsProvider class in a data source template, set the credentials-provider-class to com.spotfire.ws.im.ds.sql.TokenCredentialsProvider.

The initialization parameters store information about what IdP to use, which scopes to request, and how to pass an access token to the JDBC driver.

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>

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

Initialization 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_when_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.

Service account login (Client Credentials Grant)

To use the OAuth2 Client Credentials Grant flow, suitable for service accounts and automated workflows, you can configure a data source template with the custom credentials provider ClientCredentialsCredentialsProvider.

Data sources with the ClientCredentialsCredentialsProvider class use the client ID and client secret for authentication with the identity provider. You specify the client ID and secret with the username and password fields in the data source.

Note: Some JDBC drivers might implement the Client Credentials Grant flow in the driver itself, handling the client ID and client secret in the driver. For such cases, you might be able to use the CustomPropertiesCredentialsProvider class in your data source template instead, specifying which connection properties to pass the client ID and client secret from the username and password fields to.

See Passing username and password to custom properties.

Configuration

In your IdP, register your Spotfire Server as a confidential client. Note down the client ID and secret.
Create and add a data source template for the database. In the template, use the ClientCredentialsCredentialsProvider class.
Create a data source based on the template, and use the client ID and secret as username and password.

ClientCredentialsCredentialsProvider reference

To use the ClientCredentialsCredentialsProvider class in a data source template, set credentials-provider-class to com.spotfire.ws.im.ds.sql.ClientCredentialsCredentialsProvider.

The class initialization parameters take information about the URI of the authorization server, the OAuth2 scopes to request, and the name of the property the JDBC driver uses to handle the access token from the identity provider.

Example

<credentials-provider-class>com.spotfire.ws.im.ds.sql.ClientCredentialsCredentialsProvider</credentials-provider-class>
<credentials-provider-init-params>
 <parameter>
    <key>metadata_uri</key>
    <value>https://login.example.com/.well-known/oauth-authorization-server</value>
 </parameter>
 <parameter>
     <key>scope</key>
     <value>session:role:analyst</value>
 </parameter>
 <parameter>
     <key>access_token_property_name</key>
     <value>token</value>
 </parameter>   
</credentials-provider-init-params>

Table 1. Initialization parametersThe table lists all initialization parameters (`credentials-provider-init-params`).
Setting	Description	Default value
`access_token_property_name`	String. The name of the connection property that the driver uses to provide the access token. Required.
`metadata_uri`	String. The metadata URI of the authorization server. Typically ends with either of the following: `/.well-known/openid-configuration` `/.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 list.