AD Connector

Step-by-step guide

This guide will show you how to install and maintain the client side service for the AD Connector.

Contents

• Introduction
• Requirements
• Service Installation
• Uninstall the service
• Migrating the service
• Service Account requirements
• Server requirements
• Service Architecture
• Error Troubleshooting
  • Service Installation
  • Service Failures
  • Emails not sending

Introduction

There will occasionally be a situation where the AD Connector service will need installing.

• Initial install
• Migration to a new server
• Change to credentials/configuration

This can be accomplished without direct support from Ciphr. Where support is required this will need to be raised to our professional services team for half a day's services to support. 

The following steps will outline how to install or migrate the AD Connector service.

Requirements

To complete any service install, you will need to ensure you have the relevant details for the service. If you already have AD Connector, this is likely stored on the server that hosts the service under c:\CiphrADConnector, within a password encrypted zip file. The password for this file should be the same as the service account that runs the service.

Required details:

• Domain Service Account user/pass (For Entra ID, this can just be local computer admin)
• Ciphr AD Connector Url (This is your normal HR self service with /ciphradconnector appended)
• Ciphr API user/token
• SMTP details (Emails are generated on your environment, not Ciphr's)
  • Host
  • Port
  • User (optional)
  • Password (optional)
• Azure details (optional)
  • Tenant ID
  • Application ID (Ciphr AD Connector should be registered as an app in your tenant)
  • Secret

If you need a new copy of the installer and your Ciphr details (AD Connector Url/API user/token) then please raise a ticket to customer care who can provide this for you. Ciphr does not store details of the customer environment. Service account, server, SMTP and Azure details are all expected to be managed by customer IT.

Service Installation

Note, if the service already exists on the server, you will need to uninstall it first. Please follow the guidance further down this article for guidance on uninstalling the service.

Run the installer and complete the fields as necessary.

Enter Service account details

Enter the Ciphr AD Connector API details

For the Job Synchronisation, the value "10" should be entered. For service number, this should be set as "1". Where you have multiple domains this service number may be different, please clarify this with Ciphr customer care.

SMTP configuration

If sending anonymously or without authentication, please leave the username/password fields blank.  There will be an additional step to complete post install if sending anonymously. Please see Anonymous SMTP config below.

Configuring Azure (optional)

The Azure connection is only required in the following scenarios

• Updating photos or licences within O365
• If you are intending to sync directly with Entra ID and do not have a hybrid/On-Prem environment

The redirect Url will need to match the application configuration in your Azure tenant.

Entra ID Token (optional)

The final screen is only required if you are using Entra ID to host your AD.  This doesn’t mean a Domain Controller hosted in Azure but a pure Azure Active Directory without any server dependencies.

If you are using Entra ID then click “this link” (highlighted blue), log in and extract the value after the keyword “Code” from the url (not the whole remainder of the url, just up to the next parameter). This is the value to enter at this stage. This is the token generated by Azure that is required to create users in Entra ID.

Complete the install

Wait for the installer to finish (Command Line window will read ”Ciphr AD Connector service was started”) and then close the cmd window and installer wizard.

A test can be run by manually triggering a daily sync workflow. Guidance on doing this can be found in the associated KB article here.

If the cmd line window has displayed any red text then an error has occurred during install. Attempt the install again, checking the values and ensure everything is correct. If the errors persist, try a different server or reach out to Ciphr customer care with the error for support.

Anonymous SMTP Config (optional)

The below section also outlines where SMTP details for relaying notifications by the service are stored. Any credentials are encrypted and cannot be changed directly within the file, changing them will require the service to be re-installed.

If using anonymous/unauthenticated email, you will also need to edit a value in the config file. Open Notepad as an administrator and open C:\Program Files (x86)\ADConnector\Ciphr.Hub.exe.Config

From within here edit the SMTPUsername and SMTPPassword values to empty by deleting the 5.

Save the file and restart the service.

Uninstall the service

Where you need to uninstall the service, either due to a migration or needing to update config, the below steps will remove the service from the server.

• Stop the “Ciphr AD Connector” service under "Services" on the server.
• Remove the program using Add/Remove programs from the Windows Control Panel.
  • You may find the uninstaller hasn’t removed the service. In this situation, open a cmd window as admin and run sc delete “Ciphr AD Connector” as per the screenshot below.
  • If the service doesn’t appear under add/remove programs then you can complete the below service removal step and delete all the files under the existing installation directory (by default c:\program files (x86)\adconnector) to clear out the files.

• There will also be a scheduled task that runs on the server, if you are intending to completely uninstall ADC from the server, this should be disabled/removed as well. If the connector is being reinstalled on the same server, this task should be left alone.

Migrating the service

Where there is a requirement to migrate the service to a new server, this can be accomplished by following the above guidance to uninstall on the old server and install on the new one.

We recommend before uninstalling any existing service that the service is stopped, rather than removed, on the existing server while the new service is tested. This can then be removed once testing is successful.

Any existing scheduled tasks that are related to the service and folders under c:\ciphradconnector should also be migrated to the new server.

Service Permissions

The service account will need relevant permissions for the service to run as intended. Ciphr suggests the principle of least privilege for the service so while the below list outlines all potential permission requirements, this should only reflect what functionality you have enabled as part of your service.

• Local administrator to server (inc. log on as batch and service)
• Admin to AD (Read access to whole domain. Write and delete access required to any OUs the service is expected to work in)
• Add/Remove security Groups
• Member of Organization Management Exchange security group
• Read and Write to home drive fileserver

Server Requirements

• Ports 587, 25 and 443 open
• Remote management tools for AD installed (Users and Computers/ADSI Edit) - This is only required for active support from Ciphr
• Following sites allowed through any existing firewalls or similar
  • https://yourportal.myciphr247.com/CiphrAdConnector/ (this is your HR self service portal)
  • O365
  • Mail host

Service Architecture

Troubleshooting

The client service is not hosted by Ciphr but on customer IT environments. Due to the complexity and variety of IT infrastructure and policies across organistions any support provided by Ciphr is on a "best efforts" basis. Ciphr will provide support where possible but it is the responsibility of the customer's IT to monitor and maintain the client service, ensuring it can access the AD Connector API hosted by Ciphr.

The application log under Windows event viewer is a good starting point when considering any investigation.

Service Installation

Failed to retrieve Office 365 token : This will be caused by either the credentials entered into the relevant boxes within the installer being wrong/invalid or the server not being able to access Azure. First step to resolve is reinstall and double check install values against the app registration in Azure.

Can’t access API (WorkflowSqlLite.db file not populating) : Caused by either the CIS credentials being wrong or the CiphrADConnector site being blocked. Attempt to open the site via a browser on the server. Request relevant site is unblocked as necessary.

Service not running (Stops after starting)

The service not running can be indicated by the workflows being enabled but not having a recent runtime under the AD Connector portal dashboard (as below). Where the service stops shortly after being started, this usually indicates an issue with the AD Connector API url. Check that the server can access the site over port 443 and that network traffic is not being blocked by a firewall or similar.

If the service starts and runs but then stops overnight and only seems to work after resetting the password (but the service account password hasn't changed). This indicates an issue with group policies overwriting the local security policy. Examples of this problem can be found online on sites such as StackOverflow.

Emails not sending

Where the server is failing to connect to the defined SMTP host, there is likely an issue with the firewall or sending method. You can run the below command from powershell on the server to help diagnose the problem.

If utilising direct send via your O365 MX record, you will need to ensure that the domains of the sending and receiving mailboxes are correct for the domain being used. These can be checked in the global variables of the workflows, guidance for this can be found in the associated KB article.