ConfigHub - Security

Manage users

Please note that the guidance laid out below refers to two groups of users.

Those of you using versions of TrendMiner that include and fall after 2021.R3.1 and those of you using versions of TrendMiner that precede 2021. R3.1. Please follow the guidance that refers to the version group you are associated to. 

• Post 2021.R3.1
• Pre 2021.R3.1

Post 2021.R3.1 

TrendMiner Users 

TrendMiner users can either exist locally or via an external Identity Provider. An overview of all users can be found under the "Security" section in ConfigHub. 

The user overview shows the username, full name, email address and the identity provider. 

Specific users can be searched through via the top right search bar above the table. 

Creating users 

Only local users can be created via ConfigHub. In the case of an external Identity Provider (IdP), the users are synced instead and should be managed via the IdP. 

To create users you will need to go to the user-menu under the "security" section. From there users can be added via the "+add user"-button. 

Note: Usernames cannot be changed afterwards. 

Password policy 

When creating users locally, the password needs to adhere to the following rules: 

• Have a minimum length of 8 characters 
• Contain at least one uppercase character 
• Contain at least one lowercase character 
• Contain at least one digit 
• Contain at least one special character 
• Not have been recently used in the previous three passwords 

Configuring User details 

From the user overview an user can be clicked to see more detail in the side-panel. Here more options can be performed such as:

• Editing user details (local users only) 
• Change passwords (local users only) 
• Change roles (e.g. give users admin rights) 
• Unlock the user after the user consecutively failed to enter his password correctly. 
• Delete the user from TrendMiner (local users only). 

TrendMiner Groups 

Group management allows the creation of a collection of users and other groups (i.e. nested groups). An overview of all existing groups can be found under the "Security"-section in ConfigHub. 

The group overview shows the groupname and path of the groups so that it can be linked to its corresponding identity provider. 

Specific users can be searched through via the top right search bar above the table. 

## Creating Groups 

Creating Groups is only allowed on a local level. In case of an external provider the groups are managed and synced into TrendMiner from the IdP itself. 

It is possible to create local groups and assign users coming from LDAP or SAML or locally, to local groups and use access management to configure datasource access at group level.

To create a new group you will need to go to the groups-menu under the "security" section. From there groups can be added via the "+add group"-button. 

Note: A group can have only one parent group. 

Configuring Group details 

From the group overview a group can be clicked to see more detail in the side-panel. Here more options can be performed such as: 

Note: These actions can only be done for Local Groups. Groups synced from an external IdP are non-editable and should be managed from the IdP itself. 

• Edit the name of a group 
• Delete the group 
• Add existing users/groups as member to that group 

Warning-note: Deleting a group will also delete all subgroups. A model will be shown when this is the case. In case you want to keep the subgroups you will need to remove them first from the member list.  

Clients 

Creating Clients 

TrendMiner allows the creation of a client and secret in order to generate a token to be used in external API calls. 

To create a new client you will need to go to the clients-menu under the "security" section. From there clients can be created via the "+add client"-button. 

You will be asked to enter a name (client ID) for your client which will be used for external references. Once the client is created you can click on it to:

• Edit the client ID 
• Show the secret of the client 
• Generate a new secret 
• Delete the client 

Note: Regenerating a secret will invalidate your old secret and tokens. This action cannot be undone. 

Clients need to be added to a domain/entity in the Access management menu just as users/groups to allow access to the data. 

Fetch Token 

A token can be fetched via curl or any other means. An example is shown below.

Note: A new token needs to be fetched when the token expires after 5 minutes.

Template:

curl --request POST \ 
  --url 'https://YOUR_DOMAIN/oauth/token' \ 
  --header 'content-type: application/x-www-form-urlencoded' \ 
  --data grant_type=client_credentials \ 
  --data client_id=YOUR_CLIENT_ID \ 
  --data client_secret=YOUR_CLIENT_SECRET

Example:

curl --request POST \ 
    --url 'https://trendminer.example.net/auth/realms/trendminer/protocol/openid-connect/token' \ 
    --header 'content-type: application/x-www-form-urlencoded' \ 
    --data grant_type=client_credentials \ 
    --data client_id=external-client \ 
    --data client_secret=35c07824-5e11-40f5-88f0-0b578b940b43

Response token:

{ 
 "access_token":
"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJwcXZ1UXBpQkpiOGpRMVZQcU9PMDdFNDFCb25IRGxNZ01YY0NockZJbkhFIn0.eyJleHAiOjE2MzYwMjkzNDYsImlhdCI6MTYzNjAyOTA0NiwianRpIjoiMWQzNWUyNGQtMGQ4Zi00MWI1LThkYzgtZTYzZmIxZDk3MTEzIiwiaXNzIjoiaHR0cHM6Ly90bS1waXBlbGluZS1wbGVhc3VyZTMxLnRyZW5kbWluZXIubmV0L2F1dGgvcmVhbG1zL3RyZW5kbWluZXIiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiMTRlODRmODUtZjc5YS00YjIyLTg4MzktYWM5OWRkOWQzY2U1IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiZXh0ZXJuYWwtY2xpZW50IiwiYWNyIjoiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJkZWZhdWx0LXJvbGVzLXRyZW5kbWluZXIiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIiwidXNlciJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImV4dGVybmFsLWNsaWVudCI6eyJyb2xlcyI6WyJ1bWFfcHJvdGVjdGlvbiJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJlbWFpbCBwcm9maWxlIiwiY2xpZW50SWQiOiJleHRlcm5hbC1jbGllbnQiLCJjbGllbnRIb3N0IjoiMTAuMzIuMTM1LjE1IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJjcmVhdGVkRGF0ZSI6MTYzNjAyODY2NTMxMCwicm9sZXMiOlsiZGVmYXVsdC1yb2xlcy10cmVuZG1pbmVyIiwib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXSwicHJlZmVycmVkX3VzZXJuYW1lIjoic2VydmljZS1hY2NvdW50LWV4dGVybmFsLWNsaWVudCIsImNsaWVudEFkZHJlc3MiOiIxMC4zMi4xMzUuMTUifQ.GtGGgH7wqeqbEJuLfuGamps2nTqxHLDtz5plQ5IewZN6RTKnPTxh3oWlBshr_3lBVYaQHkjw0aXZc7K8dxfttXwQGQnxn6ijt_j2NFdqPVqlwODFWhwqGTtvTQXYESlghqz_8-k NHky9uFgd5lvZxdy6FGnOJcG6PmeeRa9lwZc_6hpwNGCEeH_9TKPM2WaiIs0f9sFoMlOSqOGZrqPrbxjzsCr0leVxptvLwSIw6RMOlDZ9IonBglpoL6mhpzTPtvZSGXQ-BL0Lcef2G_xY3A__etLM5U5bH44Ey-vwMGCYJ0ZWo7GsSPCOQYdwcGJOUoZ0Yvy0l2kNuazI1WC2g",
  "expires_in": 300, 
  "refresh_expires_in": 0, 
  "token_type": "Bearer", 
  "not-before-policy": 1571391000, 
  "scope": "email profile" 
}

Access Management 

The Access Management menu allows you to manage access permissions centrally per domain. Opening the menu returns an overview of all set access permissions. 

To create a new access permission, click the “Add entry” button situated at the top of the page and fill in the necessary details in the pop-up: 

• Domain: DATASOURCE or TIMESERIES_BUILDER 
• Entity:  
  • Using the DATASOURCE domain: Enter the name of the Historian Connection, as configured in TrendMiner or use "ALL" to indicate the collection of all Historian Connections). 
  • Using TIMESERIES_BUILDER domain: add the "MACHINELEARNINGMODEL" and/or "NOTEBOOK" Entity. 
• Members: Users, groups or clients you want to grant access permission for the domain 

To edit an existing access permission, click on the entry you want to edit and click “Edit” in the options menu. 

To remove an existing access permission, click on the entry you want to delete and click “Delete” in the options menu.  

# SSL 

To enable HTTPS, three things are required: 

• Private key 
• CSR for that private key 
• Certificate chain 

Generating a CSR is the responsibility of the customer. It's not feasible for TrendMiner to do this. 

The web server software (Apache) only supports PEM certificates. OpenSSL can be used to convert certificates in a different format to PEM. 

Once these prerequisites are fulfilled, HTTPS can be enabled via the "Options" menu on the top right. 

Note: Enabling HTTPS will temporarily render ConfigHub unusable until the service restart has completed. A manual refresh of ConfigHub is necessary. Press F5 to try to load the interface again. Retry until this succeeds. 

Note: Certificate chain: If the certificate is issued directly by the root CA, upload the root CA, otherwise upload the intermediate CA which signed the certificate. 

For a more detailed guide of what is, why and how to use SSL in TrendMiner, please look to this document.

Certificates 

If TrendMiner needs to communicate with SSL enabled services (Plant Integrations, LDAP, ...) that are using self signed certificates or certificates issued by an internal CA, it's not possible to verify the trust chain of these certificates.  

To be able to verify the trust chain please upload the root CA and optionally one or multiple intermediate CA certificates. The same is needed when using SAML with certificates issued by an internal CA. 

Identity Providers 

Everyone who needs to access TrendMiner software must be represented as a user in TrendMiner. The identity provider is the service that TrendMiner will use to verify access rights. 

By default, user management and authentication is performed by TrendMiner itself, i.e. “Local” identity provider. TrendMiner also supports authentication by an external identity provider. In this case, the credentials are managed and verified by the external IdP: when a user logs onto TrendMiner, the credentials are passed through to the IdP, which then verifies them and sends an access token to TrendMiner to grant access to this user. 

Multiple providers can be assigned to one TrendMiner installation. 

LDAP 

In version 2021.R3.1 only local users and SAML as IdP is supported. LDAP will be included in a future release. 

SAML 

More detailed documentation on how to configure TrendMiner with SAML can be found here. 

Admin Access 

Via Admin Access the password for the ConfigHub admin user can be changed. 

Pre 2021.R3.1 

Users

Manage users in TrendMiner

Create a new user by clicking the (+ Add user) label next to the title and filling in the fields for user details: username and password.

Note: Usernames cannot be changed afterwards.

Update an existing user by selecting the user in the table and clicking 'Edit' under the 'Options' menu. With the 'Delete' option the user account can be deleted. When a user is deleted his saved work remains available to other users. The user can be added again to get access again to his work.

Check the 'Administrator' checkbox in the panel to give a user access to the settings menus in the different TrendMiner applications.

Important: In case TrendMiner is configured to use an external Identity Provider (i.e. Active Directory or SAML), TrendMiner will sync user metadata from your external IdP to TrendMiner. When Active Directory is configured you will still have access to theis menu but not all user management functionality will be available. You can still manage which users should have 'administrator' permission in the TrendMiner application.  When SAML is configured to connect to your IdP, the complete user management will be disabled as it will be handled by your IdP.

Groups

Group management allows the creation of a collection of users and other groups (i.e. nested groups).

Important: In case TrendMiner is configured to use an external Identity Provider, you will not have access to this menu as you do not have to manually add groups.In case AD/LDAP is configured as the Identity Provider, TrendMiner supports reuse of the groups / group membership as configured in your AD/LDAP setup (see “Access Management”). In case SAML is used to connect to an Identity Provider, groups are not supported.

Create a new group by clicking the (+ Add group) icon next to the title and completing the group name.

Update an existing group by selecting the group in the table and clicking 'Edit' in the options menu. With the 'Delete' option the groups can be deleted.

Manage group-membership by selecting a group:

• Add a user or group as member to the selected group by typing his/her name (auto-complete suggestions are shown) and clicking “Add”.
• Remove a user or group as a member of the selected group by clicking the garbage bin icon.

Note: Membership changes are performed immediately, confirmation is not needed.

Access management

Manage access permissions centrally per domain.

Note: For now, only Historian Access permissions are supported.

To create a new access permission, click the “Add entry” button situated at the top of the page and fill in the necessary details in the pop-up:

• Entity: Name of the Historian Connection, as configured in TrendMiner.
  (Hint: you can use the keyword “ALL” to indicate the collection of all Historian Connections).
• Members: Users or groups you want to grant access permission for the Historian Connection of interest.

To edit an existing access permission, click on the entry you want to edit and click “Edit” in the options menu.

To remove an existing access permission, click on the entry you want to delete and click “Delete” in the options menu.

Note: When AD/LDAP is configured as the Identity Provider, you can also use the groups configured in your AD/LDAP setup for assigning access permissions to the configured Historian Connections. As such, when granting access permission for a given Historian Connection to an AD/LDAP group of interest, all AD/LDAP users that are a Member of this group will be granted access permission. This way, you can reuse the group membership as defined in your AD/LDAP for configuring the access permissions in TrendMiner.

SSL

To enable HTTPS, three things are required:

• Private key
• CSR for that private key
• Certificate chain

Generating a CSR is the responsibility of the customer. It's not feasible for TrendMiner to do this.

The web server software (Apache) only supports PEM certificates. OpenSSL can be used to convert certificates in a different format to PEM.

Once these prerequisites are fulfilled, HTTPS can be enabled via the "Options" menu on the top right.

Note: Enabling HTTPS will temporarily render ConfigHub unusable until the service restart has completed. A manual refresh of ConfigHub is necessary. Press F5 to try to load the interface again. Retry until this succeeds.

Note: Certificate chain: If the certificate is issued directly by the root CA, upload the root CA, otherwise upload the intermediate CA which signed the certificate.

Certificates

If TrendMiner needs to communicate with SSL enabled services (Plant Integrations, LDAP, ...) that are using self signed certificates or certificates issued by an internal CA, it's not possible to verify the trust chain of these certificates.

To be able to verify the trust chain please upload the root CA and optionally one or multiple intermediate CA certificates. The same is needed when using SAML with certificates issued by an internal CA.

Identity provider

Everyone who needs to access TrendMiner software must be represented as a user in TrendMiner Security. The identity provider is the service that TrendMiner will use to verify access rights.

By default, user management and authentication is performed by TrendMiner itself, i.e. “Local” identity provider. TrendMiner also supports authentication by an external identity provider. In this case, the credentials are managed and verified by the external IdP: when a user logs onto TrendMiner, the credentials are passed through to the IdP, which then verifies them and sends an access token to TrendMiner to grant access to this user.

Active Directory / LDAP

TrendMiner supports switching to authentication by Active Directory/LDAP. When TrendMiner is configured to use AD/LDAP authentication, the credentials are managed and verified by Active Directory. When a user logs onto TrendMiner, the credentials are passed through to the Active Directory, which on verification of the credentials sends an access token to TrendMiner, to grant access to the user. In this scenario, TrendMiner will sync user metadata from the Active Directory to TrendMiner Security. You do not have to add users manually.

Configuration

To configure AD/LDAP you need to complete a few steps.

Backup

When switching from local to AD/LDAP authentication, TrendMiner will configure the various components for this new authentication method. After the configuration and initial mapping is complete, you will not be able to change the authentication method back to Local. TrendMiner user-accounts which have not been mapped to an AD/LDAP-account will be deleted. Mapped users will no longer be editable in ConfigHub, with the exception of the admin flag, which means it is still possible to give a TrendMiner user admin rights or take away his admin rights when the AD/LDAP is active.

We highly recommend you to take a backup in case of issues during the switch, we can support you in reverting to the application state at the moment of the backup.

Self-signed certificates

More info on self-signed certificates can be found under the 'Certificates' menu.

Connect to AD/LDAP

The following attributes have to be configured to allow successful integration with AD/LDAP:

• Provider URL: The hostname of the LDAP server, including the protocol ldap://
• Manager DN: The user that lists the users that will receive access to TrendMiner, must have query permissions on this server. It can be specified by full DN or by domain\user notation. Typically a ‘service’ account with a password that does not expire is used.
• Manager password: Password of the user.
• User base DN: The DN of the starting point of tree walking for users. All users must be descendants of this node.
• Search filter: Filter to restrict the users that are permitted to access TrendMiner eg. objectCategory=Person will select all users.
• Group base DN: The DN of the starting point of tree walking for groups.

Note: Groups can be used for permission management in TrendMiner. This does not influence which users are allowed access.

• Username attribute mapping: The name of the attribute that represents the username of the user.
• First name attribute mapping: This attribute points to the user's first name.
• Last name attribute mapping: This attribute points to the user's surname or last name.
• E-Mail attribute mapping: Mail address of the user.
• Retrieve groups hierarchically: Enable to descend the tree for groups starting at the Group base DN.

Click “Test Connection” to verify that the supplied attributes result in a successful connection to your AD/LDAP server.

Click “Save” to save the changes to your configuration.

You can click on 'User' menu to see the list of users granted access to TrendMiner. The 'group' menu will be grayed out.

Note: We highly recommend that you create a separate AD/LDAP-group for TrendMiner users such that only the users that you really want to grant access to TrendMiner are being synced to TrendMiner.

Map users

To support the switching from local IDP to AD/LDAP authentication, a migration wizard is provided for the initial mapping of the existing TrendMiner user accounts. This is to ensure that the current user settings and saved work are still accessible after the switch.

All existing TrendMiner user-accounts are listed on the left. You can map to an AD/LDAP-account to each of these user-accounts, which is allowed access to TrendMiner based on the AD/LDAP configuration in Step1. The selected AD/LDAP-account will then “inherit” the user’s settings, and saved work of the original TrendMiner user-account.

Note: After finishing this step, users must use their AD/LDAP-credentials to access the TrendMiner application.

SAML

Note: Configuring SAML requires at least basic knowledge and access to the right internal resources (IT department or service provider) to generate the required files.

TrendMiner also supports the switch to authentication by an external identity provider over SAML 2.0 (reference 1). When TrendMiner is configured to use authentication over SAML, credentials are managed and verified by the SAML Identity Provider (IdP). In this scenario, TrendMiner will sync user metadata from the SAML IdP to TrendMiner Security. You do not have to manually configure users.

If SAML is active you can no longer edit users in TrendMiner. The TrendMiner security API can be used to assign the admin role to users.

Note: Groups are currently not supported in combination with SAML.

Note: Although TrendMiner will sync user metadata from the SAML IdP, it does not do this pro-actively. A user needs to log in to TrendMiner before his username will appear in the user tab and this user can be assigned to specific ACL's. 

Note: Enabling SAML authentication might impact the usage of TrendMiner scripts as APIs will no longer work using basic authentication. This can be circumvented by using session cookies, but these will auto-expire every 12 hours. Like batch indexing as these scripts use a cookie, which expires after 12 hours, to authenticate.

To configure SAML you need to complete a few steps.

Backup

When switching from local IdP to SAML IdP, TrendMiner will configure the various components for this new authentication method. After the configuration and initial mapping is complete, you will not be able to change the authentication method back to Local.

TrendMiner user-accounts which have not been mapped to an external-account will be deleted.

We advise you to take a back-up in case of issues that may arise during the switch, we can support you in reverting to the application state at the moment of the backup.

Self-signed certificates

If your Identity Provider uses self-signed certificates please make sure you upload them before activating SAML. Not providing these certificates might render your TrendMiner unusable and require restoring an older backup.

Click on the "here" link to open the ConfigHub certificates menu where you can upload your self-signed certificates.

Choose certificate file and click on 'Upload Certificate'. Upload all the certificates needed to establish trust from the root CA to the certificate used by the IdP.

Signing key

If the IdP administrators have chosen to configure their IDP very strictly, and they prefer the use of a certificate/key pair issued by them instead of the one auto-generated by TrendMiner, they can be imported in the next optional step.

Configuration

The following attributes have to be configured to enable successful integration with an external SAML Identity Provider:

• Entity Base url: The entity base URL defines the access point of the TrendMiner security application, i.e. <TrendMiner domain>/security.

Note: From this URL two properties are derived, which should be configured in your IdP: the entity id, which is an identifier for the TrendMiner service provider: {entityBaseUrl}/saml/metadata and the Single Sign-On URL, which defines the entry point for redirecting after a successful login.

• Identity provider metadata: Upload an XML file containing your SAML IdP's metadata. Your IdP’s documentation will guide you to provide metadata to a service provider. It will instruct you to download a metadata file, or it will display XML code that you can copy and paste into a new text file and save with an .xml extension.

Note: In case an AuthnStatements is included in the SAML response from the IdP, an audience restriction should be included in the response as well, as required by the SAML library which is used by TrendMiner (https://projects.spring.io/spring-security-saml/).

Click “Next step” to save the changes to your configuration and continue.

Map users

To support the switch from local to authentication over SAML, a migration wizard is provided for the initial mapping of the existing TrendMiner user-accounts. This is to ensure that the current user’s settings and saved work are still accessible after the switch.

All existing TrendMiner user-accounts are listed on the left. You can map each of these user-accounts to an external-account, which is allowed access to TrendMiner based on the SAML configuration in Step 1. The entered external-account will then “inherit” the user’s settings, and saved work of the original TrendMiner user-account.

Note: After finishing this step, users must use their SAML IdP-credentials to access the TrendMiner application.

Note: When SAML is active, user accounts in TrendMiner are only created when they first log in. As a result you cannot add users to ACLs until they have actually logged in.

Admin access

To change the Administrator password of ConfigHub, navigate to the security menu and click ‘Admin access’. Enter the new password twice and click ‘Change password’.

References

1. Tested with Okta SAML Identity Provider and Active Directory Federation Services (ADFS).