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
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.
- 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>
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
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
|
access_token_property_name
|
String. The name of the connection property that the driver uses to provide the access token. Required if
|
|
driver_supports_refresh_tokens
|
Boolean. If
|
False
|
refresh_token_property_name
|
String. The name of the connection property that the driver uses to provide the refresh token. Required if
|
|
client_id_property_name
|
String. The name of the connection property that the driver uses to provide the client secret. Required if
|
|
client_secret_property_name
|
String. The name of the connection property that the driver uses to provide the client secret. Required if
|
|
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.
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.
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>
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:
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. |