Teneo Developers

Teneo Manager

Introduction

Various Teneo Platform application settings and users, groups and permissions are managed in a centralized manner with Teneo Manager, which also handles user authentication and authorization following the OAuth2 protocol. The managed data is stored in a local database and exposed to applications via an HTTP Rest API. Group and user data may optionally be synchronized with an Active Directory server as well as created using the said HTTP Rest API.

Teneo Manager entities

Users and user access rights are organized in Teneo Manager by the following items:

User

A User item represents a particular user that logs on to a Teneo Platform application. It stores the user's ID, password and name. A user item may be backed by an Active Directory user entry.

Group

A Group item usually represents a company. User items are organized in groups. A user can be a member of one or more groups. A group item may be backed by an Active Directory group entry. Active Directory supports “nested groups” (a group which is assigned to another group which holds a certain permission). In Teneo Manager nested group memberships are not directly reflected, but TM keeps track of direct and indirect membership (from a nested group) of a user in a company group.

Account

An Account is assigned to one application instance (e.g. Teneo Studio) and contains a certain amount of per-user access permissions to the resources provided by said application. Typically, an account is associated with a specific customer.

Though an account stores access permissions per user, access to an account is granted on a group level. That is, in order to grant access to an account for a certain user, a group where said user is a member needs to be connected to the account. Consequently, all members (users) of that group get access to the account.

In the Studio Backend, one or more solutions are assigned to an account. Thus, a user who is assigned to a Studio Backend account gets access to all solutions assigned to that account.

Log Archive

A Log Archive represents a data warehouse entity stored in the TI component. Its main configuration is stored in TM and assigned to one and only one TI instance. It's aim is to be an archive for log data and the source for a number of LDS.

Log Data Source

A Log Data Source (LDS) represents a data source entity stored in the Teneo Inquire application, which other components can use to obtain log data. Its main configuration is stored in Teneo Manager and assigned to one and only one Teneo Inquire instance. Several users or groups may be assigned access to the LDS; if a user is assigned both as an individual user and as part of a group, the effective user’s roles is the aggregation of both.

Client

A Client represents a Teneo Platform application instance. It stores the application's ID, secret, and redirect URL.

Abbreviations

In this section the following abbreviations will be used:

TermAbbreviation
Active DirectoryAD
Graphical User InterfaceGUI
Log Data SourceLDS
Teneo DiscoveryTD
Teneo InquireTI
Teneo ManagerTM
Teneo StudioTS
Virtual AssistantVA

Administration GUI

System requirements

In order to access the TM GUI console, one of the following browsers is required:

  • Chrome version 81 onwards
  • Firefox 76 onwards (on Windows or Ubuntu)
  • Edge 44 onwards
  • Safari 12 onwards

Important note: cookies need to be enabled in the browser.

Login

Login to the administration GUI requires a user account with an ADMINISTRATOR role. A built-in user account with the ADMINISTRATOR role is provided, with a username and a password that is specified by the TM installation (see the installation guide for details). The ADMINISTRATOR role may be granted to standard user accounts (see User management).

The login starts a web session with a 30 minutes’ timeout. If the session timeout occurs, the user will be sent back to the login page.

GUI layout

The administration GUI is divided into a header row, a navigation bar on the left side, and the central space for the management pages. The header row displays the name of the currently logged in user, and the [Logout] button. The navigation bar is subdivided into groups of related management functions.

General GUI management

The management pages related to client settings require a client context. Thus, on the first navigation after login to a client settings page, a client selection dialog is displayed. After selecting a client, the target client settings management page is displayed. The selected client name is displayed on the top of the page, besides a button to re-open the client selection dialog. The client selection is saved in the session context and applies to all settings management pages of the client type.

Most of the data tables displayed in the GUI allow inline row editing of data properties. A table row is put into editing mode by clicking on the pen icon in the Edit column of the row. While a row is in editing mode, instead of the pen icon, a check and a cross icon are displayed. Clicking on the check icon confirms the edit and exits the edit mode. Clicking on the cross icon discards the changes and exits the edit mode.

Some data tables allow the null value for displayed settings, which is shown as null. In edit mode, an additionally displayed [Null] button allows to toggle the value between null and not-Null. If a setting is null, the setting’s edit field is disabled.

A data table may be sortable by a certain column, visualized by an arrow beside the column header. Clicking on the column header selects the soring column and changes the sorting order. A data table may also be filterable by a certain column, visualized by an edit field (for the filter expression) or a combo-box displayed under the column header. The filtering is not case sensitive.

Common

The Common section contains the Main (or Start) page and management pages for the data that’s shared between all clients.

Main page

After logging on to the administrator GUI the Main Page is displayed. It shows a statistics panel and an individual panel for the following tasks:

  • Sync task – This task synchronizes the TM users and groups’ data with the LDAP; it is executed every minute. The [Start] button manually triggers the task. Time and result of the latest task execution are displayed beside the button. This task is hidden if TM is not running in LDAP mode;
  • Unlock task – This task unlocks locked users (see User Management for details on locked users), and is executed every 15 minutes. The [Start] button manually triggers the task. Time and result of the latest task execution are displayed beside the button;
  • DbChecker – This task checks the health of the DB connection; it is executed every minute. The [Start] button manually triggers the task. Time and result of the latest task execution are displayed beside the button;
  • LdapChecker – This task checks the health of the LDAP (AD) connection; it is executed every minute. The [Start] button manually triggers the task. Time and result of the latest task execution are displayed beside the button. This task is hidden if TM is not running in LDAP mode.

User management

The User management page lists the existing users and offers to add, modify, and deleted users.

If TM runs in LDAP mode, the user data will be synchronized from the LDAP every minute. In order to avoid interference with GUI interaction the user table is not updated automatically, you need to reload the page to see any changes.

A user has the following properties:

  • ID – The unique internal ID of the user. This is a UUID value in hexadecimal text format. The value is fixed and generated by TM.
  • LDAP base DN – this is the LDAP location of the new user. This property is hidden if Teneo Manager is not running in LDAP mode.
  • Name – the free-text name of the user. The name must be unique and match the regular expression defined by the userNameRegex setting (see Manager Settings Management). If Teneo Manager runs in LDAP mode, the user name restrictions of the LDAP also apply.
  • Logon – the logon name of the user. The logon name must be unique and match the regular expression defined by the userLogonRegex setting (see Manager Settings Management). If Teneo Manager runs in LDAP mode, the logon name restrictions of the LDAP also apply.
  • The logon name will be used to identify a user when logging in to the administration GUI and for authentication with the REST interface.
  • Enabled – toggle to enable/disable login of the user. If TM runs in LDAP mode, this flag also enables/disables the user in LDAP.
  • Email – this value is used only by client applications.
  • Password – the user password must match the regular expression defined by the userPasswordRegex setting (see Manager Settings Management). If Teneo Manager runs in LDAP mode, the password restrictions of the LDAP also apply.
  • Assigned roles - the roles to assign to the user. In order to enable the user for TM administration GUI login, the user must have the ADMINISTRATOR role assigned.
  • Assigned groups – the groups to which the user should be assigned. User access to clients will be granted only via groups.

The table in the section User management lists the existing users. The action links in the Roles, Groups, LDS access roles, Password Reset, and Edit columns open dialogs for editing the related data. The action link in the Accessible Accounts column opens a dialog that visualizes the relation between the selected user and the client accounts to which the user is assigned (via groups). The action link in the Delete column opens a confirmation dialog for deletion of the selected user.

The [Create a User] button opens a wizard dialog where the user properties must be entered (mandatory properties are marked with an asterisk). Creating a user adds the user to the local database. If TM runs in LDAP mode, the user will also be created in the LDAP. If the new user is assigned to a group which is assigned to a client, then the new user will immediately get access to that client.

When a user is deleted, the user will be removed immediately from the local database and all REST interface tokens currently issued for the user will be revoked. If TM runs in LDAP mode, the user will also be deleted from the LDAP.

Group management

The Group management page lists the existing groups and offers to add, modify, and delete groups.

If TM runs in LDAP mode, the group data will be synchronized from the LDAP every minute. In order to avoid interference with GUI interaction the group table is not updated automatically.

A group has the following properties:

  • ID – the unique internal ID of the group. This is a UUID value in hexadecimal text format. The value is fixed and generated by TM.
  • LDAP base DN – this is the LDAP location of the new group. This field is hidden when TM is not running in LDAP mode.
  • Name – the free-text name of the group. The name must be unique and match the regular expression defined by the groupNameRegex setting (see Manager Settings Management). If Teneo Manager runs in LDAP mode, the group name restrictions of the LDAP also apply.
  • Assigned users – the users which are assigned to the group. Access to clients will be granted to all users in the group.

The table on the Group management page lists the existing groups. The action link in the Users columns opens a dialog for editing the users assigned to the group. The action link in the Accessible Accounts column opens a dialog that pictures the relation between the selected group and the client accounts to which the group is assigned. The action link in the Edit column starts inline editing of the selected table row. The action link in the Delete column opens a confirmation dialog for deletion of the selected group.

The [Create a Group] button opens a wizard dialog where the group properties must be entered (mandatory properties are marked with an asterisk). Creating a group adds it to the local database. If TM runs in LDAP mode, the group will also be created in the LDAP.

When a group is deleted, it will be removed immediately from the local database. If TM runs in LDAP mode, the group will also be deleted from the LDAP.

Log Archive management

The Log Archive management page lists the Log Archives that may be assigned to the managed clients. Here Log Archives may be added, modified and deleted. Please note that before a new Log Archive can be added to a client, the target client needs to be created.

A Log Archive has the following properties:

  • ID – the Log Archive’s unique identifier, using an UUID format. The field is set when creating the Log Archive and cannot be modified afterwards.
  • Client – the Inquire client for which the LDS is being created. This is a mandatory field as no Log Archive can be created without being assigned to a client; the Client cannot be reassigned.
  • Name – the free-text name of the Log Archive. The value must be unique within the selected Inquire Client. Log Archive names must be 2-60 characters long with characters from any of the following categories: letters (UPPER or lower case), numbers (0-9), dot (.) and special characters (e.g. #@&!%).
  • Description – optionally, a brief description of the Log Archive can be added.
  • Keyspace – this field is generated automatically after the Log Archive’s ID and cannot be modified.
  • Replicas – the amount of replicas (r), that is, the amount of copies of the Log Archives that will be generated. r must be lower than the number of nodes – in such event, it will be automatically adjusted. This field is set when creating the Log Archive and cannot be modified afterwards.

The [Create a Log Archive] button opens a wizard dialog where the basic Log Archive properties must be entered (mandatory properties are marked with an asterisk). Deleting a Log Archive from the management page also deletes all access roles assigned to it.

For more information on the Log Archives or Log Data Sources, or to Teneo Inquire, please refer to the Teneo Inquire documentation.

Log Data Source management

The LDS management page lists the LDSs that may be assigned to the managed clients. Here LDSs may be added, modified and deleted. Please note that before a new LDS can be added to a client, the target client needs to be created.

An LDS has the following properties:

  • ID – this is only displayed when updating the LDS - The unique internal ID of the LDS. This is a UUID value in hexadecimal text format. The value is fixed and generated by TM. Client applications may use this value to identify a LDS.
  • Client – the Inquire client for which the LDS is being created. This is a mandatory field as no LDS can be created without being assigned to a client.
  • Name – the free-text name of the LDS. The value must be unique within the selected Inquire Client. It is important to note that the field Name cannot contain the following characters: \, /, *, ?, ", #, <, >, |, %, :, space and upper case letters, neither start with a dot nor an underscore. Elasticsearch index name is derived from it and limits the format.
  • Log Archive – the Log Archive the LDS will be reading logs from.
  • Weeks – the week span of the data to be imported to Elasticsearch, ending at the week selected at the “Until” date (see the next point). By default, the amount of weeks is pre-set to 12, but it can be modified at any time, even after the LDS has been created.
  • Week numbers use the ISO8601 format (i.e. week starts on a Monday).
  • Weeks are imported as ‘calendar weeks’ in full, even though the week has not yet ended.
  • Until – date until data is imported, in Year-Week format.
  • By default, it is set to ‘Now’, which means the LDS window frame will be dynamic, i.e. that the log data weeks included in the LDS will shift to always include the most recent log data. This update is executed automatically.
  • If now is unselected, then it is possible to set the LDS to always contain the same weeks.
  • Shards – the amount of Elasticsearch shards.
  • Replicas – the amount of Elasticsearch replicas.
  • Locale – the locale of the LDS language (and country), usually the published solution’s language.

Additionally, besides the properties defined for the LDS, users and groups may have different access roles for accessing the data. The following are the description of the different access roles:

  • Augmenter – the user is able to manage augmenters
  • Data – the user is able to manipulate data
  • Export – the user is able to export datasets
  • Importer – the user is able to trigger data imports
  • Sysadmin – the user is able to administrate the system
  • TQL – the user is able to run queries.

The table on the LDS management page lists the existing LDSs. The action link in the User access roles and Group access roles open a dialog for editing User and Group access roles respectively. The action link in the Edit column opens a dialog for editing the properties of the selected LDS. The action link in the Delete column opens a confirmation dialog for deletion of the selected LDS.

The User and Group access roles dialogues permit adding, updating and deleting access roles for Users and Groups. Users and groups are searched using the text box with autocomplete functionality. Once the user or group is selected, the different roles can be enabled or disabled using the specific checkboxes. Multiple users and groups may be added in a single operation. Once the items are added in the table, the Edit and Delete action links can be used to edit or delete them.

The [Create a LDS] button opens a wizard dialog where the basic LDS properties must be entered (mandatory properties are marked with an asterisk). Deleting a LDS from the LDS management page also deletes all access roles assigned to it.

Notes on shards and replicas in an Elasticsearch cluster

Each week of data is divided into shards which are distributed across the cluster. Replicas are duplicated shards distributed across the cluster. Each TQL query will run on 1 CPU core per shard in the elasticsearch cluster.

Therefore, adding shards lets each TQL query run across more shards in the cluster which in turn increases the performance per query.

Adding replicas means that more than 1 machine can run queries against that shard. In turn, this increases the performance of concurrent queries. Replicas also increase the resilience of the cluster as data is replicated.

Adding more machines or more cores does not automatically increase performance until there are more shards where queries can run on.

A recommended configuration is therefore 2 shards per node in the elasticsearch cluster with the number of replicas set to be number_of_nodes - 1. If elasticsearch has not been setup as a cluster then leave the pre-configured defaults.

The following table can be used as a reference:

NodesShardsReplicas
120
3 (recommended)62
5104

For more information on the Log Archives or Log Data Sources, or to Teneo Inquire, please refer to the Teneo Inquire documentation.

OAuth2

Client management

The Client management page lists the existing client instances managed by TM and offers to add, modify and delete client instances.

A client has the following properties:

  • Client ID – the unique identifier of the client. This is a UUID value in hexadecimal text format. The value is fixed and generated by TM. The client ID will be used to identify a client for authentication with the REST interface.
  • Client Secret – a text string (“password”) used for authentication with the REST interface. The value is fixed and generated by TM.
  • Client name – the free-text name of the client instance. The value must be unique.
  • Client type – eligible values: Teneo Discovery, Inquire, or Studio. The value is fixed as it is selected before the wizard dialog is opened.
  • Client description – a free-text description of the client instance.
  • Redirect URI – the client application URI to be opened after successful login. This value is needed only if the OAuth2 authentication flow “Implicit” is enabled.
  • OAuth2 flows – OAuth2 authentication flow types that should be enabled for the client.

Additionally, if the client type is Inquire two more fields are displayed:

  • Inquire Query URL – the query URL Inquire clients must use for querying the data.
  • Inquire DM URL – the Data Management URL Inquire clients must use for managing the data.

The table on the Client management page lists existing clients. The action link in the OAuth2 flows column opens a dialog for selection of the OAuth2 authentication flows that are enabled for the client. The action link in the Edit column starts inline editing of the selected row. The action link in the Delete column opens a confirmation dialog for deletion of the selected client instance.

The [New Client] button first displays a dropdown menu with the available client types. After selection of a client type, the wizard dialog for the creation of a new client instance is opened. In the form, mandatory client properties are marked with an asterisk. The dialog always begins with the common client properties tab. For the Teneo Discovery client type, an additional tab for the defined Discovery settings will be displayed.

When the wizard dialog has been completed, TM generates a unique client ID and a client secret (password) for the new client instance and adds it to the client table.

When a client is deleted, the client instance and all its settings will be removed immediately from the local database and all the REST interface tokens that are currently issued for the client instance will be revoked.

Token management

The Token management page lists the currently issued Access tokens (user and client tokens) on the first tab, API tokens on the second tab and the currently issued Refresh tokens (for user access tokens) on the third tab.

API Tokens are basically persistent Access Tokens for a particular client additionally linked to a user as well. They survive TM restarts since they are stored in the local DB. Their usage is basically for running scripts where tokens can be provided in script code.

The [Create an API token] button opens a dialog where a name, client and optional user and description can be provided.

On the other hand, Access and Refresh tokens tabs work in a similar way. The displayed data is refreshed automatically every 30 seconds, or immediately by clicking the [Refresh] button.

The [Revoke filtered access tokens] resp. [Revoke filtered refresh tokens] button revokes (deletes) all tokens that match the current table filtering. If no filtering is set, then all currently existing tokens will be revoked.

With the action link in the Revoke column of the table a single token may be deleted.

Tokens cannot be created in the GUI; it is only possible via the REST interface.

Teneo Discovery

This section contains management pages for the Teneo Discovery (TD) application instances. The Accounts and Settings Management pages require a client selection, as described in General GUI Management. The Account Setting Definitions management page is not related to a particular client context; thus, it doesn’t require a client selection.

A TD Account links a group of users to a particular Account in a TD server which also have a list of settings. TD uses the account ID to fetch the account settings using the TM REST interface.

Accounts management

The TD Accounts management page lists the currently defined accounts and offers to add, modify and delete accounts.

A TD account has the following properties:

  • ID – the unique internal ID of the account. This is a UUID value in hexadecimal text format. The value is fixed and generated by TM.
  • Name – the free-text name of the account. The name must be unique within a TD client.
  • Description – the free-text description of the account.
  • Enabled – this flag allows to temporarily disable an account in order to hide it from TD users. A disabled account should not be removed from the managed TD instance.
  • Groups – the groups assigned to the account. All users in the assigned groups will have access to the account.
  • Settings - a set of setting entities that allow the configuration per account. This list of settings is dynamically defined (see the Account Setting Definition Management for details).

The table on the Accounts management page lists the existing accounts. The action link in the Settings column opens an edit dialog for the values of the Settings of the selected account. The action link in The Groups column opens the edit dialog for the user groups assigned to the selected account. The action link in the Edit column starts inline editing of the selected row (name, description and enabled flag). The action link in the Delete column opens a confirmation dialog for deletion of the selected account.

The [Create an Account] button opens a wizard dialog for the creation of a new TD account (mandatory properties are marked with an asterisk). The account settings cannot be preset in this wizard. This must be done via the accounts table, after the creation of the new account is finished.

See the next chapter on how to work with account setting definitions.

Account setting definition management

All accounts in all TD clients share the same set of settings (the actual values of the account settings are configurable individually per account). This set of account settings is dynamically definable. When completing installation of TM, a needed set of account setting definitions are created automatically. This set is what TD need. Please refer to the Discovery documentation on details of the required account settings.

The TD Account Setting Definition management page lists the currently defined Account Settings and offers to add, modify and delete them.

An Account Setting Definition has the following properties:

  • Name – a free-text name of the account setting. The name must be unique.
  • This name will also be used in the REST interface to identify the account setting.
  • Initial Value – the initial value of the account setting.
  • Description – a free-text description of the account setting.

The table on the page lists the currently existing account setting definitions. The action link in the Edit column opens the property editing dialog for the selected account setting. The action link in the Delete column opens a confirmation dialog for deletion of the selected account setting.

The [Create account setting definition] button opens a dialog for the creation of a new account setting definition (mandatory properties are marked with an asterisk). The creation of a new account setting definition adds the account setting to each TD account and sets its value to the initial value. After that, changing the initial value will not affect the values of the present account settings.

Deleting an account setting definition also removes the account setting from all TD accounts.

Settings management

TD is supported in a limited sense in this version of TM. It just provides user login handling. TD settings are not used at present.

Teneo Studio

This section contains management pages for Teneo Studio (TS) application instances. The pages require a client selection, as described in General GUI Management.

Accounts management

This page allows to manage TS accounts (former called “customer” in TS).

A TS account has the following properties.

  • Id – unique identifier of the account (customer) to be used by TS. The value is a UUID in hexadecimal text format. In the account creation wizard (see below) this field is preset with a randomly generated value. In case the account is created for an already existing TS customer, its ID must be entered.
  • Name – the name of the account. The value must be unique within a TS client instance.
  • Enabled – this flag allows to temporarily disable an account in order to hide it from TS users. A disabled account is not removed from the managed TS instance.
  • Log Archives – these are the Log Archives assigned to the account. User can select one of those when publishing a solution in order to store and archive the logs.
  • LDS – these are the LDS assigned to the account which user can later link to a solution or just query them if no solution is open.
  • User permissions – a set of permissions that enable/disable certain actions for the TS customer related to the account. User permissions can also be inherited from all groups user is member of.
  • Group permissions – a set of permissions passed on groups' members which enable/disable certain actions for the TS customer related to the account.

The table on the TS Accounts management page lists the existing accounts. The action links in the Log Archives, LDSs, User and Group permissions columns each open a dialog for editing the related properties of the selected account. The action link in the Edit column starts the editing of the selected account. The action link in the Delete column opens a confirmation dialog for deletion of the selected account.

The [Create an Account] button opens a wizard dialog to create a new account (mandatory properties are marked with an asterisk). User and Group permissions are not assignable in the wizard dialog; this must be done from the accounts table after the account creation is completed. Once the account is created the related customer in the managed TS client instance is immediately available to the user.

Removing an account firstly removes it from TM only. The related customer is removed from the managed TS instance after a grace period of 24 hours, but only if it does not contain any solutions.

Teneo Manager administration

The TM Administration section contains management pages for settings that apply to TM itself or all clients in general.

This section is displayed only for the admin user and users granted the ADMINISTRATOR role.

Manager settings management

The Manager Settings management page displays the settings that control the TM instance itself. This does not include the settings provided as Java system properties (see the installation guide for details on these properties).

This view is divided into the following sections:

  • [Save and restart] – This button persists the changes done in any tab of the view. This will restart some internal services and also revoke all OAuth2 tokens, thus all currently existing user logons will be invalidated.
  • General tab – This tab is always visible and contains the General settings:
    • Authentication – a drop down to choose the authentication type, with the options DB, DELEGATED and LDAP.
  • Users and Groups source – a drop down to choose the source of users and groups, with the options DB and LDAP.
    • A table with the following list of settings:
      • groupNameRegex – a Java regular expression that defines the validness of a group. If TM runs in LDAP mode, the group name must also match the LDAP restrictions.
      • groupNameRegexInfo – Error message shown to the user if regex groupNameRegex does not match the chosen Group Name.
      • maxLoginAttempts – maximum allowed count of failed login attempts for a user within the unblock period (15 minutes). If the failed logon count of a user exceeds this limit, the user will be prevented from logon to the GUI and REST interface until the next execution of the user unblock task.
      • oauth2.accessTokenTimeout – lifespan of OAuth2 access tokens, given in minutes. The value must be a positive integer number.
      • oauth2.refreshTokenTimeout – minimum lifespan of OAuth2 refresh tokens, given in days. The lifespan will restart each time the refresh token is used. The value must be a positive integer number.
      • oauth2.stateTimeout – timeout for the OAuth2 implicit flow state parameter, given in seconds. The value must be a positive integer number.
      • public.url – defines a public URL in order to expose the access of the API through this external URL instead of using the internal one.
    • userLogonRegex – a Java regular expression that defines the validness of a user logon name. If TM runs in LDAP mode, the logon name must also match the LDAP restrictions.
  • userLogonRegexInfo – Error message shown to the user if regex userLogonRegex does not match the chosen Login Name.
    • userNameRegex – a Java regular expression that defines the validness of a user name. If TM runs in LDAP mode, the user name must also match the LDAP restrictions.
  • userNameRegexInfo – Error message shown to the user if regex userNameRegex does not match the chosen Username.
    • userPasswordRegex – a Java regular expression that defines the validness of a user password.
  • userPasswordRegexInfo – Error message shown to the user if regex userPasswordRegex does not match the chosen Password.
  • Ldap tab – This tab is only shown if either Authentication or Source is LDAP. Its settings and configuration is explained in the LDAP annex.
  • Delegated tab – This tab is only shown if Authentication is DELEGATED; its settings and configuration is explained in the Delegated authentication annex.

Client settings management

The Client Settings management page is organized in multiple tabs that each display the settings defined for a particular client (sub-module) type. It offers to add, modify and delete setting definitions.

On each tab the settings table displays the setting’s name, initial value and description text, furthermore it contains action links to open the edit dialog and to delete a setting definition.

The [Create setting] button opens a dialog for the creation of a new setting definition. The following properties must be entered:

  • Name – the free-text name of the setting. The name must be unique within a client (sub-module) type. This name will also be used in the REST interface to identify the setting.
  • Initial Value – the initial value the setting will be set to. The initial value may be set to null with the [Null] button toggle.
  • Description – a free-text description of the setting.

The creation of a new setting definition adds the setting to each instance of the related client (sub-module) type and sets it to the initial value. After that, changing the initial value will not affect the values of the settings of already existing client instances. But it will affect the setting value of a newly created client instance.

After creation of the setting definition its name will be fixed, thus renaming an existing setting definition requires to delete it and then re-add it with the new name.

Deleting a setting definition also removes the setting from all instance of the related client (sub-module) type.

LDAP

LDAP is supported in TM as a user and group source as well as an authentication method. Selection of the LDAP for one or the other is done in manager settings view and its configuration parameters and test is done in the LDAP tab.

Once in the LDAP tap the following settings can be found:

  • Implementation – a drop down to choose the implementation type, with only AD option for now.
  • [Test] – button to open the LDAP Tester dialog, description of this dialog is provided in the next section.
  • A table with the following list of settings:
    • ldap.bindDN – name of the user account TM will use for connection to the LDAP. This is usually given in the form domain\logon).
  • ldap.bindPassword – password of the user account TM will use when connection to the LDAP.
    • ldap.connectTimeout – timeout for the LDAP connection, given in seconds. The value must be a positive integer number.
    • ldap.fullManagement – switch to allow (value = true) or disable (value = false) creation of users and groups within TM.
  • ldap.groupBaseDNs – one or more DNs of LDAP OUs where groups will be retrieved from/created in. The DNs must be separated by semi-colon. TM internally adds any sub-OUs of these and displays them on the Group Management page.
    • ldap.groupType – group type to be used when creating a group in the LDAP. The value defines the groupType attribute of the LDAP group item; it must be an integer number.
    • ldap.host – host name of the LDAP server, to be given in the form of ldap://hostname or ldaps://hostname.
    • ldap.maxConnections – maximum size of the LDAP connection pool maintained by TM. The value must be a positive integer number.
  • ldap.minConnections – minimum size of the LDAP connection pool maintained by TM. The value must be a positive integer number.
    • ldap.port – socket port number of the LDAP server. Usually 389 for LDAP and 636 for LDAPs. The value must be a positive integer number.
  • ldap.responseTimeout – timeout for a response to an LDAP request, in seconds. The value must be a positive integer number.
    • ldap.teneoGroupDN – DN of the LDAP group that all TM managed users and groups must be member of, it may be empty.
    • ldap.userAccountControl – user access control value to be used when creating a user in the LDAP. The value defines the userAccountControl attribute of the LDAP user item; it must be a positive integer number.
  • ldap.userBaseDNs – one or more DNs of LDAP OUs where users will be retrieved from/created in. The DNs must be separated by semi-colon. TM internally adds any sub-OUs of these and displays them on the User Management page.
    • ldap.userLogonSuffix – suffix to append to the user logon when creating a user in the LDAP. Usually given in the form @domain-name;

LDAP tester

The LDAP Tester sub-dialog is basically a dialog which admin user util to test and verify the correct settings for the LDAP connection. The first step is to list all the LDAP connection settings where admin can adjust values depending on the desired configuration. Once the values have been set, admin can click on “Fetch users & groups” thus the connection to the LDAP is verified if the correct list of users and groups is returned. If an error connecting or no entities are returned, the button [Ldap Settings] is used to go back to set them again. On the other hand, if settings are correct, [Apply settings] button is used to propagate the settings’ values to the main window ([Save and restart] button click is still needed to persist setting in TM).

Delegated

Delegated authentication is supported in TM as a user authentication method. Currently the only supported delegated authentication type is SAML2.

When opening the delegated tab the following options appear:

  • Implementation – a drop down to choose the implementation type, with only SAML2 option for now.

  • [Check] – button to check if values entered for Delegated (SAML2) are correct.

  • IdP Metadata – a drop down to choose the source of the IdP metadata, with the options SETTINGS and URL.

    • If SETTINGS option is selected, settings are read from the settings table which follows. It is also possible to import IdP metadata settings from a XML file with the button [Import IdP Metadata] as defined in SAML2 standard.
    • If URL option is selected, a new text box appear where the url to read the IdP metadata must be provided. IdP metadata will then be read on every user authentication.
  • SP Metadata – [Export SP Metadata] – button to export SP metadata as a XML file defined in SAML2 standard. Before it is created, settings are checked for errors.

  • A table with the following list of settings:

    • contacts.support.email_address – e.g. support@example.com
    • contacts.support.given_name – Support Contact
    • contacts.technical.email_address – e.g. technical@example.com
    • contacts.technical.given_name – Technical Contact
    • debug – Enable debug mode
    • idp.certfingerprint – an unformatted fingerprint. If it is provided, then the certFingerprintAlgorithm is required.
    • idp.certfingerprint_algorithm – possible values: sha1, sha256, sha384 or sha512
    • idp.entityid – identifier of the IdP entity (must be a URI)
    • idp.single_logout_service.binding – SAML2 protocol binding to be used when returning the message. Logout functionality not supported.
    • idp.single_logout_service.response.url – optional SLO Response endpoint info of the IdP. Logout functionality not supported.
    • idp.single_logout_service.url – SLO endpoint info of the IdP.
    • idp.single_sign_on_service.binding – SAML2 protocol binding to be used when returning the message.
    • idp.single_sign_on_service.url – SSO endpoint info of the IdP.
    • idp.x509cert – public x509 certificate of the IdP.
    • login_timeout – timeout for delegated login in seconds.
    • logon_prefix – prefix which is automatically removed from user logon during the delegated login.
    • logon_suffix – suffix which is automatically removed from user logon during the delegated login.
    • security.authnrequest_signed – 'true' or 'false' whether or not the samlp:AuthnRequest messages sent by this SP will be signed.
    • security.logoutrequest_signed – 'true' or 'false' whether or not the samlp:logoutRequest messages sent by this SP will be signed.
    • security.logoutresponse_signed – 'true' or 'false' whether or not the samlp:logoutResponse messages sent by this SP will be signed.
    • security.nameid_encrypted – 'true' or 'false' whether or not the nameID of the samlp:logoutRequest sent by this SP will be encrypted.
    • security.requested_authncontext – if empty no AuthContext will be sent in the AuthNRequest.
    • security.requested_authncontextcomparison – allows the authn comparison parameter to be set.
    • security.sign_metadata – 'true' or empty whether or not the Metadata of this SP requires to be signed.
    • security.signature_algorithm – algorithm that the toolkit will use on signing process. Options:
    • security.want_assertions_encrypted – 'true' or 'false' whether or not the Assertions received by this SP requires to be encrypted.
    • security.want_assertions_signed – 'true' or 'false' whether or not the saml:Assertion elements received by this SP requires to be signed.
    • security.want_messages_signed – 'true' or 'false' whether or not the samlp:Response, samlp:LogoutRequest and samlp:LogoutResponse elements received by this SP require to be signed.
    • security.want_nameid_encrypted – 'true' or 'false' whether or not the NameID received by this SP requires to be encrypted.
    • security.want_xml_validation – 'true' or 'false' whether or not the SP will validate all received xmls (In order to validate the xml, 'strict' and 'wantXMLValidation' must be true).
    • sp.assertion_consumer_service.binding – SAML2 protocol binding to be used when returning the message.
    • sp.assertion_consumer_service.url – specifies info about where and how the message must be returned to the requester. It must contain the full endpoint specification: hostname, port and '/teneo-manager/rest/oauth2/delegated/saml2'.
    • sp.entityid – identifier of the SP entity (must be a URI).
    • sp.nameidformat – specifies constraints on the name identifier to be used to represent the requested subject.
    • sp.privatekey – privateKey of the SP (Required format PKCS#8).
    • sp.single_logout_service.binding – SAML2 protocol binding to be used when returning the or sending the message.
    • sp.single_logout_service.url – specifies info about where and how the message must be returned to the requester.
      • sp.x509cert – x509cert of the SP.
      • strict – 'true' or 'false' whether or not the Java Toolkit will reject the messages if not strictly follow the SAML2 and unsigned or unencrypted messages, if it expects them signed or encrypted.

Delegated SAML2

TM and therefore Teneo Platform supports SAML2 SP Initiated login authentication. Logout is not supported yet, but it is planned to be in future releases. The easiest way to configure SAML2 is to exchange the SAML2 metadata files between SP (TM) and the IdP. They come with all the information needed to setup the connection. Once the IdP metadata file is acquired, it is just simple as upload it using the import SAML2 IdP metadata button in the Delegated tab. Metadata settings will then be verified and set to the settings table. Then, once the SP settings have been entered in the settings table, they just need to be exported using the SP metadata export button and delivered to the IdP admins to setup the connection on their side. In case the IdP metadata is dynamic, that is, changes on regular basis, another way of providing it is support. If URL option is selected in the IdP metadata drop-down, it will be read on every user login, making this use case fully supported.
Finally, to apply the settings admin needs to click on [Save and restart] button. Since the delegated login flow requires interacting with backend components from the users browser some additional configurations should be made at a platform deployment level for it to properly work [Refer to Installation Guide]. Then all should be configured and working. To test it, admin users just need to go to any platform component and check that the login method is actually delegated and working.

Rest API

TM REST API has been expanded to allow creation of entities through the API; API endpoints and specification are described in the page: Manager Server REST API Endpoints - Swagger. In order to call any endpoint, admin would need to obtain a valid admin access token. Admin access tokens can be obtained using the client credentials OAuth2 flow using the admin user as client_id and admin password as client_secret. They share the same expiration time as the normal access tokens.