Installing the EmpowerID Domain Controller Filter

EmpowerID provides an optional plugin, the EmpowerID Domain Controller (DC) Filter, that can be installed on all Active Directory domain controllers to provide password synchronization for users with multiple accounts residing on different managed Account Stores. The installation adds a password filter, PwdFilter, and a Windows Service, EmpowerID DC Filter Service, onto each domain controller. When a password change occurs, PwdFilter calls the EmpowerID DC Filter Service, which in turn forwards the password sync request to the DCFilterService web service hosted on the EmpowerID Server. EmpowerID takes these notifications and syncs the new password to any other user accounts owned by an EmpowerID Person as well as their Person object via the Reset Password By Sync operation, depending on the value specified for the RequestWorkflowID in the EmpowerID Identity Warehouse. If the value for the RequestWorkflowID is null (no workflow is specified), the password sync occurs through code; otherwise, the workflow handles the entire task. If desired, custom logic can be added to the workflow in Workflow Studio to sync to an unsupported system or provide additional logging.

The EmpowerID DC Filter Service is configured by default to use a service identity that is mapped to an EmpowerID Person to reset user account passwords in Active Directory. However, as a best practice, certificate-based authentication is recommended as problems can sometimes arise when using a service identity. This topic, therefore demonstrates installing and configuring the EmpowerID DC Filter Service using certificates for authentication. In this scenario, two certificates are needed, a client certificate issued to the domain controller and the EmpowerID Server certificate (the certificate used in the EmpowerID deployment). EmpowerID will need the public key of the client certificate and the domain controller will need the public key of the EmpowerID Server certificate, as well as the root for that certificate. These certificates will need to be added to the certificate stores on each machine (domain controller and the EmpowerID server).
The DC Filter Client certificate can be SHA-2 in EmpowerID 2016 and EmpowerID 2017, but must be SHA-1 in previous versions.

This topic demonstrates how to install the EmpowerID DC Filter and is divided into the following activities:

To install the Message Queueing Feature

  1. Install the Message Queuing Feature on every Active Directory domain controller by logging into each server, opening Server Manager and clicking Features > Add Features. Select Message Queuing, click Next and then click Install. This provides the queuing system that the Windows EmpowerID DC Filter Service uses to store password requests until they are processed.
  2. From Server Manager, install the .NET Framework 3.5 Features (includes .NET 2.0 and 3.0).

To install the EmpowerID domain controller filter

The service account for the DC Filter must have logon as a service rights on all Domain Controllers. Otherwise the EmpowerID DC Filter service will not start.

  1. On each domain controller, double-click the EmpowerID.DCFilter.msi to launch the EmpowerID Domain Controller Filter Setup.
  2. Enter the credentials for the Windows service account (local admin) that is to run the DC Filter Service and click Next. This accounts reads the EmpowerID DC Filter queue and sends any password change notifications to EmpowerID.
  3. If desired, you can change the service account to the Local System account on the Domain Controller. To do so, open services.msc and locate the EmpowerID DC Filter Service. Open the Properties dialog for the service and set the log on to Local System account.

  4. In the Queue Name field, type the path to the Private Queues section and the name of the queue where all password reset requests are to be processed, then press Tab and click Next to continue. The format for this should be .\private$\queueName.
  5. In the example below, we are creating a queue named eid in the Private Queues section.

  6. Select the folder location in which to place the installed files and then click Install to continue.
  7. Wait for the wizard to complete the installation and then click Finish.
  8. Reboot the domain controller.
  9. Open the Computer Management console and navigate to Services and Applications > Message Queuing > Private Queues.
  10. You should see the private queue you created for the DC Filter.

  11. Double-click the queue to open the Properties dialog for it.
  12. Click the Security tab and then click the service account you specified for the DC Filter.
  13. You should that the account has full permissions on the queue.

To export the EmpowerID server certificates to the Domain Controller

  1. On the EmpowerID server that is to receive messages from the domain controller, open MMC and add the Certificates snap-in for the local computer.
  2. Expand Certificates > Personal and then click Certificates.
  3. From the Personal Certificates store, right-click the EmpowerID Server certificate and select All Tasks > Manage Private Keys from the context menu.
  4. Ensure that the DC Filter service account you specified has permissions for the keys.
  5. From the Personal Certificates store, right-click the EmpowerID server certificate and select All Tasks > Export from the context menu.
  6. In the Certificate Export Wizard that appears, click Next.
  7. Select No, do not export the private key and click Next.
  8. Select DER encoded binary X.509 (.CER) and click Next
  9. Click Browse, navigate to an appropriate place on the domain controller in which to save the certificate, type a name for the certificate in the File name field and then click Save.
  10. Back in the Certificate Export Wizard, click Next and then click Finish.
  11. Click OK to close the certificate export message.
  12. Back in MMC, expand Trusted Root Certification Authorities and click Certificates.
  13. From the Trusted Root Certification Authorities store, right-click the root certificate for the EmpowerID server certificate and select Export from the context menu.
  14. In the Certificate Export Wizard that appears, click Next.
  15. Select DER encoded binary X.509 (.CER) and click Next
  16. Click Browse, navigate to an appropriate place on the domain controller in which to save the certificate, then type a name in the File name field and click Save.
  17. Back in the Certificate Export Wizard, click Next and then click Finish.
  18. Click OK to close the certificate export message.

To import the EmpowerID server certificates to the Domain Controller Certificate Stores

  1. On the domain controller, open MMC and add the Certificates snap-in for the local computer.
  2. Expand Certificates > Personal, right-click Certificates and select All Tasks > Import from the context menu.
  3. In the Certificate Import Wizard that appears, click Next.
  4. Click Browse, select the EmpowerID server public key certificate you just exported and then click Open.
  5. Click Next.
  6. Click Next again and then click Finish.
  7. Click OK to close the certificate import message.
  8. Back in the Certificates Snap-In of MMC, expand Trusted Root Certification Authorities, right-click Certificates and select All Tasks > Import from the context menu.
  9. In the Certificate Import Wizard that appears, click Next.
  10. Click Browse, select the EmpowerID root certificate you exported earlier and click Open.
  11. Click Next.
  12. Click Next again and then click Finish.
  13. Click OK to close the certificate import message.

To export the client certificate public key to the EmpowerID server

  1. From the Certificates snap-in of your domain controller, navigate to the Personal Certificates store.
  2. From the Personal Certificates store, right-click the client certificate and select All Tasks > Export from the context menu.
  3. In the Certificate Export Wizard that appears, click Next
  4. Select No, do not export the private key and click Next.
  5. Select DER encoded binary X.509 (.CER) and click Next
  6. Click Browse, navigate to an appropriate place on the EmpowerID server in which to save the certificate, type a name for the certificate in the File name field and then click Save.
  7. Back in the Certificate Export Wizard, click Next and then click Finish.
  8. Click OK to close the certificate export message.

To add the client certificate to the EmpowerID certificate store

  1. On the EmpowerID server, log in to the EmpowerID Management Console as an administrative user.
  2. From the EmpowerID Management Console, click the EmpowerID icon and select Configuration Manager from the application menu.
  3. In Configuration Manager, expand the EmpowerID Servers and Role node in the application navigation tree and then click the Manage Certificates node.
  4. Click the Add New button located above the Certificates grid and select From File from the context menu.
  5. In the Open File dialog that appears, locate and select the client certificate you exported earlier and then click Open.
  6. Click No when asked if the certificate requires a password.

To create a certificate-based service configuration file in Workflow Studio

  1. On the EmpoweID server, log in to Workflow Studio as an administrator.
  2. In Workflow Studio, click the Servers tab located to the left of Solution Explorer.
  3. Expand the EmpowerID Servers > EmpowerID Server > Services > EmpowerID Web Role Service nodes in the servers tree and then right-click any one of the EmpowerID services and select Generate <System.ServiceModel> Configuration from the context menu.
  4. In the Relying Party Config that is generated, click the Certificate tab and copy the XML.
  5. Open a text editor and paste the XML in to a blank document and then save the document as an XML file named EmpowerIDPwdFilterService.exe.config.

To edit the EmpowerID DC Password Filter Config file for certificate-based authentication

  1. On the domain controller, navigate to "C:\Program Files\EmpowerID Domain Controller Filter" and create a backup copy of the original EmpowerIDPwdFilterService.exe.config file.
  2. Locate the EmpowerIDPwdFilterService.exe.config file you created in Workflow Studio and paste it in to the "C:\Program Files\EmpowerID Domain Controller Filter" directory.
  3. When the Copy File dialog opens, select Copy and Replace. Be sure you have created a backup of the original config file before doing so.
  4. Open the EmpowerIDPwdFilterService.exe.config file you just copied with a text editor.
  5. In the EmpowerIDPwdFilterService.exe.config file, specify the correct certificate for client cert authentication by locating the clientCertificate attribute (line 9) and replacing findValue with the thumbprint of your client certificate. In the below example, the highlighted text is the thumbprint of the client certificate we are using in our environment. You should replace this with the thumbprint of your client certificate.
  6. <clientCertificate findValue="9D49BEF8F5D9F419D61C5061869D1F7CFAAAA377"
            storeName="My"
            storeLocation="LocalMachine"
            x509FindType="FindByThumbprint"/>
  7. In the EmpowerIDPwdFilterService.exe.config file, specify the correct service contract by locating the endpoint attribute (line 95) and changing the address value to point to the DCFilterService.svc and the contract value to DCFilterService.DCFilterService.
  8. <endpoint address="https://EID.tdnflab.com/EmpowerIDWebServices/DCFilterService.svc
            binding="ws2007FederationHttpBinding" bindingConfiguration="WS2007FederationHttpBinding_LoginService"
            contract="DCFilterService.DCFilterService" name="WS2007FederationHttpBinding_LoginService" behaviorConfiguration="ClientCertificateBehavior">
            
  9. Next, ensure the URL for the endpoint address is correct by copying and pasting it in the address bar of a browser. You should see a page similar to the following:
  10. Save your changes to EmpowerIDPwdFilterService.exe.config.
  11. Restart the EmpowerID DC Filter service.

To create an EmpowerID Person account for the DC Password Filter service

  1. Log in to the EmpowerID Web application as an administrator.
  2. From the Navigation Sidebar, navigate to Person Manager by expanding Identities and clicking on People.
  3. In Person Manager, click the Actions tab and then click Create Person Simple Mode.
  4. Enter a first name and a last name for the Person account in the First Name and Last Name fields, respectively. As this Person account serves as an identity for the DC Password Filter service, you should name it accordingly. In our example, we are naming the Person "dcsvcproxy."
  5. Underneath Primary Business Role and Location, click Select a Role and Location.
  6. In the Business Role pane of the Business Role and Location selector that appears, type Temp, press ENTER and then click Temporary Role to select it.
  7. Click the Location tab to open the Location pane and then type Temp, press ENTER and click Temporary Role to select it.
  8. Click Select to select the Business Role and Location for the Person account and close the Business Role and Location.
  9. Click Save to create the EmpowerID Person.

To delegate the DC Filter Password Sync Access Level

  1. From Person Manager, search for the person you just created and then click the EmpowerID Login link for that person.

    This directs you to the View One page for the person. View One pages allow you to view details about an object in EmpowerID and make changes to those objects as needed.
  2. From the View One page, expand the Access Assignments accordion.
  3. In the Access Assignments accordion, select By Location from the Assignment Type drop-down and then click the Add (+) button in the grid. By Location assignments allow you to give the person an Access Level against all resources in a selected location and all child locations of that location.
  4. In the Grant Access dialog that appears, do the following:
    1. Select Person from the Resource Type drop-down as the Password Reset Sync operation will be executed against Person objects.
    2. Underneath For Resources in or Below, click the Select a Location link.
    3. In the Location Selector that appears, search for an select the appropriate location and then click Save to close the Location Selector. In our example, we are granting the access assignment against all people in any location so we have selected Anywhere.
    4. Select DC Password Sync from the Access Level drop-down. This Access Level has one operation allowed, the Reset Password By Sync operation.
    5. Optionally, ff you want to limit the access to a specified period of time, tick Time Constrained and select the appropriate dates from the calendar.
    6. Click Add to add the assignment to the shopping cart.
  5. Click the Shopping Cart and in the Cart dialog that appears, type a reason for the assignment and then click Submit.

To map the client certificate to the EmpowerID Person

  1. From the View One page for the person, expand the Editable Multivalued Fields accordion and then click the Edit link in the Mapped Login Certificates pane.
  2. Search for and select the client certificate and then click Save.
  3. Certificates can only be mapped to one person. If you decide at a later point in time to use another Person account for the DC Password Filter, you must remove the certificate mapping from the first EmpowerID Person before you can map it to the new person.

To test the EmpowerID DC Filter Password service

  1. On any EmpowerID server open ADUC and locate a user account that has an EmpowerID Person linked to it.
  2. Reset the password for that user.
  3. Open the Event Viewer on the domain controller.
  4. Expand Applications and Services Logs and click EmpowerID.
  5. You should see a message showing that the EmpowerID Service Bus was called to Sync Password for the select user account. There should be no errors in the log.