Create Workspot Enterprise Connector

The Workspot Enterprise Connector (also called Connector or EC) integrates Workspot Control with your Active Directory (AD) domain controller. Connector is a Windows service that you install on a server in your data center.

This article gives a simplified installation procedure that is adequate for most deployments see Workspot Enterprise Connector for a more detailed treatment.

How Workspot Enterprise Connector Works

Connector relays read-only queries between Workspot Control and your AD server. Workspot Control needs to know the users' status and group membership to assign the correct resources to them. Connector opens a secure connection to Workspot Control to listen for requests about user account status and group membership, then services requests by forwarding them to your AD server.  

Connector opens an outbound HTTPS connection with Workspot Control on port 443 and communicates with your AD server on the usual ports.

New users won’t be able to register with Workspot Control if Enterprise Connector isn’t running.

Prerequisites

General

1. Your AD administrator must create a service account for Connector on your domain controller that has limited domain access.

2. Run the Connector service on at least one supported, dedicated, maintained Windows server VM on the same private network as your domain controller.

3. The Connector VM should be domain-joined using the same OU as the service account.

4. Use Connector only on secure LANs or VPNs.

5. Keep the servers running Connector up-to-date with security patches, etc.

6. Workspot recommends having two instances of Connector on different hosts for high availability. Control automatically load-balances queries to multiple Connectors and queries the surviving instance if one fails.

7. If you use replicated domain controllers, having different instances of Connector that connect to different replicated controllers is recommended for greater reliability.

Hardware/OS requirements:

• See Workspot OS and Hardware Requirements for supported Windows Server versions for Windows Enterprise Connector.

• The server running Connector must be a member of the Windows domain used by Connector.

Outbound Connections

Connector must be able to open outbound connections over HTTPS on port 443 as listed in Internet Firewalls and Workspot.

Required Software Packages

Java. Connector requires the Java Runtime Environment. Workspot recommends Azul Zulu OpenJDK 8. As of October, 2023, the most recent certified version was 8.58. Download it here from Azul.

Powershell. Installation requires Windows PowerShell 2.0 or above (installed by default with Windows Server 2016 and higher).

Create the Service Account on the Domain Controller

Creating the Service Account

You must create a service account in Active Directory before installing Connector.

• The password for this account must not contain spaces or non-printing characters.

• If the password contains a double-quote character ("), expect to have to escape it as (\") later, when you install Connector.

• For permissions, see "Setting Permission for the Service Account," below.

• For production installations, grant the Connector service account "Log on as a Service" rights via Group Policy.  This will ensure that the account does not lose this privilege in the future and the Connector service will be able to start.

Set Permissions for the Service Account

Permissions for the Workspot Enterprise Connector service account should be configured as follows: 

1. On the domain controller, login as a domain administrator and create a new domain user for the Connector service account. 

2. Open Command Prompt in "Run as Administrator" mode.

3. Install the AD Schem snapin:

>regsvr32 schmmgmt.dl

4. Set permissions using dsacls commands as shown below.

   • In the following examples, the domain is example.com.

   • The base DN for the domain is dc=example,dc=com.

   • The Connector service account is WSECservice.

5. Add Replicating Directory Changes to the service account:

> dsacls "dc=example,dc=com" /g "example\WSECservice:CA;Replicating Directory Changes"

4. Add Replication synchronization to the service account:

> dsacls "dc=example,dc=com" /g "example\WSECservice:CA;Replication synchronization"

5. Add the List Contents and Return Property Deleted Object permissions

> dsacls "cn=deleted objects,dc=example,dc=com" /takeownership

6. Then grant permissions for the EC service account as follows:

> dsacls "cn=deleted objects,dc=example,dc=com" /g example\WSECservice:LCRP

For more information on Dsacls see https://technet.microsoft.com/en-us/library/cc771151.aspx

Enable AES Encryption

Depending on your organization’s security policies, you may also have to declare that the account supports AES encryption in its AD Account Options before it contacts the domain controller with an accepted encryption.

Note: The screen capture shows a different service account than the examples above.

Configuring the Connector VM

Perform these steps before installing Workspot Connector:

1. Join the Connector VM to the exact same domain (OU) as the one specified for the service account (“example.com” in the example above).

2. Add the service account to the list of local administrators.

Configure in Workspot Control

Declare a Private Cloud

1. Sign into the Connector VM using the service account.

2. From the Connector VM, use a browser to sign into Workspot Control as a Control Administrator.

3. Create a Private Cloud: Go to Setup > Cloud > Private Cloud > Add Private Cloud.” Enter a Name for the configuration, in this example, "US Private Cloud".

4. Back on the “Setup > Cloud” page, click on the name, "US Private Cloud", to manage its configuration. This will show the “Manage Private Cloud” page, which will show “No connectors.”

Declare a New Connector

5. Click “Add Connector” and a Connector definition will be declared, along with an integration key that we will copy to Workspot Connector server.

6. Click the integration key field and it will pop up a window with the full string. Select this and paste it somewhere, such as in Notepad, since we will need it later.

Download and Install Workspot Connector

1. Still signed into Workspot Control from the Connector VM, navigate to the “Setup > Cloud > your_private_cloud_name” page, click the Download Connector button to download the Enterprise Connector installer.

2. Launch the Workspot Enterprise Connector Installer and navigate through the initial screens.

3. In the Integration Key screen, paste in:

   • Your Company Identifier

   • your Integration Key,

   • the AD domain name serviced by Connector,

   • the username of the service account created previously in Active Directory (and added to this machine's local administrators group),

   • and the service account's password.

     • If the password contains a double- quote character ("), escape it as (\").

3. Click on Finish.

4. In Windows Services, verify that the Workspot Enterprise Connector service is running

Finish Configuration on Workspot Control 

1. Returning to Workspot Control, Go to “Setup > Cloud” to check the connector status. If installed and configured correctly, the status will show “Available” on the “Cloud” page and “Connected” on the “Private Cloud” page.

2. The “Configs” tab of the “Manage Private Cloud” page is now active and you can finish your configuration.

Troubleshooting

• If errors occur during installation and setup, see c:\ProgramData\workspot\setup.txt.

• If Connector doesn't seem to be running, start it in Services.

• If errors occur while Connector is running, see the log file in C:\Program
  Files\Workspot_Enterprise_Connector\log.

Related Documents

• User Self-Registration and Resource Entitlements

• Enterprise Connector (EC) - Troubleshooting Guides

• Workspot Enterprise Connector

• For more information on dsacls. see https://technet.microsoft.com/en-us/library/cc771151.aspx.