User Management

Getting Started

Tasktop Cloud users will access user administration directly via the Tasktop UI and not in 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 in to Tasktop Integration Hub, you must log in to the User Administration Console to create your admin user(s). This can be accessed via the User Administration Console link at the bottom of the Tasktop login screen.

User Administration Console Link

After clicking the link, the Keycloak login screen will appear.

Keycloak Login Screen

The Tasktop User Administration Console comes pre-configured with a root user and password. You can use the following credentials to log in to Keycloak:

  • Username: root 
  • Password: Tasktop123

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

After logging in, you will be prompted to change your root password and you will need to make at least one new Tasktop Admin user for Tasktop. After this first user is created, you can create additional users directly from the Tasktop interface.

To create a Tasktop Admin, ensure the Tasktop realm is selected here:

Ensure 'Tasktop' is selected

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

Select the User section in the left column and click Add user

Click on 'Add user'

On this screen, enter the username, email, first name, and last name for your new user — the rest of the fields are not required. Once you've entered the required fields, click Save.

Add User Screen

After you have saved the user, select the Credentials tab and provide a temporary password for the new user.

(lightbulb) Tip: Please ensure the Temporary toggle is set to On. This will allow the user to set a new password upon their first log in. 

Once you have entered the temporary password, click Set 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, the user can add new users directly from the Tasktop Integration Hub interface.

Add User to TasktopAdmins Group

(lightbulb) Tip: You can ignore the Attributes, Role Mappings, Consents and Sessions tabs.

That's it! Your Tasktop Admin user has been added.

Now, you can sign out of the User Administration console, navigate to http://<server>:8080, and log in with your newly created user account.

Types of Users 

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

There are several types of users in Tasktop Hub:

  • Users: This user has all permissions needed to create, modify, and run integrations.
  • Admins: This user has the same permissions as a User and also includes the following permissions:
    • Create new users
    • Update users' passwords
    • Change users' group membership (from user to admin or vice-versa) 
  • Troubleshooting Users: This user can review Tasktop errors, logs, usage reports, and configurations, but cannot alter Tasktop integration configurations or user management.
    • (lightbulb) Note: Troubleshooting Users were added in Tasktop version 19.4, and may require additional steps if you'd like to update specific settings. For more information on configuring the Troubleshooting User role, please see the section below.
  • View Artifact Pair Details Users: This user can view artifact pair details. 
  • Delete Artifact Pair Users: This user can delete artifact pairs. 

(lightbulb) NoteAll users installing Hub after 21.1 will have the Artifact Pair user roles by default and will not need to follow any additional steps.

Best Practices

We recommend configuring at least two admin users — that way if one admin forgets their password, the other admin can log in and reset the other admin user's password. 

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

User Permissions

CapabilityAdminUserTroubleshooting UserView Artifact Pair UserDelete Artifact Pair User
Create New User(tick)(error)(error)(error)(error)
Reset Any User's Password(tick)(error)(error)(error)(error)
View and Modify Any User's Group Membership(tick)(error)(error)(error)(error)
Reset Own Password, Name, or E-mail(tick)(tick)(tick)(error)(error)
Create and Modify Repository Connections(tick)(tick)(error)(error)(error)
Create and Modify Models(tick)(tick)(error)(error)(error)
Create and Modify Collections(tick)(tick)(error)(error)(error)
Create, Modify, and Run Integrations(tick)(tick)(error)(error)(error)
Download Troubleshooting Reports (logs, usage reports, etc)(tick)(tick)(tick)(error)(error)
Change Logging Frequency(tick)(tick)(tick)(error)(error)
Review Errors & Configurations(tick)(tick)(tick)(error)(error)
Retry, Prioritize, and Recreate Errors(tick)(tick)(error)(error)(error)
View artifact pair details(error)(error)(error)(tick)(error)
Delete artifact pairs(error)(error)(error)(error)(tick)
Access to /api/v1/integrations/delete-integration-data public API(tick)(error)(error)(error)(error)
Access to /api/v1/integrations/delete-all-integration-data public API(tick)(error)(error)(error)(error)

Creating Additional Users

To create a user, select User Administration.

(lightbulb) Note: You must have admin capabilities to create an additional user.

Click User Administration

From the User Administration screen, select Add user.

Select 'Add User'

On the Add User screen, enter the username, email, first name, and last name for your new user — the rest of the fields are not required. Once you've entered the required fields, click Save.

New User Form

After you have saved the user, select the Credentials tab and provide a temporary password for the new user.

(lightbulb) Note: Please ensure the Temporary toggle is set to On. This will allow the user to set a new password upon their first log in. 

Once you have entered the temporary password, click Set Password.

New User - Credentials

Next, click the Groups tab and add the user to a group — based on the permissions you'd like the user to have.

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

New User - Groups

(lightbulb) Tip: You can ignore the Attributes, Role Mappings, Consents, and Sessions tabs.

That's it! Your user has been added and can log in with their temporary password.  

(warning) Note: Tasktop will not send the new user an email notification. The admin must notify the user of the new account and password.

Resetting a User's Password

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

(lightbulb) Note: You must have admin capabilities to reset a user's password.

Click 'User Administration'

Click View all users. Next, click on the ID for the user whose password you'd like to reset.

Click 'View all users'

Then, click the Credentials tab and provide a temporary password for the user.

(lightbulb) Note: Please ensure the Temporary toggle is set to On. This will allow the user to set a new password upon their first log in. 

Once you have entered the temporary password, click Set Password.

New User - Credentials

(warning) Note: Tasktop will not send the user an email 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 the members of a group, click Groups on the left side of the User Management screen.

(lightbulb) Note: You must have admin capabilities to view members of a group.

Click 'Groups'

Next, select the group you'd like to review, and click Edit.

Select Group and Click 'Edit'

To view the group's current members, click the Members tab.  

(lightbulb) Tip: A user can be a member of multiple groups.

Select 'Members' Tab

Adding or Removing Users From a Group

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

(lightbulb) Note: You must have admin capabilities to modify a user's group membership.

Click the Groups tab and select the group whose membership you'd like to modify. Then, use the leave and join buttons to modify their group membership.

There is no saving necessary here. Once you click leave and/or join, you will see a notification at the top of the screen informing you that your change has been made.

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

Update Group Membership

Modifying Your Own User 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.

(lightbulb) Tip: Both users and admins can modify their own account information.

Click 'My Account'

This will bring you to the Account Info screen, where you can update your name or email address.

Update Account Info

Click Password on the left sidebar to change your password.

Update Own Password

(lightbulb) Tip: The Sessions and Applications sections can be ignored.

Advanced User Management 

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

To access advanced user management capabilities, click the User Administration Console link at the bottom of the Tasktop Hub login 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, 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, click here.

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

Creating and Managing Root Users 

A root user refers to a user who can 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 

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


 For Upgrades to 19.4+

This section is only applicable when upgrading from versions earlier than Tasktop Integration Hub 19.4.

Creating the Troubleshooting User Role using a Script

To configure the troubleshooting user role, we provide a script that will create the TasktopTroubleshootingUser role in your Keycloak instance, and replace the default TasktopUsers group with the TasktopTroubleshootingUsers group.

(lightbulb) Note: 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. This 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 Add Role.

Add Role

On this screen, enter TasktopTroubleshootingUser in the Role Name field. Then, click Save.

(lightbulb) Tip: The Role Name is case-sensitive and must match exactly.

Create Troubleshooting User Role

That's it! The troubleshooting user role has been created. Next, you'll need to add the troubleshooting user to a group. 

Adding Troubleshooting Users to a Group

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 and click New.

Create New Group

On the Create Group screen, enter TasktopTroubleshootingUsers in the Name field. Then, click Save.

Create TasktopTroubleshootingUsers Group

After saving the group, the new group screen will appear.

Next, select the Role Mappings tab and add TasktopTroubleshootingUser to Assigned Roles. 

Add to Assigned Roles

After you have added the user to Assigned Roles, navigate back to the User Groups screen and select the Default Groups tab.

Next, remove any groups under Default Groups and add the TasktopTroubleshootingUsers group.

Update Default Groups

 For Fresh 19.4+ Installs

This section is only applicable to Tasktop Integration Hub version 19.4 and later.


Upon installation, new users will default to having the TasktopUser role. If you'd like to set the default to TasktopTroubleshootingUser, please 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 that will create the TasktopTroubleshootingUser role in your Keycloak instance, and replace the default TasktopUsers group with the TasktopTroubleshootingUsers group.

(lightbulb) Note: 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

Importing SSL Certificates

If you would like to connect to an LDAP server, you will need to import the SSL certificate into the keystore of your Tasktop product and restart it. To import the certificate to the keystore, see the following:  

  • Shut down your Tasktop instance (including Keycloak)
  • Obtain the certificate and certificate chain for your LDAP server. You may be able to do this using a command like the following on Linux
    • echo -n | openssl s_client -connect <ldap-server>:636 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > ldapserver.pem
  • In command prompt enter the following:
    • <path_to_jre>/bin/keytool -import -trustcacerts -keystore <path_to_keystore> -storepass <password> -alias ldap -import -file ldapserver.pem 
      • <path_to_jre> refers to the jre folder in the Tasktop install location.
      • <path-to-keystore> refers to the path to the truststore referenced here.
      • <password> is the password of your keystore or changeit if you are using the default
      • the keytool command should be run for each certificate exported. Each will need to have a unique alias.
    • the default password is: changeit
  • Start your Tasktop product.
  • Try again to connect to LDAP Server.

Accessing Keycloak Configuration Tool 

1. To access advanced user management capabilities, click the User Administration Console link at the bottom of the Tasktop Integration Hub login 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 left side panel.

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

 5. The LDAP configuration screen should now be displayed.

LDAP Configuration Screen

Configuring LDAP for Active Directory

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

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

Required Settings

(lightbulb) TipFollow the steps above to access the LDAP configuration page.

See the required settings below:

  • Console Display name: This is the name you'd like to give your connection.
  • Priority: If you have more than one User Federation configured, this setting specifies in which order to search each user federation service, 0 is first.
  • Edit Mode:
    • READ_ONLY: This setting reads the attributes from Active Directory (AD). It will not attempt to modify the AD service or store any local changes to user information.
    • WRITABLE: This setting 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 setting reads the attributes from AD and synchronizes 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.
    • (lightbulb) TipThe recommended mode is READ_ONLY.
  • 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.
  • Vendor: Specifies which vendor software to use for this LDAP configuration. If you are using something other than Active Directory, the attributes and locations may be different. This will also pre-fill some default values.


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

  • RDN LDAP attribute: The Relative Distinguished Name LDAP attribute 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 unique within a domain. The following options are a good base to use:
    • cn (canonical name): the full name (e.g., John Doe)
    • sAMAccountName: the username (e.g., john.doe)
    • mail: the email address (e.g., john.doe@demo.tasktop.com)

  • UUID LDAP attribute: The User Unique Identification attribute is a complicated long string of characters which uniquely identify a single object within AD. For unix based LDAP this is often uid. The default for Microsoft AD is objectGUID.

  • 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.

  • 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).

(lightbulb) Tip: 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.

  • Users DN: This is the Distinguished Name for the location where you can find your users. You can find 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 organization. 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 (any 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.

(lightbulb) Tip: Spaces are allowed in this string if they exist in your structure. 


  • Authentication Type: If using Microsoft Active Directory, you will be required to authenticate. Some non-Microsoft systems do not require authentication— if this is the case, select none.
  • Bind DN: This is the Distinguished Name for the user account which you will use to authenticate against your LDAP service 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 string 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. 

(lightbulb) Tip: Spaces are allowed in the string if they exist in your structure.

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

(lightbulb) Tip: Once you have entered the password, click Test authentication 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.

  • 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 (e.g., matching objects in a group)
    • Users in a specific group can use 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 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 (e.g., objectCategory=Person)

  • Search Scope: The Configuration of this depends on whether you have all of your AD users in a single OU, or if you'd like to search through the OU hierarchy structure. If searching, 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.

  • Use Trusted SPI: This is used if your environment uses SSL and a client certificate is required. This is not a default AD configuration.
  • Connection Pooling: This will allow connections to your AD server to remain open if set to ON, (for specific timeframe) rather than creating a new connection each time a user authenticates. 
  • Pagination: This allows you to page (or cache) information for active connections from your AD servers.
  • Mappers: Go to the Mappers tab at the top of the LDAP user federation you just created. Click Username. Ensure that LDAP Attribute is the same as what you entered in Username LDAP attribute here.
Kerberos

(warning) Note: Tasktop does not include instructions for Kerberos setup.

Sync Settings
  • Batch Size: Indicates how many accounts will process at once
  • 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.
  • 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, you should also enable this. Default is set to OFF.

(lightbulb) Tip: Save your configuration by clicking Save 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. If you are already logged in to Tasktop, you will first need to log out 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 log in, 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 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 can 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, use the following 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 the TasktopAdmins groups to the Default Groups list.

User Management and Security Constraints

Tasktop's 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 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 only contain 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 organization decides not to 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.

Additional information on configuring Tomcat authentication can be found here.


(lightbulb) 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.