User Management

Getting Started

Note: Tasktop Cloud users will access user administration directly via the Tasktop UI and not via the external User Administration Console.  

Once installation is complete, you can begin using Tasktop Integration Hub by opening http://localhost:8080/ or https://localhost:8443 in any of our supported browsers.  

Before logging on to Tasktop, you must log into the User Administration Console in order to create your admin user(s).  The Tasktop User Administration Console can be accessed via the 'User Administration Console' link, at the bottom of the Tasktop Integration Hub sign-in page.

User Administration Console Link

This will lead you to the Keycloak log-in screen:

Keycloak Log in Screen

The Tasktop User Administration Console comes pre-configured with a root user.  Use those credentials to log into Keycloak.

Username: root

Password: Tasktop123

You will be prompted to change your root password.

(warning) WARNING: There is only one initial root user. If the credentials for this user are lost, access to the advanced User Management features will be lost. All functionality of Tasktop Integration Hub, however, will continue uninterrupted.  You can learn how to create additional root users and manage existing root users here.

After logging in, you will need to make at least ONE new Tasktop Admin user for Tasktop Integration Hub.  After this first user is created, you can create additional users directly from the Tasktop Integration Hub interface.

To create a Tasktop Admin, ensure the "Tasktop" realm is selected in the upper left:

Ensure 'Tasktop' is selected

(warning) Note: Do not re-name the realm ('Tasktop'), as this will result in errors upon Tasktop log-in.  If you must re-name it, please also edit {tasktop workspace}/webapps/ROOT/WEB-INF/keycloak.json, change the “realm” parameter, then restart Tasktop.

Select the 'User' section in the left column and click on the 'Add user' button on the upper right. 

Click on 'Add user'

On the Add User screen, populate the Username, E-mail, First Name, and Last Name sections. The rest of the sections can be ignored.

Add User Screen

After clicking 'Save', select the 'Credentials' tab and give the user a temporary password. Make sure 'temporary' is set to 'on'. This will allow them to set a new password upon their first log-in. Then click 'Reset Password'.

Credentials Tab

Next, select the 'Groups' tab to assign the user as a Tasktop Admin. Highlight 'TasktopAdmins' and click 'Join'. By becoming a Tasktop Admin, this user will be able to add new users directly from the Tasktop Integration Hub interface.

Add User to TasktopAdmins Group

Ignore the Attributes, Role Mappings, Consents and Sessions tabs.

Your Tasktop Admin user has been added.

Now, sign out of the User Administration console and go to http://<server>:8080. You will be able to log in with the user account you just created. Once the admin user has been created, you generally will not need to log into the User Administration Console.

Types of Users 

Note: Available user types vary by Tasktop Edition.  See Tasktop Editions table to determine if your edition contains this functionality.

There are three types of users: Admins, Users, and Troubleshooting Users.

(lightbulb) Troubleshooting users were added in Tasktop version 19.4, and require some additional configuration.  For details on how to set up the Troubleshooting User role, see below.

The only differences between Admins and Users are regarding user management.  An admin can create new users, update users' passwords, and change users' group membership (from user to admin or vice-versa).  A user cannot.  Both user types have the same permissions with regard to Tasktop functionality (meaning that both have all permissions needed to create, modify, and run integrations).

The Troubleshooting User can review Tasktop errors, logs, usage reports, and configurations, but cannot alter Tasktop integration configurations or user management.

(lightbulb) We recommend configuring at least two admin users.  This way, if one admin forgets their password, the other admin will be able to log in and re-set the other admin user's password.

We also recommend changing the default password of the Advanced User Administration console.  Please see the Getting Started section above for information on how to reset passwords.

CapabilityAdminUserTroubleshooting User
Create New User(tick)(error)(error)
Reset Any User's Password(tick)(error)(error)
View and Modify Any User's Group Membership(tick)(error)(error)
Reset Own Password, Name, or E-mail(tick)(tick)(tick)
Create and Modify Repository Connections(tick)(tick)(error)
Create and Modify Models(tick)(tick)(error)
Create and Modify Collections(tick)(tick)(error)
Create, Modify, and Run Integrations(tick)(tick)(error)
Download Troubleshooting Reports (logs, usage reports, etc)(tick)(tick)(tick)
Change Logging Frequency(tick)(tick)(tick)
Review Errors & Configurations(tick)(tick)(tick)
Retry, Prioritize, and Recreate Errors(tick)(tick)(error)

Creating Additional Users

To create an additional user, you must have admin capabilities.  To create a user, select 'User Administration' from the upper right corner of the application.

Click User Administration


From the User Administration screen, select 'Add user'

Select 'Add User'

On the Add User screen, populate the Username, Email, First Name, and Last Name sections.  The rest of the sections can be ignored.

New User Form

Click the 'Credentials' tab and give the user a temporary password.  Make sure 'temporary' is set to 'on'.  This will allow them to set a new password upon their first log-in.  Then click 'Reset Password.'

New User - Credentials

Click on the 'Groups' tab. Add the user to a group - either TasktopUsers, TasktopTroubleshootingUsers or TasktopAdmins, depending on the permissions you'd like the user to have.

(warning) If the new user is not added to a group, they will not be able to successfully access Tasktop Integration Hub.

New User - Groups

You can ignore the following tabs: Attributes, Role Mappings, Consents, and Sessions.

Your user has been added, and can log in with their temporary password.  

(warning) Note that Tasktop will not send the new user an e-mail notification.  The admin must notify the user of the new account and password.

Resetting a User's Password

To reset a user's password, you must have admin capabilities.

To reset a user's password, select 'User Administration' from the upper right corner of the application.

Click 'User Administration'

Click 'View all Users.'

Click 'View all users'

Click on the ID for the user whose password you would like to reset.  Then, click on the 'Credentials' tab and give the user a new temporary password.  Make sure 'temporary' is set to 'on'.  This will allow them to set a new password upon their first log-in.  Then click 'Reset Password.'

New User - Credentials


(warning) Note that Tasktop will not send the user an e-mail notification.  The admin must notify the user of the new temporary password.  The user will be prompted to set a new password upon their next log-in.

Managing Groups

Viewing Members of a Group

To view members of a group, you must have admin capabilities.

To view the members of a group, click 'Groups' on the left pane of the User Management screen.

Click 'Groups'

Select the group you'd like to review, and click 'edit.'  

Select Group and Click 'Edit'

Click the 'Members' tab to view current members.  

(lightbulb) Remember that a user can be a member of multiple groups.

Select 'Members' Tab

Adding or Removing Users From a Group

To modify a user's group membership, you must have admin capabilities.

Select 'Users' from the left pane of the User Administration screen.  Click 'View all Users' and select the ID of the user you would like to modify.

Click on the 'Groups' tab, select the group whose membership you'd like to modify, and use the 'leave' and 'join' buttons to modify their group membership.  There is no saving necessary here; once you click the 'leave' and/or 'join' button, you will see a notification at the top of the screen letting you know that your change has been made.

(warning) Note that a user must be a member of at least one group in order to be able to log into Tasktop successfully.

Update Group Membership

Modifying Your Own User Information 

Both Users and Admins can modify their own account information.  To change your own password or other user information, click your username at the upper right corner of the screen, and select 'My Account.'

Click 'My Account'

This will bring you to the Account Info screen, where you can update your name or e-mail address:

Update Account Info

You can also click 'Password' on the left sidebar in order to change your password:

Update Own Password

The 'Sessions' and 'Applications' sections can be ignored.

Advanced User Management 

Tasktop Integration Hub has some advanced user management capabilities not accessible via the Tasktop Integration Hub interface.

To access advanced user management capabilities, please click the 'User Administration Console' link at the bottom of the Tasktop Integration Hub sign-in screen.

User Administration Console Link


You can log in using the credentials you set when you first installed and began using Tasktop.

(warning) WARNING: there is only one initial root user. If the credentials for this user are lost, access to the advanced User Management features will be lost. All functionality of Tasktop Integration Hub, however, will continue uninterrupted.

Some of the advanced features include:

  • User Federation Configuration for:
    • LDAP
    • Kerberos
  • Identity Provider login for:
    • SAML v2.0
    • OpenID Connect v1.0
  • Enforcing custom password policies such as:
    • Set password expiration
    • Require special characters
    • Setting minimum password length

(warning) Note: While Tasktop officially supports LDAP, other advanced features (including but not limited to Kerberos Federation and IDP) are not supported or tested by Tasktop.

To learn more about these advanced features, see http://www.keycloak.org/documentation.html.

(warning) WARNING: Do not make changes or updates to the Roles or Groups section. Altering these settings may prevent your Tasktop Integration Hub users from accessing the tool.

Creating and Managing Root Users 

A 'root user' refers to a user who is able to log in to the User Administration Console.  Tasktop comes with one root user, but if you'd like to create additional root users or to manage existing users, you can do so from the User Administration Console.

Once logged in, click the arrow next to 'Tasktop' (in the upper left panel), and select 'Master'

Select 'Master'

Next click 'Users' in the left panel.  From here, you can follow the same instructions used to create Tasktop users to create and manage root users (ignoring the 'Groups' section).

Configuring the Troubleshooting User 

Note: Availability of the Troubleshooting user varies by Tasktop Edition.  See Tasktop Editions table to determine if your edition contains this functionality. 

Details on the Troubleshooting user can be found here.

For Upgrades to 19.4+

Creating the Troubleshooting User Role using a Script

To configure the troubleshooting user role, we provide a script will create the TasktopTroubleshootingUser role in your Keycloak instance, and replace the default TasktopUsers group with the TasktopTroubleshootingUsers group. Please note that this script can only be used if you have provided a valid SSL certificate as described in the SSL Certificate Installation section. If you have not provided such a certificate, skip to the “Creating the troubleshooting user role via the Keycloak admin console” section below.

Windows

Run the add-troubleshooting-user.bat script in C:\Program Files\Tasktop\utility-scripts, providing the relevant information when prompted.

Linux

Run the add-troubleshooting-user.sh script in <installation location>/Tasktop/utility-scripts, providing the relevant information when prompted.

Creating the Troubleshooting User Role via the Keycloak Admin Console

If you have not provided a valid SSL certificate, you can create a troubleshooting user via the User Administration Console. The console can be accessed by following the instructions in the Getting Started section. After logging in, navigate to the ‘Roles’ section in the left column and click on the 'Add Role’ button on the upper right.

Add Role

On the Add Role screen, populate the Role Name section with “TasktopTroubleshootingUser”. Note that the name must match exactly. Then click ‘Save’.

Create Troubleshooting User Role

The troubleshooting user role has been created. 

We recommend that you create a group for troubleshooting users and set it as the default group. To do this, navigate to the ‘Groups’ section in the left column. On the User Groups page, click on the 'New’ button on the upper right.

Create New Group

On the Create Group screen, populate the Name section with “TasktopTroubleshootingUsers”. Then click ‘Save’.

Create TasktopTroubleshootingUsers Group


You should be presented with this screen. Select the ‘Role Mappings’ tab and add “TasktopTroubleshootingUser” to Assigned Roles. 

Add to Assigned Roles

Navigate back to the User Groups page and select the ‘Default Groups’ tab. Remove any groups under ‘Default Groups’ and add “TasktopTroubleshootingUsers”.

Update Default Groups


For Fresh 19.4+ Installs

Upon installation, new users created will default to having the ‘TasktopUser’ role. If you'd like to set the default as the ‘TasktopTroubleshootingUser’ role instead, you may follow either set of instructions below.

Setting the Default Troubleshooting User Group Using a Script

To configure the troubleshooting user role, we provide a script will create the TasktopTroubleshootingUser role in your Keycloak instance, and replace the default TasktopUsers group with the TasktopTroubleshootingUsers group. Please note that this script can only be used if you have provided a valid SSL certificate as described in the SSL Certificate Installation section. If you have not provided such a certificate, skip to the “Creating the troubleshooting user role via the Keycloak admin console” section below.

Windows

Run the add-troubleshooting-user.bat script in C:\Program Files\Tasktop\utility-scripts, providing the relevant information when prompted.

Linux

Run the add-troubleshooting-user.sh script in <installation location>/Tasktop/utility-scripts, providing the relevant information when prompted.

Setting the Default Troubleshooting User Group via the Keycloak Admin Console

If you have not provided a valid SSL certificate, you can set the troubleshooting user group as the default via the User Administration Console. The console can be accessed by following the instructions in the Getting Started section.  

After logging in, navigate to the ‘Groups’ section in the left column.

Navigate to 'Groups'

Select the ‘Default Groups’ tab. Remove any groups under ‘Default Groups’ and add “TasktopTroubleshootingUsers”.

Update Default Groups

Configuring LDAP User Management

Required Directory Information

Before configuring LDAP, please check you have the following required pieces of information available for your specific Active Directory (AD) domain.

  • The fully qualified domain name (FQDN) for the AD service,
    • example: 'demo.tasktop.com'
  • An AD user account and credentials; The user will need read / view access to Users, Groups and Organizational Units (OU). We suggest a specific restricted account be setup in AD for this purpose.
    • example: 'service_tasktop'
  • An AD user group; The group(s) will be used to store specific users, who will have access to Tasktop.
    • example: 'Tasktop Users'
  • A tool such as ADSIEdit, which is able to give your the specific information about the structure of your AD domain setup.
    • ADSIEdit is part of Microsoft Windows Remote Server Administration Toolset (RSAT). This can be downloaded from Microsoft RSAT page, or enabled on a server by adding the RSAT feature.
    • Alternatively ask your Domain Administrators for all of the following information:
      • CN/DN for Tasktop User (mentioned above)
      • CN/DN for the Tasktop User Group (mentioned above)
      • User, mail; username and name attributes (the specific name for each attribute)
      • OU root for all users
      • LDAP FQDN server URL

Accessing Keycloak Configuration Tool

1. To access advanced user management capabilities, please click the 'User Administration Console' link at the bottom of the Tasktop Integration Hub sign-in screen.

'User Administration Console' Link

2. Log in using the default credentials listed in the  Getting Started section above.

3. Select the 'User Federation' link from the side-menu

4. Choose the 'ldap' option from the dropdown for 'Add provider ...'

You are now on the LDAP configuration screen.

Configuring LDAP for Active Directory

This section will guide you through creating a connection to an LDAP authentication server.

(lightbulb) Note that images provided are only a sample of settings; please ensure that you enter information specific for your environment.

Required Settings

1. Follow steps above to access the LDAP configuration page.

2. Console Display name: This is any label you would like to give your connection.


3. Priority: If you have more than a single User Federation configured, the priority specifies which order to search each user federation service, 0 is first.

4. Edit Mode:

  • READ_ONLY: This will read the attributes from Active Directory. It will not attempt to modify the AD service or store any local changes to user information.
  • WRITABLE: This may enable some changes to be written back to AD. The user account communication with AD will need access to modify the specific objects attribute
  • UNSYNCED: This will read the attributes from AD and synchronise them to a local store in the internal Keycloak database. Users and Administrators can make changes to the user objects, but those changes will only be stored for the local Tasktop instance. This will not write back to Active Directory. 

The recommend mode is READ_ONLY.

5. Sync registrations: If a new user is created in Tasktop, this will allow that user to also be created in AD, if you have WRITABLE selected and access to create user objects in the AD domain. The default setting is 'OFF'.

6. Vendor: Specify which vendor software to use for this LDAP configuration. If you are using something other than Active Directory, then the attributes and locations may be different. This will also pre-fill some default values.


7. Username LDAP attribute: This should be the default username attribute as specified in your domain. The default for Microsoft AD is 'sAMAccountName'.

8. RDN LDAP attribute: This is the Relative Distinguished Name LDAP attribute. This is a list of attributes which will be searched when a user attempts to authenticate to Tasktop. The attributes listed here should be unique within an OU level or better-yet unique within a domain. The following options are a good base to use:

  • cn (canonical name), also known as the full name; example "John Doe"
  • sAMAccountName, also known as the username; example john.doe
  • mail, also known as email-address; example john.doe@demo.tasktop.com

9. UUID LDAP attribute: This is the User Unique IDentification attribute.  It is a complicated long string of characters which will always uniquely identify a single object within AD. For unix based LDAP this is often 'uid'. The default for Microsoft AD is 'objectGUID'.

10. User Object Classes: These are the 'types' of objects which can be used to authentication against. You can specify more if your organization has other specific identifiers such as 'staff' or 'contractor'. The default for Microsoft AD is: person, organizationalPerson, user.

11. Connection URL: This is the specific string which should be the FQDN of your LDAP service. It's default format for AD will be 'ldap://demo.tasktop.com'. If you have SSL configured then you can also use ldaps://demo.tasktop.com (SSL is not enabled by default in Microsoft AD).

At this point, we recommend selecting the 'Test connection'  button to check that Tasktop is able to communicate with your LDAP server. You should see a green message at the top of your screen indicating a successful connection to your LDAP server .

12. Users DN: This is the Distinguished Name for the location where you can find your users. You can find out the Users DN (and any other Distinguished Names via the ADSIEdit tool in Windows. Once the tool is open, you will need to connect to the AD domain for your company. Once connected, the domain will be presented in a tree-view on the left, where you can drill down to the specific branches until you find the specific OU or User object you want details for.  We recommend using this utility as it will allow you to copy/paste the specific DN information directly (as typing mistakes will result in error when testing).

The format for this string will be a number of 'OU=' followed by a number of 'DC=' separated by a comma. Spaces are allowed in this string if they exist in your structure. 

example: OU=Users,OU=Tasktop,DC=demo,DC=tasktop,DC=com


13. Authentication Type: If you are are using Microsoft Active Directory, you will be required to authenticate. Some non-Microsoft systems do not require authentication.  If that is the cause for your LDAP, then select 'none'

14. Bind DN: This is the Distinguished Name for the user account which you will use to authenticate against your LDAP service in order to allow Tasktop to authenticate users. The Bind DN user account can be anywhere within the AD domain, however we suggest that you have a dedicated account specifically for Tasktop. The format for this sting will be a singular 'CN=' for the Canonical Name of the user account, followed by possible 'OU=' which is followed by the 'DC=' items all separated by a comma. Spaces are allowed in this string if they exist in your structure

example: CN=service_tasktophub,OU=Service Accounts,OU=Tasktop Infrastructure,DC=demo,DC=tasktop,DC=com



15. Bind Credential: This the password for the user account configured in the Bind DN.

Once you have entered the password, press the 'Test authentication' button to confirm that Tasktop is successful in authenticating itself against your Active Directory domain. You should see a green message at the top of your page as an indication of a successful authentication .

16. LDAP Filter: This is where you will configure a filter to specify which user accounts will have access to authenticate in Tasktop. If you leave this blank, all users within your 'Users DN' OU in the AD environment will have access. The structure of the string is as follows:

  • () : braces to start and finish
  • Either
    • &() : for performing an 'AND' operation (i.e. all items must match)
    • |() : for performing an 'OR' operation (i.e. where any items can match)
  • Specific attribute related condition, for examples matching objects in a group
  • Users in a specific group you can user "memberOf=" => 
    • memberOf=CN=Tasktop Hub Users,OU=Resource Groups,OU=Groups,OU=Tasktop,DC=demo,DC=tasktop,DC=com
  • Users and (nested) Groups in a specific group, you specifically require "memberOf:1.2.840.113556.1.4.1941:="
    • memberOf:1.2.840.113556.1.4.1941:=CN=Tasktop Hub Users,OU=Resource Groups,OU=Groups,OU=Tasktop,DC=demo,DC=tasktop,DC=com
  • You can also specify that a particulate attribute is equal to some value, example
    • objectCategory=Person

17. Search Scope: The Configuration of this depends on whether you have all of your AD users in a single OU, or if you would like to search through the OU hierarchy structure. If searching, then the Users DN field configured above will need to be the root or lowest-level OU.

  • If all users are in a single OU, set this to 'One Level'
  • If users are hierarchically organized in OUs, set this to 'Subtree'

18. Use Trusted SPI: This is used if your environment uses SSL and a client certificate is required. This is not a default AD configuration.

19. Connection Pooling: This will allow connections to your AD server to remain open if set to 'ON' ,(for specific timeframe) rather then creating a new connection each time a user authentications. 

20. Pagination: This allows you to page (or cache) information for active connections from your AD servers.

21. Mappers: Go to the 'Mappers' tab at the top of the LDAP user federation you just created.  Click on "username."  Ensure that "LDAP Attribute" is the same as what you entered in "Username LDAP attribute" in step 7.

Kerberos

Kerberos setup is not shown in this guide.

Sync Settings
  1. Batch Size: Indicates how many accounts will process at once
  2. Periodic Full Sync: Allows for a sync of all users to occur between Tasktop and Active Directory. If you have a large number of users constantly authenticating into Tasktop, it may be useful to enable this. Default is set to OFF.
  3. Periodic Changed Users Sync: Allows for newly created or updated users to be synced from Active Directory to Tasktop. If you have the Periodic Full Sync enabled, then you should also enable this. Default is set to OFF.

Save your configuration using the save button at the bottom of the page. A green message at the top will indicate that your save was successful.  

Additional LDAP Information

Testing

(lightbulb) Note: The configuration utility for LDAP requires its own internal authentication.  As such, when you test account access, it is recommended that you use a separate browser or select a 'private' or 'incognito' browser mode. If you are already logged into Tasktop, you will first need to logout before testing.

  1. Direct your browser to the default web address of your Tasktop server, such as https://demo.tasktop.com/
  2. Enter credentials which should be allowed access to authenticate from the LDAP connection you have just setup
  3. Retry with a set of credentials which should not have access to Tasktop. If you are able to login then check the 'filter' settings again.
Default User Access

By default, all LDAP users will be granted 'user' level access to Tasktop.   If you have configured the troubleshooting user functionality (by either running the script or performing manual configuration through the admin console), LDAP users will by default be granted 'troubleshooting user’ level access instead.  If desired, you will be able to set all new accounts, including LDAP user accounts, to default into a specific group. You can also assign different 'members' to either of the TasktopUsers or TasktopAdmins groups.

To change the default group, follow these instructions:

  1. Select 'Groups' (under the 'manage' section) of the right-side bar menu
  2. Select the 'Default Groups' tab
  3. Add or Remove the TasktopUsers and / or TasktopAdmins groups to the Default Groups list.

User Management and Security Constraints

Tasktop with User Management uses Security Constraints as described in the Java Servlet Specification to limit access to authenticated users. Adding additional Security Constraints to the Apache Tomcat configuration can interfere with the Security Constraints provided by Tasktop and enable unauthenticated users to access Tasktop.

DNS Settings

The server Tasktop in installed on must be able to resolve the hostname clients will use to access it. This can be accomplished through the DNS configuration. A less preferred option is to configure using the server's hosts file.

The hostname clients use to access Tasktop must be a valid hostname according to RFC 952. This means it may contain only letters, digits, hyphens, and periods, and may not contain underscores.

Alternative User Management

By default, Tasktop comes with a user management solution.  In the rare scenario where your company has decided to not use Tasktop's provided user management solution and you still need to ensure that only authorized users are able to access your Tasktop instance, you can set up Basic Authentication for the Tomcat web server.

Instructions for configuring Tomcat authentication can be found herehttp://www.avajava.com/tutorials/lessons/how-do-i-use-basic-authentication-with-tomcat.html.


Please note, using this style of user management will mean that all of your users will have the exact same permissions within Tasktop. There will be no separate roles or permissions within the application.