User Sync Tool

Introduction

The LoginTC User Sync Tool allows you to perform a one-way synchronization of your users from your LDAP-speaking user directory (e.g. Active Directory, OpenLDAP, OpenDJ) to LoginTC Admin.

Business or Enterprise subscription required

See the Pricing page for more information about subscription options.

Prerequisites

Before proceeding, please ensure you have the following:

  • A LoginTC Admin account
  • A user directory that supports LDAP version 2 or 3
  • A host with Java 1.8+ (the host that will run LoginTC User Sync Tool)

Installation

  1. Download the latest LoginTC User Sync Tool
  2. Unzip the file

Installing on LoginTC RADIUS Connector

You may install the sync tool on the LoginTC RADIUS Connector by following the steps:

  1. Log in to the RADIUS Connector as logintc-user
  2. Install Java and unzip: sudo yum -y install java-1.8.0-openjdk unzip
  3. Download User Sync Tool: curl -O https://www.logintc.com/downloads/logintc-sync-1.0.2.4.zip
  4. Unzip the User Sync Tool: unzip logintc-sync-1.0.2.4.zip

You are now ready to run sh logintc-sync. While the options in the LoginTC RADIUS Connector and the User Sync Tool configuration files are similar, they should be separate files.

Configuration

Copy the sample configuration file sample.cfg to config.cfg and configure the two sections.

LoginTC

The following properties instruct LoginTC Sync Tool on how to communicate with LoginTC Admin.

Property Explanation Examples
host Host or IP address of LoginTC Admin host cloud.logintc.com
api_key Your organization 64-character API key YOUR_API_KEY
domain_id The 40-character domain ID for the domain you wish to sync with YOUR_DOMAIN_ID

LDAP

The following properties instruct LoginTC Sync Tool on how to communicate with your LDAP directory.

Property Explanation Examples
host Host or IP address of the LDAP server ldap.example.com, ldap.example.com:4444
encryption Type of LDAP encryption to use none, ssl, startTLS
bind_dn DN of a user with read access to the directory cn=Manager,dc=example,dc=com
bind_password The password for the above bind_dn account MY_PASSWORD
base_dn The top-level DN that you wish to query from ou=People,dc=example,dc=com
attr_username The attribute containing the user’s username sAMAccountName, uid
attr_name The attribute containing the user’s real name displayName, cn
attr_email The attribute containing the user’s email address mail, email
filter An LDAP query for the users you wish to sync (objectClass=person)

Note: The user’s real name is only used for email correspondence and if you desire, you may set attr_name to be the same as attr_username.

Usage

Run LoginTC Sync Tool with logintc-sync:

sh logintc-sync --dry-run config.cfg
Fetching users...
Fetched 2 user(s)
+----------+----------+----------------------+
| Username | Name     | Email                |
+----------+----------+----------------------+
| john.doe | John Doe | john.doe@example.com |
| jane.doe | Jane Doe | jane.doe@example.com |
+----------+----------+----------------------+
Async Job created with id: 0371a83b752fcdbe6141cec14091527acd84c5a1
Status: Completed. Completed 2 of 2 action(s) (approx.).
Job completed successfully.

When you are satisfied with the users fetched from LDAP, run sh logintc-sync without the --dry-run flag to perform the one-way synchronization with LoginTC Admin. The synchronization will add the new users to your organization and make them members of your domain. If you remove users from your user directory and then perform synchronization, the users will be removed from the domain and their tokens will be revoked (but they will still exist in your organization).

Options

Option Explanation Examples
-a,--local-validation Perform local user data validation and fail if there is missing data. n/a
-d,--dry-run Fetch users from LDAP but don’t sync them. n/a
-e,--default-email <arg> Specify a default email to be used when the email is missing. john.doe@example.com
-h,--help Display help message. n/a
-i,--ignore-referral Ignore LDAP referrals. n/a
-j,--job-status <arg> jobId. Get job status. n/a
-l,--email-notification <arg> An email confirming new and removed will be sent to the specific email address. The email address must match an existing administrators email or it will be ignored. administrator@example.com
-m,--sync-mode <arg> [add_only | remove | delete]. add_only will only add users and not remove or delete. In remove mode users are removed from the domain, while in delete mode users are also deleted from the organization. Default is add_only. add_only
-n,--default-name <arg> Specify a default name to be used when the name is missing. John Doe
-r,--max-remove-limit <arg> Maximum number of remove actions (either remove from domain or delete) that can be performed. If the limit is reach no remove actions are made. Default is 0. 10
-t,--sync-token-mode <arg> [do_not_issue_token | issue_token_with_email | issue_token_without_email]. do_not_issue_token will not issue tokens for newly added users. In issue_token_with_email mode newly added users are issued a token with an email, while in issue_token_without_email mode no email is sent. Default is do_not_issue_token. do_not_issue_token
-v,--version Display the version number. n/a

Examples

Only create / add new users to the domain. Issue tokens for new domain members.

sh logintc-sync -t issue_token_with_email config.cfg

Create / add new users and remove users from the domain not part of sync. Allow for up to 10 remove actions. Issue tokens without email for new domain members.

sh logintc-sync -m remove -r 10 -t issue_token_with_email config.cfg

Create / add new users and delete users from the organization not part of sync. Allow for up to 10 remove actions. Issue tokens without email for new domain members. Send en email notification whenever an action is performed (ideal for cron jobs).

sh logintc-sync -m delete -r 10 -t issue_token_with_email -l administrator@example.com config.cfg

Check status of a job.

sh logintc-sync -j 0371a83b752fcdbe6141cec14091527acd84c5a1 config.cfg
Job ID: 0371a83b752fcdbe6141cec14091527acd84c5a1
Job Type: SyncUsersJob
Job Status: Completed
Job Date Created: 2017-08-02T17:46:43+0000
Job Date Started: 2017-08-02T17:46:43+0000
Job Date Completed: 2017-08-02T17:46:43+0000
Job Actions (approx.): 2 of 2
Job Error Code:
Job Error Message:

Troubleshooting

Certificate Errors

LoginTC Sync Tool uses Java’s default trust store. Ensure that your LDAP certificate is in Java’s default trust store (commonly located in security/cacerts in $JAVA_HOME).

java.lang.UnsupportedClassVersionError

A java.lang.UnsupportedClassVersionError exeption means that an unsupported version of Java is being used to run logintc-sync. Make sure the Java version being used is at least 1.8. The full error displayed:

Exception in thread "main" java.lang.UnsupportedClassVersionError: com/cyphercor/logintc/sync/Main : Unsupported major.minor version 52.0
    at java.lang.ClassLoader.defineClass1(Native Method)
    at java.lang.ClassLoader.defineClassCond(ClassLoader.java:637)
    at java.lang.ClassLoader.defineClass(ClassLoader.java:621)
    at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:141)
    at java.net.URLClassLoader.defineClass(URLClassLoader.java:283)
    at java.net.URLClassLoader.access$000(URLClassLoader.java:58)
    at java.net.URLClassLoader$1.run(URLClassLoader.java:197)
    at java.security.AccessController.doPrivileged(Native Method)
    at java.net.URLClassLoader.findClass(URLClassLoader.java:190)
    at java.lang.ClassLoader.loadClass(ClassLoader.java:306)
    at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:301)
    at java.lang.ClassLoader.loadClass(ClassLoader.java:247)

For instructions on installing Java on the LoginTC RADIUS Connector see: Installation