Authentication

Any access to the application, both in the user interface and via programming interfaces (metadata REST/API, metadata upload/download), must be authenticated to verify the identity of the user.

💡 Tooltip
Each user can be defined in one or in multiple tenants (with different access levels), i.e. the login ID exists in several tenants and the user can log in with one of these tenants or select a specific tenant in the user interface.

For each user, it can be optionally specified that the user is logged into a certain tenant by default, if the login ID exists in multiple tenants.

Essentially, authentication involves the following steps:

The credentials (e.g. login ID and password) are determined according to the authentication method and, if necessary, verified.
If an access key is specified, the user is identified directly using the access key.
Otherwise, the user is assigned using the credentials.

🛈 Note
In the following examples, the database test and the server https://www.myserver.com are used for illustration purposes (e.g. in the path https://www.myserver.com/api/test). This database or server must be replaced accordingly in all actual requests. Depending on the configuration, the URL may also have to be extended by the context path (e.g. https://www.myserver.com/dataspot/api/test).

What's new?

The following changes to the configuration should be noted:

Release	Description
2026.1	In the authentication with login ID and password (basic authentication), new passwords are hashed using a unique, random salt and an optional, secret pepper. The optional server parameter `DATASPOT_PEPPER_STORE` contains the list of pepper values used for password hashing.
2026.1	In the authentication methods single sign-on (pre-authentication) and OpenID Connect (bearer authentication), the optional server parameter `DATASPOT_OIDC_JWT_TENANT_ID` defines the name of the claim in the JSON Web Token (JWT) containing the tenant ID of the user supplied by the identity provider (used when evaluating the access rules).
2026.1	In the authentication method single sign-on (pre-authentication), the optional server parameter `DATASPOT_REMOTE_USER_TENANT_ID` defines the name of the HTTP header attribute containing the tenant ID of the user supplied by the identity provider (used when evaluating the access rules).
2026.1	In the authentication method same sign-in (directory service/LDAP), the optional server parameter `DATASPOT_JNDI_TENANT_ID` defines the name of the JNDI attribute containing the tenant ID of the user supplied by the identity provider (used when evaluating the access rules).
2025.1	When calling an interface, an access key can be used to identify the user or service user.
4.6	In the authentication methods single sign-on (pre-authentication) and OpenID Connect (bearer authentication), the optional server parameters `DATASPOT_OIDC_JWT_FAMILY_NAME` and `DATASPOT_OIDC_JWT_GIVEN_NAME` define the names of the claims in the JSON Web Token (JWT) containing the family name and given name of the user (used when evaluating the access rules).
4.6	Access rules allow logging in as a guest (read-only) without a user or even to automatically create persons and users with specific access levels. The evaluation of the access rules is enabled with the server parameter `DATASPOT_ACCESS_RULES` (formerly `DATASPOT_GUEST_USERS`).
4.6	In the authentication method single sign-on (pre-authentication), the optional server parameter `DATASPOT_REMOTE_USER_GROUP_ID` defines the name of the HTTP header attribute containing the group IDs of the user supplied by the identity provider (used when evaluating the access rules). In the authentication method same sign-in (directory service/LDAP), the optional server parameter `DATASPOT_JNDI_GROUP_ID` defines the name of the JNDI attribute containing the group IDs of the user supplied by the identity provider (used when evaluating the access rules).
4.5	In the authentication methods single sign-on (pre-authentication) and OpenID Connect (bearer authentication), the optional server parameter `DATASPOT_OIDC_JWT_GROUP_ID` defines the name of the claim in the JSON Web Token (JWT) containing the group IDs of the user supplied by the identity provider (used when evaluating the access rules).
4.4	In the authentication methods single sign-on (pre-authentication) and OpenID Connect (bearer authentication), the optional server parameter `DATASPOT_OIDC_JWT_SUB_ID` defines the name of the claim in the JSON Web Token (JWT) containing the Subject Identifier of the user.

Authentication methods

The following authentication methods to determine the credentials are supported:

Login ID and password (basic authentication)
Single sign-on (pre-authentication)
Same sign-in (directory service/LDAP)
OpenID Connect (bearer authentication)

The credentials are provided using basic authentication in the HTTP header attribute Authorization.

This authentication method displays a login dialog (with login ID and password) in the user interface. The login ID and password are separated by :, encoded in Base64, and are sent to the server in the HTTP header attribute Authorization.

💡 Tooltip
When an external system calls a programming interface (metadata REST/API, metadata upload/download), the external system must provide the credentials in the HTTP header attribute Authorization.

On the server, the login ID and password are extracted from the HTTP header attribute Authorization. The password of the assigned user is used to verify the provided password from the credentials. With this authentication method, the passwords are managed in the application.

⚠️ Attention
Logging in as a guest (read-only) without a user is not supported with this authentication method, regardless of whether access rules are enabled or not. If the login ID cannot be assigned to a user in the login tenant, access is denied.

Configuration

The configuration is specified using the following server parameters:

Parameter	Description
`DATASPOT_PEPPER_STORE`	List of pepper values used for password hashing. The values are specified in the format `<pid>=<value>;<pid>=<value>;...`. - example: `pid2=mRHQiprk0S3JySeF;pid1=LnVT6FEkhuVQTU3J`
`DATASPOT_ACCESS_RULES` `DATASPOT_GUEST_USERS`(deprecated)	Enables/Disables access rules [`true`,`false`] - default: `true`

⚠️ Attention
The pepper store DATASPOT_PEPPER_STORE contains the currently active pepper value, used for hashing new passwords, as its first entry. The remaining entries are all previously active pepper values, necessary to verify the passwords hashed with them. Each pepper value is identified by a unique pepper ID.

To change the active pepper value, a new value is added as <pid>=<value> at the beginning of the list, without removing or changing the previous pepper values in order to remain compatible with existing passwords. If a pepper value is changed or removed from the pepper store, passwords that were hashed with this pepper value can no longer be verified.

🛈 Note
With the open source tool OpenSSL, secure pepper values (e.g. 24 bytes) can be generated as follows:

openssl rand -base64 24

In Java, secure pepper values (e.g. 24 bytes) can be generated as follows:

var bytes = new byte[24];
new java.security.SecureRandom().nextBytes(bytes);
System.out.println(java.util.Base64.getEncoder().encodeToString(bytes));

🛈 Note
Authentication with login ID and password (basic authentication) is automatically selected by default, if no other authentication method is enabled.

The login ID myuser and password s3cr3t are concatenated to myuser:s3cr3t, encoded in Base64 as bXl1c2VyOnMzY3IzdA==, and are sent to the server in the HTTP header attribute Authorization:

Authorization: Basic bXl1c2VyOnMzY3IzdA==

💡 Tooltip
For requests using the open source tool curl, the credentials can be provided as follows:

curl -u "myuser:s3cr3t" https://www.myserver.com/dataspot/rest/test/schemes
curl -H "Authorization: Basic bXl1c2VyOnMzY3IzdA==" https://www.myserver.com/dataspot/rest/test/schemes

On the server, the login ID myuser and password s3cr3t are extracted from the HTTP header attribute Authorization.

The password s3cr3t is compared with the password of the assigned user.

🛈 Note
In the application, passwords are not stored as plain text but are encrypted.

Single sign-on (pre-authentication)

The credentials are provided using customer-specific HTTP header attributes. Pre-authentication verifies the user's identity completely outside the application.

🛈 Note
Typically, pre-authentication is implemented on a reverse proxy, which, in addition to establishing the connection over https, also performs authentication and sets the configured HTTP header attributes.

This authentication method does not display a login dialog in the user interface. No credentials are sent from the browser to the server. The authentication is implemented on an external system between browser and server (e.g. on a reverse proxy), where the configured HTTP header attributes are set.

💡 Tooltip
When an external system calls a programming interface (metadata REST/API, metadata upload/download), the external system must provide the credentials in the customer-specific HTTP header attributes.

On the server, the login ID is extracted from the configured HTTP header attribute. There is no further verification of the credentials (e.g. password). With this authentication method, the passwords are not managed in the application.

⚠️ Attention
Enabling pre-authentication and setting the corresponding HTTP header attributes bypasses regular authentication. Therefore, when configuring pre-authentication, the network setup must ensure that no unauthorized systems are able to submit requests against the server with the respective HTTP header attributes set.

An additional level of security can be introduced with the configuration of an API-KEY token. If DATASPOT_API_KEY_TOKEN is defined, only requests containing the configured HTTP header attribute (see DATASPOT_API_KEY) with the API-KEY token (see DATASPOT_API_KEY_TOKEN) are authenticated.

⚠️ Attention
As of version 4.1, if pre-authentication is enabled, it is no longer possible to call programming interfaces with login ID and password (basic authentication).

Configuration

The configuration is specified using the following server parameters:

Parameter	Description
`DATASPOT_PRE_AUTHENTICATION`	Enables/Disables pre-authentication [`true`,`false`] - default: `false`
`DATASPOT_REMOTE_USER_ID` `DATASPOT_REMOTE_USER`(deprecated)	Name of the HTTP header attribute containing the login ID of the user
`DATASPOT_REMOTE_USER_GROUP_ID`	Name of the HTTP header attribute containing the (comma-separated) group IDs of the user supplied by the identity provider (used when evaluating the access rules) - optional
`DATASPOT_REMOTE_USER_TENANT_ID`	Name of the HTTP header attribute containing the tenant ID of the user supplied by the identity provider (used when evaluating the access rules) - optional
`DATASPOT_REMOTE_USER_FAMILY_NAME`	Name of the HTTP header attribute containing the family name of the user (used when evaluating the access rules) - optional
`DATASPOT_REMOTE_USER_GIVEN_NAME`	Name of the HTTP header attribute containing the given name of the user (used when evaluating the access rules) - optional
`DATASPOT_REMOTE_USER_TENANT_NAME`	Name of the HTTP header attribute that overrides the default tenant. - optional; default: The default tenant remains unchanged
`DATASPOT_REMOTE_USER_OIDC_JWT`	Name of the HTTP header attribute containing a JSON Web Token (JWT) - optional
`DATASPOT_OIDC_JWT_SUB_ID`	Name of the claim in the JSON Web Token (JWT) (see `DATASPOT_REMOTE_USER_OIDC_JWT`) containing the Subject Identifier of the user - optional
`DATASPOT_OIDC_JWT_GROUP_ID`	Name of the claim in the JSON Web Token (JWT) (see `DATASPOT_REMOTE_USER_OIDC_JWT`) containing the group IDs of the user supplied by the identity provider (used when evaluating the access rules). Evaluated only if the HTTP header attribute `DATASPOT_REMOTE_USER_GROUP_ID` is empty. - optional
`DATASPOT_OIDC_JWT_TENANT_ID`	Name of the claim in the JSON Web Token (JWT) (see `DATASPOT_REMOTE_USER_OIDC_JWT`) containing the tenant ID of the user supplied by the identity provider (used when evaluating the access rules). Evaluated only if the HTTP header attribute `DATASPOT_REMOTE_USER_TENANT_ID` is empty. - optional
`DATASPOT_OIDC_JWT_CLIENT_ID`	Name of the claim in the JSON Web Token (JWT) (see `DATASPOT_REMOTE_USER_OIDC_JWT`) containing the OpenID Connect Client ID - default: `aud`
`DATASPOT_OIDC_JWT_USER_NAME`	Name of the claim in the JSON Web Token (JWT) (see `DATASPOT_REMOTE_USER_OIDC_JWT`) containing the name of the user (used when evaluating the access rules). Evaluated only if the HTTP header attributes `DATASPOT_REMOTE_USER_FAMILY_NAME` and `DATASPOT_REMOTE_USER_GIVEN_NAME` are empty. - optional
`DATASPOT_OIDC_JWT_FAMILY_NAME`	Name of the claim in the JSON Web Token (JWT) (see `DATASPOT_REMOTE_USER_OIDC_JWT`) containing the family name of the user (used when evaluating the access rules). Evaluated only if the HTTP header attribute `DATASPOT_REMOTE_USER_FAMILY_NAME` is empty. - optional
`DATASPOT_OIDC_JWT_GIVEN_NAME`	Name of the claim in the JSON Web Token (JWT) (see `DATASPOT_REMOTE_USER_OIDC_JWT`) containing the given name of the user (used when evaluating the access rules). Evaluated only if the HTTP header attribute `DATASPOT_REMOTE_USER_GIVEN_NAME` is empty. - optional
`DATASPOT_OIDC_JWT_TENANT_NAME`	Name of the claim in the JSON Web Token (JWT) (see `DATASPOT_REMOTE_USER_OIDC_JWT`) that overrides the default tenant. Evaluated only if the HTTP header attribute `DATASPOT_REMOTE_USER_TENANT_NAME` is empty. - optional
`DATASPOT_API_KEY`	Name of the HTTP header attribute containing the API-KEY token (see `DATASPOT_API_KEY_TOKEN`) - optional
`DATASPOT_API_KEY_TOKEN`	API-KEY token - optional
`DATASPOT_ACCESS_RULES` `DATASPOT_GUEST_USERS`(deprecated)	Enables/Disables access rules [`true`,`false`] - default: `true`
`DATASPOT_ADMIN_USER`	List of login IDs (separated by `;`) of users allowed to act as system administrators - optional
`DATASPOT_LOGOUT_URL`	URL that is opened by clicking `Logout` in the user menu. Before opening the URL, the optional placeholder `${POST_LOGOUT_REDIRECT_URL}` is replaced by the URL of the current database (e.g. `https://www.myserver.com/web/test`). - optional - example: `/.auth/logout?post_logout_redirect_uri=${POST_LOGOUT_REDIRECT_URL}` - example: `https://www.myserver.com/`

⚠️ Attention
The optional JSON Web Token (JWT) (see DATASPOT_REMOTE_USER_OIDC_JWT) can contain additional information about the user. Please note that, since authentication is not explicitly configured as OpenID Connect (bearer authentication), the signature of the JWT is not verified, as this would involve establishing connectivity to the issuer and obtaining the corresponding JSON Web Key (JWK) from the public JSON Web Key Set (JWKS). Rather, we assume the JWT has been correctly issued, signed and injected into the HTTP header by an authentication module (e.g. Azure Easy Auth).

💡 Tooltip
The group IDs of the user supplied by the identity provider (see DATASPOT_REMOTE_USER_GROUP_ID and DATASPOT_OIDC_JWT_GROUP_ID) can be used to define access rules (e.g. the user is automatically created with the access level Editor, if they are a member of a specific group).

💡 Tooltip
The tenant ID of the user supplied by the identity provider (see DATASPOT_REMOTE_USER_TENANT_ID and DATASPOT_OIDC_JWT_TENANT_ID) can be used to define access rules (e.g. all users with a specific tenant ID are automatically logged in as guests).

🛈 Note
When pre-authentication is enabled, the entry Logout is displayed in the user menu, only if the server parameter DATASPOT_LOGOUT_URL is defined.

Example: Single sign-on (pre-authentication)

DATASPOT_PRE_AUTHENTICATION=true
DATASPOT_REMOTE_USER_ID=dataspot-user-id
DATASPOT_REMOTE_USER_FAMILY_NAME=dataspot-user-family-name
DATASPOT_REMOTE_USER_GIVEN_NAME=dataspot-user-given-name
DATASPOT_REMOTE_USER_TENANT_NAME=dataspot-user-tenant-name
DATASPOT_REMOTE_USER_OIDC_JWT=X-MS-TOKEN-AAD-ID-TOKEN
DATASPOT_OIDC_JWT_USER_NAME=name
DATASPOT_OIDC_JWT_TENANT_NAME=tenant
DATASPOT_ADMIN_USER=mmustermann;jdoe

dataspot-user-id: myuser

💡 Tooltip
For requests using the open source tool curl, the credentials can be provided as follows:

curl -H "dataspot-user-id: myuser" https://www.myserver.com/dataspot/rest/test/schemes

On the server, the login ID myuser is extracted from the HTTP header attribute dataspot-user-id.

The default tenant can be overridden with the HTTP header attribute dataspot-user-tenant-name. Alternatively, the JSON Web Token (JWT) is extracted from the HTTP header attribute X-MS-TOKEN-AAD-ID-TOKEN and the default tenant is read from the claim tenant.
The name of the user can be provided in the HTTP header attributes dataspot-user-family-name and dataspot-user-given-name. Alternatively, the JSON Web Token (JWT) is extracted from the HTTP header attribute X-MS-TOKEN-AAD-ID-TOKEN and the name of the user is read from the claim name.

A user whose login ID appears in the list mmustermann;jdoe, is also granted access to all tenants with additional authorization as a system administrator.

Example: API-KEY token

DATASPOT_PRE_AUTHENTICATION=true
DATASPOT_REMOTE_USER_ID=dataspot-user-id
DATASPOT_API_KEY=dataspot-api-key
DATASPOT_API_KEY_TOKEN=s3cr3t

The authentication is implemented on an external system between browser and server (e.g. on a reverse proxy), where the login ID myuser is written into the HTTP header attribute dataspot-user-id and the API-KEY token s3cr3t is written into the HTTP header attribute dataspot-api-key:

dataspot-user-id: myuser
dataspot-api-key: s3cr3t

On the server, the login ID myuser is extracted from the HTTP header attribute dataspot-user-id.

The request is only authenticated, if the HTTP header attribute dataspot-api-key has the value s3cr3t.

Example: Apache HTTP server with LDAP module

The following example illustrates how a reverse proxy can be configured using an Apache HTTP server to support the following additional functionalities:

SSL connection (over https)
Single sign-on (the user must authenticate only once on the reverse proxy)

The example should only demonstrate the basic principle of authenticating over LDAP. Advanced configurations may be defined as described in the documentation of the respective Apache modules:

<VirtualHost *:443>
  ServerName dataspot.example.com
  SSLEngine on

  # Certificate configuration
  SSLCertificateKeyFile /etc/ssl.key/example.com.key
  SSLCertificateFile /etc/ssl.crt/example.com.crt

  # Enable rewrite engine
  RewriteEngine On

  <Location "/dataspot">
    ProxyPass http://localhost:8080
    ProxyPassReverse http://localhost:8080
    Require all granted

    AuthName "My Company"
    AuthBasicProvider ldap
    AuthType Basic

    AuthLDAPURL ldap://ldap.example.com/o=Example?uid

    Require valid-user
    Require ldap-group cn=Users, o=Example

    # Do not rewrite sub requests
    RewriteCond %{IS_SUBREQ} ^false$

    # store the value of the environment variable REMOTE_USER into the variable RU (look-ahead)
    RewriteCond %{LA-U:REMOTE_USER} (.+)
    RewriteRule .* - [E=RU:%1]

    # add the value of the variable RU to the request headers
    RequestHeader set X-AUTHENTICATED-USER %{RU}e

    # clear the Authorization header
    RequestHeader unset Authorization
  </Location>
</VirtualHost>

The credentials are provided using basic authentication in the HTTP header attribute Authorization and are authenticated in an external directory service.

💡 Tooltip
When an external system calls a programming interface (metadata REST/API, metadata upload/download), the external system must provide the credentials in the HTTP header attribute Authorization.

On the server, the login ID and password are extracted from the HTTP header attribute Authorization. The password is verified in an external directory service over JNDI (Java Naming and Directory Interface). With this authentication method, the passwords are not managed in the application.

🛈 Note
Even though LDAP (Lightweight Directory Access Protocol) is typically used for authentication, in principle any directory service that supports JNDI can be used for authentication.

The verification of the login ID and password from the credentials is implemented using JNDI (Java Naming and Directory Interface), as follows:

The directory service (see DATASPOT_JNDI_FACTORY and DATASPOT_JNDI_URL) is contacted with a user (see DATASPOT_JNDI_USER) and password (see DATASPOT_JNDI_PASSWORD). The user must be authorized to search for objects in the directory service.
In the context (see DATASPOT_JNDI_CONTEXT) and using the filter expression (see DATASPOT_JNDI_FILTER), the directory service is searched for an object (user) with the login ID specified in the credentials. The placeholder {0} in the filter expression is replaced by the login ID.
If an object with the login ID is found, the password is verified by contacting the directory service with the found object and the password specified in the credentials.

Configuration

The configuration is specified using the following server parameters:

Parameter	Description
`DATASPOT_JNDI_AUTHENTICATION`	Enables/Disables JNDI authentication [`true`,`false`] - default: `false`
`DATASPOT_JNDI_FACTORY`	Initial Context Factory - default: `com.sun.jndi.ldap.LdapCtxFactory` (LDAP)
`DATASPOT_JNDI_URL`	Directory service URL - example: `ldaps://ldap.example.com`
`DATASPOT_JNDI_USER`	User, with authorization to search for objects in the directory service - example: `uid=admin,ou=administrators,dc=example,dc=com`
`DATASPOT_JNDI_PASSWORD`	Password (see `DATASPOT_JNDI_USER`)
`DATASPOT_JNDI_CONTEXT`	Context in which objects are searched for - optional; example: `ou=users,dc=example,dc=com`
`DATASPOT_JNDI_FILTER`	Filter expression (the placeholder `{0}` is replaced by the login ID from the credentials) - default: `uid={0}` - example: `samaccountname={0}` (Active Directory)
`DATASPOT_JNDI_GROUP_ID`	Name of the JNDI attribute containing the group IDs of the user supplied by the identity provider (used when evaluating the access rules) - optional; example: `groups`
`DATASPOT_JNDI_TENANT_ID`	Name of the JNDI attribute containing the tenant ID of the user supplied by the identity provider (used when evaluating the access rules) - optional; example: `tenant`
`DATASPOT_JNDI_COMMON_NAME`	Name of the JNDI attribute containing the common name of the user (used when evaluating the access rules) - optional; example: `cn`
`DATASPOT_JNDI_FAMILY_NAME`	Name of the JNDI attribute containing the family name of the user (used when evaluating the access rules) - optional; example: `sn`
`DATASPOT_JNDI_GIVEN_NAME`	Name of the JNDI attribute containing the given name of the user (used when evaluating the access rules) - optional; example: `givenName`
`DATASPOT_JNDI_TENANT_NAME`	Name of the JNDI attribute that overrides the default tenant. - optional; default: The default tenant remains unchanged
`DATASPOT_ACCESS_RULES` `DATASPOT_GUEST_USERS`(deprecated)	Enables/Disables access rules [`true`,`false`] - default: `true`

💡 Tooltip
For LDAP, the command-line tool ldapsearch can be used to determine and test the required filter expression.

💡 Tooltip
The group IDs of the user supplied by the identity provider (see DATASPOT_JNDI_GROUP_ID) can be used to define access rules (e.g. the user is automatically created with the access level Editor, if they are a member of a specific group).

💡 Tooltip
The tenant ID of the user supplied by the identity provider (see DATASPOT_JNDI_TENANT_ID) can be used to define access rules (e.g. all users with a specific tenant ID are automatically logged in as guests).

DATASPOT_JNDI_AUTHENTICATION=true
DATASPOT_JNDI_URL=ldap://ldap.example.com
DATASPOT_JNDI_USER=cn=admin,dc=example,dc=com
DATASPOT_JNDI_PASSWORD=pa$$word
DATASPOT_JNDI_CONTEXT=ou=users,dc=example,dc=com
DATASPOT_JNDI_FILTER=uid={0}
DATASPOT_JNDI_COMMON_NAME=cn
DATASPOT_JNDI_TENANT_NAME=group

The login ID myuser and password s3cr3t are concatenated to myuser:s3cr3t, encoded in Base64 as bXl1c2VyOnMzY3IzdA==, and are sent to the server in the HTTP header attribute Authorization:

Authorization: Basic bXl1c2VyOnMzY3IzdA==

💡 Tooltip
For requests using the open source tool curl, the credentials can be provided as follows:

curl -u "myuser:s3cr3t" https://www.myserver.com/dataspot/rest/test/schemes
curl -H "Authorization: Basic bXl1c2VyOnMzY3IzdA==" https://www.myserver.com/dataspot/rest/test/schemes

On the server, the login ID myuser and password s3cr3t are extracted from the HTTP header attribute Authorization and are authenticated in LDAP.

The directory service LDAP at the URL ldap://ldap.example.com is contacted with the user cn=admin,dc=example,dc=com and password pa$$word. In the context ou=users,dc=example,dc=com and using the filter expression uid={0}, the directory service is searched for an object with the login ID myuser.

The default tenant can be overridden with the LDAP attribute group of the found object.
The common name of the user can be provided in the LDAP attribute cn of the found object.
The password is verified by contacting the directory service with the found object and the password s3cr3t.

🛈 Note
LDAP Unauthenticated Authentication (with an empty password) is not supported.

OpenID Connect (bearer authentication)

The credentials are provided using bearer authentication in the HTTP header attribute Authorization.

This authentication method displays the login dialog of an external identity provider in the user interface, e.g. Microsoft Entra ID (formerly Microsoft Azure AD). The identity of the user is verified using OpenID Connect (OIDC). The credentials are represented as a signed JSON Web Token (JWT), encoded in Base64, and are sent to the server in the HTTP header attribute Authorization.

💡 Tooltip
When an external system calls a programming interface (metadata REST/API, metadata upload/download), the external system must provide the credentials as a signed JSON Web Token (JWT) in the HTTP header attribute Authorization.

On the server, the login ID is extracted from the configured claim in the signed JSON Web Token (JWT) from the HTTP header attribute Authorization. There is no further verification of the credentials (e.g. password). With this authentication method, the passwords are not managed in the application.

⚠️ Attention
For security reasons, the OpenID Connect Client ID (see DATASPOT_OIDC_CLIENT_ID) must be contained in the configured claim (see DATASPOT_OIDC_JWT_CLIENT_ID).

Configuration

The configuration is specified using the following server parameters:

Parameter	Description
`DATASPOT_OIDC_AUTHENTICATION`	Enables/Disables OIDC authentication [`true`,`false`] - default: `false`
`DATASPOT_OIDC_CLIENT_ID`	OpenID Connect Client ID
`DATASPOT_OIDC_PROVIDER_NAME`	Name of the identity provider, that supports OpenID Connect: `AzureAD` (Microsoft Entra ID, formerly Microsoft Azure AD)
`DATASPOT_OIDC_PROVIDER_URL`	URL of the identity provider, that supports OpenID Connect
`DATASPOT_OIDC_JWT_USER_ID`	Name of the claim in the JSON Web Token (JWT) containing the login ID of the user
`DATASPOT_OIDC_JWT_SUB_ID`	Name of the claim in the JSON Web Token (JWT) containing the Subject Identifier of the user - optional
`DATASPOT_OIDC_JWT_GROUP_ID`	Name of the claim in the JSON Web Token (JWT) containing the group IDs of the user supplied by the identity provider (used when evaluating the access rules) - optional
`DATASPOT_OIDC_JWT_TENANT_ID`	Name of the claim in the JSON Web Token (JWT) containing the tenant ID of the user supplied by the identity provider (used when evaluating the access rules) - optional
`DATASPOT_OIDC_JWT_CLIENT_ID`	Name of the claim in the JSON Web Token (JWT) containing the OpenID Connect Client ID (see `DATASPOT_OIDC_CLIENT_ID`) - default: `aud`
`DATASPOT_OIDC_JWT_USER_NAME`	Name of the claim in the JSON Web Token (JWT) containing the name of the user (used when evaluating the access rules) - optional
`DATASPOT_OIDC_JWT_FAMILY_NAME`	Name of the claim in the JSON Web Token (JWT) containing the family name of the user (used when evaluating the access rules) - optional
`DATASPOT_OIDC_JWT_GIVEN_NAME`	Name of the claim in the JSON Web Token (JWT) containing the given name of the user (used when evaluating the access rules) - optional
`DATASPOT_OIDC_JWT_TENANT_NAME`	Name of the claim in the JSON Web Token (JWT) that overrides the default tenant. - optional; default: The default tenant remains unchanged
`DATASPOT_ACCESS_RULES` `DATASPOT_GUEST_USERS`(deprecated)	Enables/Disables access rules [`true`,`false`] - default: `true`
`DATASPOT_ADMIN_USER`	List of login IDs (separated by `;`) of users allowed to act as system administrators - optional

💡 Tooltip
Using Microsoft Entra ID (formerly Microsoft Azure AD) requires that the application is registered in the Azure portal. The URI https://www.myserver.com/dataspot/web/auth must be added to the list of accepted redirect URIs.

⚠️ Attention
To verify the signature of the JSON Web Token (JWT) the corresponding JSON Web Key (JWK) must be obtained from a public JSON Web Key Set (JWKS). The URI of the public JSON Web Key Set (JWKS) is published in the OpenID Provider Configuration (see Claim iss). Therefore, the server must have access to both the OpenID Provider Configuration and the public JSON Web Key Set (JWKS).

💡 Tooltip
The group IDs of the user supplied by the identity provider (see DATASPOT_OIDC_JWT_GROUP_ID) can be used to define access rules (e.g. the user is automatically created with the access level Editor, if they are a member of a specific group).

💡 Tooltip
The tenant ID of the user supplied by the identity provider (see DATASPOT_OIDC_JWT_TENANT_ID) can be used to define access rules (e.g. all users with a specific tenant ID are automatically logged in as guests).

Subject Identifier

The Subject Identifier of a user is a unique and never reassigned identifier issued by the identity provider.

If the optional server parameter DATASPOT_OIDC_JWT_SUB_ID is specified, the corresponding claim in the JSON Web Token (JWT) must contain a Subject Identifier matching the internal Subject Identifier of the user. Otherwise, the authentication is rejected.

🛈 Note
If the user does not yet have an internal Subject Identifier, the Subject Identifier from the JSON Web Token (JWT) is assigned to the user (and verified in subsequent accesses). The internal Subject Identifier of the user cannot be changed thereafter.

Example: OpenID Connect (bearer authentication)

DATASPOT_OIDC_AUTHENTICATION=true
DATASPOT_OIDC_CLIENT_ID=6731de76-14a6-49ae-97bc-6eba6914391e
DATASPOT_OIDC_PROVIDER_NAME=AzureAD
DATASPOT_OIDC_PROVIDER_URL=https://login.microsoftonline.com/a1ebd953-fb5f-425e-99fc-ec46bf8ce3f0
DATASPOT_OIDC_JWT_CLIENT_ID=aud
DATASPOT_OIDC_JWT_USER_ID=email
DATASPOT_OIDC_JWT_SUB_ID=sub
DATASPOT_OIDC_JWT_USER_NAME=name
DATASPOT_OIDC_JWT_TENANT_NAME=group
DATASPOT_ADMIN_USER=john.smith@mydomain.com;joe.public@mydomain.com

The identity of a user in the user interface is verified using OpenID Connect (OIDC) with the external identity provider AzureAD at the URL https://login.microsoftonline.com/a1ebd953-fb5f-425e-99fc-ec46bf8ce3f0. The credentials are represented as a signed JSON Web Token (JWT) containing a header and a payload, for example:

{
  "alg": "HS256",
  "typ": "JWT"
}

{
  "iss": "https://sts.windows.net/a1ebd953-fb5f-425e-99fc-ec46bf8ce3f0/",
  "sub": "123456",
  "aud": "6731de76-14a6-49ae-97bc-6eba6914391e",
  "exp": 1311281970,
  "iat": 1311280970,
  "name": "Jane Doe",
  "email": "jane.doe@mydomain.com"
}

Header, payload and signature are encoded in Base64, separated by . and are sent to the server as a bearer token in the HTTP header attribute Authorization.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC82NzMxZGU3Ni0xNGE2LTQ5YWUtOTdiYy02ZWJhNjkxNDM5MWUvIiwic3ViIjoiMTIzNDU2IiwiYXVkIjoiNjczMWRlNzYtMTRhNi00OWFlLTk3YmMtNmViYTY5MTQzOTFlIiwiZXhwIjoxMzExMjgxOTcwLCJpYXQiOjEzMTEyODA5NzAsIm5hbWUiOiJKYW5lIERvZSIsImVtYWlsIjoiamFuZS5kb2VAbXlkb21haW4uY29tIn0.FPo7QaEAmb5jNuaShUtbdg2PXEVrTseIPjovN3s2Pz4

💡 Tooltip
For requests using the open source tool curl, the credentials can be provided as follows:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC82NzMxZGU3Ni0xNGE2LTQ5YWUtOTdiYy02ZWJhNjkxNDM5MWUvIiwic3ViIjoiMTIzNDU2IiwiYXVkIjoiNjczMWRlNzYtMTRhNi00OWFlLTk3YmMtNmViYTY5MTQzOTFlIiwiZXhwIjoxMzExMjgxOTcwLCJpYXQiOjEzMTEyODA5NzAsIm5hbWUiOiJKYW5lIERvZSIsImVtYWlsIjoiamFuZS5kb2VAbXlkb21haW4uY29tIn0.FPo7QaEAmb5jNuaShUtbdg2PXEVrTseIPjovN3s2Pz4" https://www.myserver.com/dataspot/rest/test/schemes

💡 Tooltip
JSON Web Tokens (JWTs) can be edited and verified conveniently using jwt.io.

On the server, the login ID jane.doe@mydomain.com is extracted from the claim email in the signed JSON Web Token (JWT) from the HTTP header attribute Authorization.

The default tenant can be overridden with the claim group.
The name of the user can be provided in the claim name.
The OpenID Connect Client ID 6731de76-14a6-49ae-97bc-6eba6914391e must be contained in the claim aud.
The Subject Identifier 123456 from the claim sub must match the internal Subject Identifier of the user.

A user whose login ID appears in the list john.smith@mydomain.com;joe.public@mydomain.com, is also granted access to all tenants with additional authorization as a system administrator.

Example: Resource Owner Password Credentials (ROPC)

When calling an interface, the bearer token can be obtained programmatically (without any user interaction) using Resource Owner Password Credentials (ROPC).

⚠️ Attention
If the identity provider requires multi-factor authentication (MFA) (and therefore user interaction), authentication with Resource Owner Password Credentials (ROPC) is not suitable for programmatically calling interfaces. Alternatively, a non-interactive authentication (e.g. OAuth 2.0 Client Credentials Grant) must be used.

On Windows, the open source tools curl and jq can be used in a PowerShell:

$USERNAME="jane.doe@mydomain.com"
$PASSWORD="s3cr3t"
$CLIENT_ID="6731de76-14a6-49ae-97bc-6eba6914391e"
$ID_TOKEN=$(curl.exe -X POST https://login.microsoftonline.com/organizations/oauth2/v2.0/token -d "username=$USERNAME&password=$PASSWORD&client_id=$CLIENT_ID&grant_type=password&scope=openid" | jq.exe -r ".id_token")
curl.exe -X GET -H "Authorization: Bearer $ID_TOKEN" https://www.myserver.com/dataspot/rest/test/schemes

On Linux, the open source tools curl and jq can be used in a Bash:

USERNAME="jane.doe@mydomain.com"
PASSWORD="s3cr3t"
CLIENT_ID="6731de76-14a6-49ae-97bc-6eba6914391e"
ID_TOKEN=$(curl -X POST https://login.microsoftonline.com/organizations/oauth2/v2.0/token -d "username=$USERNAME&password=$PASSWORD&client_id=$CLIENT_ID&grant_type=password&scope=openid" | jq -r ".id_token")
curl -X GET -H "Authorization: Bearer $ID_TOKEN" https://www.myserver.com/dataspot/rest/test/schemes

The identity provider that supports OpenID Connect (e.g. Microsoft Entra ID) is contacted at the endpoint /token with the login ID and password as well as the OpenID Connect Client ID. Using jq the JSON propery id_token is extracted from the response and stored in the environment variable ID_TOKEN. Finally, the interface /rest/test/schemes is called and the bearer token from the environment variable ID_TOKEN is passed in the HTTP header attribute Authorization.

Example: OAuth 2.0 Client Credentials Grant

If the application is hosted in the cloud (e.g. as Software-as-a-Service in Microsoft Azure), the server can be protected by an authentication module (e.g. Azure Easy Auth). When an interface is called, a valid and signed JSON Web Token (JWT) must be provided so that the request can pass the authentication module.

💡 Note
If the identity provider requires multi-factor authentication (MFA) (and therefore user interaction), authentication with login ID and password is not suitable for programmatically calling interfaces.

If an interface is called by an external program, the JSON Web Token (JWT) must therefore be obtained using a non-interactive method (e.g. with OAuth 2.0 Client Credentials Grant).

💡 Note
In OAuth 2.0 Client Credentials Grant, a client program is authenticated non-interactively (machine to machine) rather than a user. The calling client program is granted access to the application.

In this case, the JSON Web Token (JWT) is not an OpenID Connect ID Token that identifies a user, but an access token that authenticates the client program. The access token does not contain the required login ID that can be assigned to a user in the application.

In addition to the access token required to pass the authentication module, an access key must also be provided for each interface call in order to identify the user or service user in the application.

On Windows, the open source tools curl and jq can be used in a PowerShell:

$TENANT_ID="b0ebd953-fb5f-425e-98fc-ec46bf8ce2f1"
$CLIENT_ID="6731de76-14a6-49ae-97bc-6eba6914391e"
$CLIENT_SECRET="s3cr3t"
$SCOPE="api://$CLIENT_ID/.default"
$ACCESS_KEY="0W7aB0dMEmRoGOq3M85gBD5CxSnNQhCBvlZsBm5XABkyxzjlE1tm7EPDF3bvIlTd6Uyu3_lReBTuhiFKWXAimU"
$ACCESS_TOKEN=$(curl.exe -X POST https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token -d "client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&grant_type=client_credentials&scope=$SCOPE" | jq.exe -r ".access_token")
curl.exe -X GET -H "Authorization: Bearer $ACCESS_TOKEN" -H "dataspot-access-key: $ACCESS_KEY" https://www.myserver.com/dataspot/rest/test/schemes

On Linux, the open source tools curl and jq can be used in a Bash:

TENANT_ID="b0ebd953-fb5f-425e-98fc-ec46bf8ce2f1"
CLIENT_ID="6731de76-14a6-49ae-97bc-6eba6914391e"
CLIENT_SECRET="s3cr3t"
SCOPE="api://$CLIENT_ID/.default"
ACCESS_KEY="0W7aB0dMEmRoGOq3M85gBD5CxSnNQhCBvlZsBm5XABkyxzjlE1tm7EPDF3bvIlTd6Uyu3_lReBTuhiFKWXAimU"
ACCESS_TOKEN=$(curl -X POST https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token -d "client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&grant_type=client_credentials&scope=$SCOPE" | jq -r ".access_token")
curl -X GET -H "Authorization: Bearer $ACCESS_TOKEN" -H "dataspot-access-key: $ACCESS_KEY" https://www.myserver.com/dataspot/rest/test/schemes

The identity provider that supports OAuth 2.0 Client Credentials Grant (e.g. Microsoft Entra ID) is contacted at the endpoint /token with the client ID and client secret. Using jq the JSON propery access_token is extracted from the response and stored in the environment variable ACCESS_TOKEN. Finally, the interface /rest/test/schemes is called and the bearer token from the environment variable ACCESS_TOKEN is passed in the HTTP header attribute Authorization. The access key is provided in the HTTP header attribute dataspot-access-key.

Access key

An access key is a secret character sequence that is assigned to a user or service user. When calling an interface, the access key can be used to identify the user or service user.

⚠️ Attention
When authenticating with an access key, the user is not assigned based on the credentials, i.e. the access key replaces the login with credentials (e.g. login ID and password). The user or service user and the tenant are identified directly by the access key.

The access rules are not evaluated if an access key is used for authentication.

The access key is provided in the HTTP header attribute dataspot-access-key.

⚠️ Note
Access keys can only be used when calling interfaces. It is not possible to log in to the user interface with an access key.

On the server, the access key is extracted from the HTTP header attribute dataspot-access-key. The access key is verified and uniquely identifies a user or service user in the application. The access key is only valid in a single tenant, i.e. the tenant is also uniquely determined by the access key.

⚠️ Note
If a tenant is specified in the HTTP header attribute dataspot-tenant, the login in this tenant is enforced, regardless of the authentication method. If the tenant determined by the access key is different, the login is rejected.

Example: Access key

The access key is sent to the server in the HTTP header attribute dataspot-access-key:

dataspot-access-key: 0W7aB0dMEmRoGOq3M85gBD5CxSnNQhCBvlZsBm5XABkyxzjlE1tm7EPDF3bvIlTd6Uyu3_lReBTuhiFKWXAimU

💡 Tooltip
For requests using the open source tool curl, the access key can be provided as follows:

curl -H "dataspot-access-key: 0W7aB0dMEmRoGOq3M85gBD5CxSnNQhCBvlZsBm5XABkyxzjlE1tm7EPDF3bvIlTd6Uyu3_lReBTuhiFKWXAimU" https://www.myserver.com/dataspot/rest/test/schemes

On the server, the access key is extracted from the HTTP header attribute dataspot-access-key.

The access key determines the user or service user and the tenant.
The access rules are not evaluated.

Assign credentials to users

The login tenant is the tenant in which a user is logged into in the user interface or via programming interfaces (metadata REST/API, metadata upload/download). Based on the login ID in the credentials, the login tenant is determined as follows:

If a tenant is specified in the HTTP header attribute dataspot-tenant, log into this tenant.
If the login ID refers to the system administrator, log into the default tenant.
If a user with the login ID and the indicator, that the user is logged in by default, exists in a tenant, log into this tenant.
If a user with the login ID exists in the default tenant, log into the default tenant.
If a user with the login ID exists in another tenant, log into that tenant.
The login ID doesn't exist, therefore log into the default tenant.

⚠️ Attention
If a tenant is specified in the HTTP header attribute dataspot-tenant, the user is forced to log into this tenant, regardless of the authentication method. If the user does not have access to the tenant, or the tenant does not exist, the login is rejected.

🛈 Note
Exactly one default tenant is defined in each database. Depending on the authentication method, this default tenant can be overridden in the credentials (see DATASPOT_REMOTE_USER_TENANT_NAME, DATASPOT_JNDI_TENANT_NAME and DATASPOT_OIDC_JWT_TENANT_NAME).

For the login tenant as well as for all other tenants, it is determined whether the user has access to the tenant and whether the tenant can be selected in the user interface:

If the login ID exists in a tenant, the user is granted access according to their specified access level.
If the login ID does not exist in a tenant, the access rules of the tenant are evaluated.
A system administrator, or a user who is allowed to act as a system administrator (see DATASPOT_ADMIN_USER), is also granted access to all tenants with additional authorization as a system administrator.
Otherwise, the user is not granted access to the tenant.

⚠️ Attention
If the user does not have access to the login tenant, the login is rejected.

Evaluate access rules

A user, whose login ID does not exist in a tenant, can nevertheless be granted access to the tenant. For this purpose, appropriate access rules can be configured in the tenant, allowing to log into the tenant and select the tenant in the user interface.

⚠️ Attention
The access rules are not evaluated if an access key is used for authentication.

The additional rules for the access to the tenant are evaluated if an externally authenticated user cannot be assigned to the login ID of an existing user. The access rules are processed from top to bottom:

The condition of each access rule is evaluated.
- If the condition applies, the action is executed, i.e. the access is granted or denied and, if necessary, a user is automatically created. If no condition is defined, the action is always executed. No further access rules are processed.
- If the condition doesn't apply, evaluation continues with the next access rule.
If no access rule applies, the access is denied.

🛈 Note
Access rules are only evaluated, if they are enabled (DATASPOT_ACCESS_RULES). Otherwise, external users are always denied.

⚠️ Attention
The authentication method with login ID and password (basic authentication) doesn't support logging in as a guest (read-only) without a user.

Depending on the authentication method (Single sign-on, Same sign-in, OpenID Connect), the user must nevertheless be verified in the external system (on the reverse proxy, in LDAP, in Microsoft Entra ID, etc.).

🛈 Note
In order for the credentials to be evaluated and assigned to a user in the application, the database name (e.g. test) must be specified in the URL (e.g. https://www.myserver.com/dataspot/web/test) when accessing the user interface or calling a programming interface.

What's new?​

Authentication methods​

Login ID and password (basic authentication)​

Configuration​

Example: Login ID and password (basic authentication)​

Single sign-on (pre-authentication)​

Configuration​

Example: Single sign-on (pre-authentication)​

Example: API-KEY token​

Example: Apache HTTP server with LDAP module​

Same sign-in (directory service/LDAP)​

Configuration​

Example: Same sign-in (directory service/LDAP)​

OpenID Connect (bearer authentication)​

Configuration​

Subject Identifier​

Example: OpenID Connect (bearer authentication)​

Example: Resource Owner Password Credentials (ROPC)​

Example: OAuth 2.0 Client Credentials Grant​

Access key​

Example: Access key​

Assign credentials to users​

Evaluate access rules​

What's new?

Authentication methods

Login ID and password (basic authentication)

Configuration

Example: Login ID and password (basic authentication)

Single sign-on (pre-authentication)

Configuration

Example: Single sign-on (pre-authentication)

Example: API-KEY token

Example: Apache HTTP server with LDAP module

Same sign-in (directory service/LDAP)

Configuration

Example: Same sign-in (directory service/LDAP)

OpenID Connect (bearer authentication)

Configuration

Subject Identifier

Example: OpenID Connect (bearer authentication)

Example: Resource Owner Password Credentials (ROPC)

Example: OAuth 2.0 Client Credentials Grant

Access key

Example: Access key

Assign credentials to users

Evaluate access rules