User Access Control

UAC Policies

Manage users' access to TimeBase streams via User Access Control (UAC):

• Authentication: TimeBase uses external services such as Apache DS and Active Directory to authenticate users. Refer to Authentication Provider Configuration to learn more.
• Authorization: TimeBase allows authorizing access to streams based on rules and permissions configured for user/user group. Refer to Rules Configuration to learn more.

UAC Rules

In order to implement UAC policies, a system administrator defines a set of UAC rules. Each UAC rule tells the system the actor that can perform a certain action, and on which resources (streams) that action can be performed. For example, "user John can read stream level2data".

UAC rules specify the following criteria:

• Actor: A user or a group of users who can perform a specific action.
• Action: An action or permission (e.g., reading a TimeBase stream). There is a set of predefined actions that can be extended.
• Target: Describes the resource the rule applies to. There are two types of targets:
  • Streams.
  • Users or user groups: In this case, the rule applies to all resources owned by a given user or group.

Configuration

TimeBase stores the UAC rules in <TimeBase Home>/config > uac-access-rules.xml.

The rules can be defined in any order. Each rule may contain multiple actors, actions, and/or targets. To see an explanation of the file syntax, go to the Rules Definition section.

With well-defined roles mapped to custom groups, the uac-access-rules.xml file can be configured just once. Day to day tasks like adding new users are usually implemented using group membership rather than by editing access rules. To learn more, refer to the Best Practices section.

Please do not confuse groups and their permissions. Groups define the administrative structure of your organization. Typically, groups are used to model various roles in the organization. For example, the custom group TimeBaseDesigners may provide permissions to create new TimeBase streams.

Example

The following rule allows the admin user to modify the TimeBase stream called Securities and read any stream that belongs to one of the members of the Traders group.

	Actor	Action	Target
Allow	admin (user)	READ,WRITE	Securities (stream)
Allow	admin	READ	Traders (group)

Wildcards

The system allows defining UAC rules that apply to any target or provide any permission to a given actor.

If the wildcard character * appears in the context of:

• An Actor: the rule can apply to anybody.
• An Action: the rule can apply to any action.
• A Target: the rule can apply to any person or any resource.

Example

The following rule allows members of the Administrators group to do anything:

	Actor	Action	Target
Allow	Administrators (group)	*	*

The following rule allows members of the GoodTraders group to share everything. This rule literally means: allow any member of the GroupTraders group to perform any action on any resource (stream) that belongs to any member of this group.

	Actor	Action	Target
Allow	GoodTraders (group)	*	GoodTraders (group)

Resource Patterns

Target can use simple patterns to identify resources and users. In addition to simple wildcards described in the previous section, a target can use:

• Multiple wildcards

  	Actor	Action	Target (format:wildcard)
  Allow	GoodTraders (group)	*	*Futures* (stream pattern) any stream that contains word FUTURES in its name

• Regular Expression (there are many syntax references)

  	Actor	Action	Target (format:regex)
  Allow	GoodTraders (group)	*	.+Futures.+ (stream pattern) any stream that contains word FUTURES in its name

Resource Ownership

TimeBase streams are resources for UAC. Each stream has a single owner (usually user who created this specific stream/resource). System automatically defines only once implicit permission for resource owners to perform any action on owned resources.

	Actor	Action	Target
Allow	John	*	John

System Rules

System rules describe actions over resources that does not belong to specific user or belong to unknown user. For example, the following rule allows any user group member to create TimeBase streams. You can omit the Target argument for system rules.

	Actor	Action
Allow	Use Group	CREATE

Orphan Resources

Resources owned by unknown users (e.g. users that have been removed from the Directory Service) de-facto belong to the system, but require system rules.

Deny Rules

It is possible to express security policy in terms like "allow anything except...". This can be implemented using a combination of Allow and Deny rules. For example, to allow user John editing any stream except "securities":

	Actor	Action	Target
Allow	John (user)	READ,WRITE	* (stream)
Deny	John (user)	WRITE	securities (stream)

Just like Allow rules, rules that have Deny effect can use * action, as well as wildcards and regular expressions, and use any resource type as target. Order in which different rules are defined is not important. Each permissions check is done in two steps:

1. Reject action if user doesn't have matching Allow rule, otherwise go to Step 2.
2. Reject action if user has matching Deny rule, otherwise allow the action.

Multiple Groups Membership

User inherits permissions of all groups the user is a member of.

Consider the following example:

User John is a member of groups: TimeBaseConsumers and TimeBaseProducers. In our example permissions are defined in following way:

	Actor	Action	Target
Allow	TimeBaseConsumers	READ	* (stream)
Allow	TimeBaseProducers	CREATE, READ, WRITE	* (stream)

As a member of each of these groups John will have all these permissions:

	Actor	Action	Target
Allow	John	CREATE, READ, WRITE	* (stream)

Membership in groups that have Deny access rules may reduce user rights. For example, if TimeBaseConsumers are not allowed to edit 'securities' stream, John won't be able to edit this stream despite the fact that TimeBaseProducers can edit any stream.

	Actor	Action	Target
Deny	TimeBaseConsumers	WRITE	* (stream)

User Impersonation

System allows administrative users to impersonate other users. For example, Administrator may be allowed to create a stream that belongs to a specific user. This action is controlled using IMPERSONATE permission. System performs two checks every time resource changes ownership:

1. Current User, IMPERSONATE, New Owner
2. Current User, IMPERSONATE, Old Owner

Permission IMPERSONATE can only be defined using principal (user or group) as permission targets.

Predefined Permissions

The following table lists TimeBase permissions.

Action	Description	System	Resource
READ	Permission to read a stream		+
WRITE	Permission to write into a stream. User must also have READ permission on the stream.		+
CREATE	System permission to create a stream	+
CHANGE_SCHEMA	Administrative permission to edit stream schema (data types). User must also have WRITE permission to commit changes.		+
IMPERSONATE	Administrative permission to impersonate other users. Typically is granted to Administrators who create streams and grant access to TimeBase on behalf of other, non-administrative users. This permission allows users to change stream ownership (define a user who owns a stream). Internal use only.		+

Rules Definition

TimeBase UAC rules are defined in uac-access-rules.xml file located in <TimeBase Home>/config folder.

The following table briefly describes uac-access-rules.xml file format:

XML Element	XML attribute	Description	Examples
allow		Contains ALLOW rule
deny		Contains DENY rule
principal		Actor - user or group that identifies who will be performing allowed action	John Administrators
permission		Action - one of standard or custom permission names. Can be * (any).	READ, *
resource		Identifies resource (user, group, or stream) . Can be * (any)	securities Traders
resource	Type	One of: "Stream" or "Principal". Optional. Default is "Principal".	type="Stream"
resource	Format	One of: "Text", "Wildcard" or "RegEx". Optional. Default is "Text".	format="RegEx"

<!-- `uac-access-rules.xml` example -->

<!-- Any member of Users group can READ "data" stream -->

<allow>
    <principal>Users</principal>
    <permission>READ</permission>
    <resource type="Stream">data</resource>
</allow>
<!-- Note that each rule may contain multiple principal, permissions, and resources:-->
<allow>
    <principal>Users</principal>
    <permission>CREATE</permission>
</allow>
<allow>
    <principal>Users</principal>
    <permission>READ</permission>
    <resource type="Stream">data</resource>
    <resource type="Stream">securities</resource>
    <resource type="Stream">events#</resource>
    <resource type="Stream" format="Wildcard">ES#SYS#*</resource>
</allow>
<deny>
    <principal>trader1</principal>
    <permission>WRITE</permission>
    <resource type="Stream">securities</resource>
</deny>

UAC Configuration

TimeBase uses the Apache Directory Service and Active Directory authentication service providers via the LDAP protocol. We also support LDAP over SSL (LDAPS).

You can configure TimeBase to read Users and Groups from the following places:

• Apache Directory Server
• Active Directory
• Local configuration files

warning

Due to possible security leaks, only use local configuration files in test and UIT environments.

OAuth2

To access TimeBase:

• Before login, users and groups should be specified in the uac-oauth-security.xml config file.
• At login, users need to provide their username and OAuth2 token (token is required only for clients before 5.6.110 version).

Starting from version 5.6.110, TimeBase client applications support OAuth2 authentication using either client credentials or user credentials (via authorization code flow). This means that client applications no longer need to provide tokens during login as tokens will now be requested and refreshed automatically.

There are two types of clients, depending on the type of authentication:

1. User-facing Applications These clients have a user interface and can open a browser to allow users to enter their credentials on the authentication provider's page. They use the authorization code flow for OAuth2 authentication. Examples of such applications include TimeBase Desktop Admin and TickDB Shell.

2. Service Applications These clients do not have a user interface for entering user credentials or they operate with TimeBase as a service on behalf of no specific user. They use client credentials for OAuth2 authentication. Examples include Aggregator or TickDB Shell running in a service mode.

Configuration

To configure OAuth via XML file:

1. set the following properties in <TimeBase Home>/config > admin.properties:

QuantServer.security=OAUTH
QuantServer.security.rulesConfig=uac-access-rules.xml
QuantServer.security.userDirectoryConfig=uac-oauth-security.xml

2. Configure uac-oauth-security.xml:

In the configuration, two application names are reserved for each type of client. The name timebase.client.application is used for User-facing Applications (for example, TimeBase Desktop Admin), and timebase.client.service is used for Service Applications (for example, Aggregator).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<config xmlns="http://xml.deltixlab.com/internal/quantserver/3.0">
    <!-- Available users and clients list -->
    <users>
        <user id="User1"></user>
        <user id="User2"></user>
        <user id="TBClientService"></user>
        <!--...-->
    </users>

    <!-- List of groups for which users and clients belongs -->
    <groups>
        <group id="Group1">
            <principal>User1</principal>
            <principal>Client1</principal>
        </group>
        <group id="Group1">
            <principal>User1</principal>
        </group>
        <group id="Group3">
            <principal>TBClientService</principal>
        </group>
        <!--...-->
    </groups>
    <oauthSettings>
        <!-- oauth provider settings -->
        <issuer>https://auth-provider-host/issuer/url/path</issuer>
        <jwksUrl>https://auth-provider-host/jwks/url/path</jwksUrl>

        <!-- list available clientId(s) -->
        <clientId app="timebase.client.application">TBClientApp</clientId>
        <clientId app="timebase.client.service">TBClientService</clientId>
        <clientId app="custom application name 1">Client1</clientId>
        <clientId app="custom application name 2">Client2</clientId>
        <!--...-->
        
        <!-- list of scopes required during authentication for each application -->
        <!-- available since 5.6.110 -->
        <scope app="timebase.client.application">client_application_scope</scope>
        <scope app="timebase.client.service">client_service_scope</scope>
        <scope app="custom application name 1">openid profile another_scope</scope>
        <scope app="custom application name 2">scope1 scope2</scope>
        <!--...-->

        <!-- claim name from token that contains client id -->
        <!-- value from the claim will be used as username for Service Applications -->
        <clientIdClaim>azp</clientIdClaim>

        <!-- claim name from token that contains username -->
        <!-- value from the claim will be used as username for User Applications -->
        <!-- available since 5.6.110 -->
        <usernameClaim>preferred_username</usernameClaim>
    </oauthSettings>
</config>

3. Configure uac-access-rules.xml as described here.

To configure TimeBase client applications with OAuth2, follow the next tutorials:

• TimeBase Desktop Admin;
• TimeBase WebAdmin;
• TimeBase Shell CLI as User-facing Application;
• TimeBase Shell CLI as service;
• Aggregator.

Example

Here is an example of the uac-oauth-security.xml file for EntraID:

<!-- uac-oauth-security.xml for EntraID example -->
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<config xmlns="http://xml.deltixlab.com/internal/quantserver/3.0">
    <users>
        <user id="trader">
        </user>
        <user id="manager">
        </user>
        <user id="d69eb9b-e7c3-4bf3-1111-111111111111">
        </user>
    </users>
    <groups>
        <group id="Traders">
            <principal>trader</principal>
        </group>
        <group id="RiskManagers">
            <principal>manager</principal>
        </group>
        <group id="Service">
            <principal>d69eb9b-e7c3-4bf3-1111-111111111111</principal>
        </group>
    </groups>
    <oauthSettings>
        <issuer>https://login.microsoftonline.com/b41b72d0-1111-1111-1111-111111111111/v2.0</issuer>
        <jwksUrl>https://login.microsoftonline.com/b41b72d0-1111-1111-1111-111111111111/discovery/v2.0/keys</jwksUrl>

        <clientId app="timebase.client.application">4d69eb9b-e7c3-4bf3-1111-111111111111</clientId>
        <clientId app="timebase.client.service">4d69eb9b-e7c3-4bf3-1111-111111111111</clientId>
        <clientId app="Ember">d69eb9b-e7c3-4bf3-2222-222222222222</clientId>
        
        <scope app="timebase.client.application">openid profile offline_access api://4d69eb9b-e7c3-4bf3-1111-111111111111/app</scope>
        <scope app="timebase.client.service">api://4d69eb9b-e7c3-4bf3-1111-111111111111/.default</scope>
        <scope app="Ember">api://d69eb9b-e7c3-4bf3-2222-222222222222/.default</scope>

        <clientIdClaim>azp</clientIdClaim>
        <usernameClaim>preferred_username</usernameClaim>
    </oauthSettings>
</config>

Here is an example of the uac-oauth-security.xml file for Keycloak:

<!-- uac-oauth-security.xml for Keycloak example -->
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<config xmlns="http://xml.deltixlab.com/internal/quantserver/3.0">
    <users>
        <user id="admin">
        </user>
        <user id="web_admin_master">
        </user>
    </users>
    <groups>
        <group id="Administrators">
            <principal>admin</principal>
        </group>
        <group id="Service">
            <principal>web_admin_master</principal>
        </group>
    </groups>
    <oauthSettings>
        <issuer>http://localhost:8282/realms/timebase</issuer>
        <jwksUrl>http://localhost:8282/realms/timebase/protocol/openid-connect/certs</jwksUrl>

        <clientId app="timebase.client.application">tb_admin</clientId>
        <clientId app="timebase.client.service">web_admin_master</clientId>

        <!- Used default scopes (openid + profile) ->
        
        <clientIdClaim>azp</clientIdClaim>
        <usernameClaim>preferred_username</usernameClaim>
    </oauthSettings>
</config>

LDAP

To generate the LDAP configuration file, use the UACCONF tool. The configuration file defines LDAP connection parameters (for example, host, port, and login credentials) and query filters that locate user groups for TimeBase. You can find a sample of this file in \build\classes\config\uac-ldap-security.xml.

Configuration

To configure LDAP, set the following properties in <TimeBase Home>/config > admin.properties:

QuantServer.security=LDAP
QuantServer.security.rulesConfig=uac-access-rules.xml
QuantServer.security.userDirectoryConfig=uac-ldap-security.xml

Customize Query Filters

You can customize query filters and define multiple group filters. For example, the following filters locate the custom group TimeBaseUsers:

• Apache DS

  <groups filter="(&(objectClass=groupOfUniqueNames)(cn=TimeBaseUsers))" node="ou=ExternalGroups,dc=timebase,dc=com"/>

• MS Active Directory

  <groups filter="(&(objectClass=group)(cn=TimeBaseUsers))" node="ou=ExternalGroups,dc=timebase,dc=com"/>

User Group Access

When your user directory is stored in LDAP, you need to tell TimeBase which group(s) are allowed to access it. The TimeBase system builds the list of users based on these groups. Every TimeBase user must be a member of at least one group listed in the LDAP configuration. Groups and users excluded from this list are not allowed to access the system (such users are not authenticated).

This approach is recommended for large organizations that have a lot of users, whose entire organizational structure is defined in services like Active Directory, and do not want to expose all users to TimeBase.

Directory service implementations like Apache DS lack a convenient and simple GUI to create users and groups. To simplify the procedure, TimeBase provides a UAC Shell that simplifies this task. You can also define your user directory in the Apache Directory Studio GUI.

XML File

Configuration

To configure UAC via an XML file, set the following properties in <TimeBase Home>/config > admin.properties:

QuantServer.security=FILE
QuantServer.security.rulesConfig=uac-access-rules.xml
QuantServer.security.userDirectoryConfig=uac-file-security.xml

Example

You can define users and groups in <TimeBase Home>/config > uac-file-security.xml.

<!-- uac-file-security.xml example -->\
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<config xmlns="http://xml.deltixlab.com/internal/quantserver/3.0">
    <users>
        <user id="admin">
            <password>admin</password>
        </user>
        <user id="JohnDoe">
            <password>QWERTY</password>
        </user>
        <user id="OwnersManager">
            <password>123</password>
        </user>
        <user id="User1">
            <password>123</password>
        </user>
        <user id="User2">
            <password>123</password>
        </user>
        <user id="User3">
            <password>123</password>
        </user>
        <user id="User4">
            <password>123</password>
        </user>
    </users>
    <groups>
        <group id="Administrators">
            <principal>admin</principal>
        </group>
        <group id="Users">
            <principal>JohnDoe</principal>
        </group>
    </groups>
</config>

UAC Tools

UACCONF

TimeBase provides special utility that prepares LDAP configuration for future use. It does the following:

1. Generates configuration file that describes LDAP UAC configuration for TimeBase. This file is stored in <TimeBase Home>\config\uac-ldap-security.xml.
2. When running against Apache DS, the tool pre-creates users, groups, and rules. This is useful for installations that use clean directory service. If you already have your organization defined in one of the directory services, skip this step.

The following example shows tool arguments. Note, that we use full username to connect to LDAP. Also this sample uses domain "dc=timebase,dc=com" (in your case it might be a different one).

uacconf -home "C:\temp\home" \ 
        -server ldap://localhost:10389 \ 
        -user "uid=admin,ou=system" 
        -pass secret \ 
        -domain "dc=timebase,dc=com"

LDAP over SSL example

uacconf -home "C:\temp\home" \ 
        -server ldaps://localhost:10636 \ 
        -user "uid=admin,ou=system" 
        -pass secret \ 
        -domain "dc=timebase,dc=com"

Shell

TimeBase provides command line utility (located at \bin\uac) you can use to edit users and groups in Apache DS (or any LDAP). If you use Microsoft Active Directory we recommend using Microsoft GUI to manage user directory. The following example shows how use UAC tool.

For a complete list of commands supported by UAC type help or ?.

You can exit this tool using exit or quit commands

First of all, this tool needs to know the location of your TimeBase Home directory. There are two ways to supply this information:

• specify this via command line argument -home
• set home variable after you launch the tool:

Connect

==> set home .../Home 
Setting home=.../Home 
==> connect 
... 
==> list 
>>> Directory Users: 
Admin Admin, Member Of: (Administrators), Description: jdoe John Doe, Member Of: (Traders), Description: 
>>> Directory Groups: 
Traders Users: (jdoe), Groups: () Administrators Users: (Admin), Groups: () ...

Add User

The following example shows how to connect to Directory Server:

==> newuser jsmith;password;Traders;Jeff;Smith;This is a description 
==> list 
>>> Directory Users: 
Admin Admin, Member Of: (Administrators), Description: jdoe John Doe, Member Of: (Traders), Description: jsmith Jeff Smith, Member Of: (Traders), Description: 
>>> Directory Groups:
Traders Users: (jdoe,jsmith), Groups: () Administrators Users: (Admin), Groups: () ... 
==>quit

Add Group

The following sample shows how to add a group "RiskManagers" that consist of two members (andy, and nick):

==> newgroup RiskManagers;andy,nick 
==> listgroups 
>>> Directory Groups: 
Risk Users: (nick, andy), Groups: () 
...

Best Practices

Minimize UAC Rules

TimeBase UAC uses "default-deny" model - by default everything is prohibited. UAC rules that you define should allow users to perform their normal tasks but not much more.

Minimize Users that Can Access TimeBase

We recommend limiting users that may use TimeBase software using group filters in LDAP configuration. For example, you can create a group Users end list eligible users in this group (a group can reference other groups). Limiting group filter to Users ensures that anybody who is not a member of this group will not be able to pass authentication (and gain any access to the system).

<groups filter="(objectClass=groupOfUniqueNames)" node="ou=DeltixUsers,ou=groups,dc=deltix,dc=com"/>

To allow multiple groups you can specify multiple group elements in your LDAP configuration file.

Role-Based Groups

Define custom groups that reflect different roles people play in your organization. A user can be a member of more than one group. We recommend using groups rather than individual rules for users.

Avoid Too Many DENY Permissions

By default, system prohibits everything, but the best way to prohibit something is minimizing UAC rules rather than granting too many permissions. For example, if you want to prohibit access to a resource for a specific user, simply exclude this user from a group rather than defining another DENY rule for this user.