Install the EmpowerID Domain Controller Filter

The EmpowerID Domain Controller (DC) Filter is an optional plugin that you can install on all of your Active Directory domain controllers to synchronize passwords for users for their accounts in different account stores. It installs a PwdFilter and DC Filter Service on each domain controller. 

When a password change occurs, PwdFilter calls the DC Filter Service, which in turn forwards the password sync request to the DCFilterService web service hosted on the EmpowerID Server, triggering the Password Sync DC Filter workflow. The workflow takes these notifications and syncs the new password to any other user accounts owned by an EmpowerID Person as well as their Person object. 

You can change 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. To sync to an unsupported system or provide additional logging, you can add custom logic to the workflow in Workflow Studio.

The workflow looks like this. (A description follows the diagram.)

Open

In the diagram, we have two domains, each with two domain controllers, one EmpowerID server, and a number of native systems.

1. When a user account password change occurs, the PwdFilter calls the DC Filter Service.

2. The DC Filter Service forwards the password sync request to the DCFilterService web service hosted on the EmpowerID server.
   

3. The Password Sync DC Filter workflow verifies whether the request is authorized.

4. If so, it updates the password on the user account.

5. The workflow then checks whether Allow Password Sync is enabled on the related account store, and whether the user account is linked to a person.

6. If so, it updates the password on the person and checks to see whether the person has more accounts with Allow Password Sync enabled.

7. If so, it updates the password on any user accounts linked to the person that have Allow Password Sync enabled.

8. Then it checks other domains to see whether they have domain controllers, and updates the password as appropriate.

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

• Step 1 - Install the Message Queuing feature on the domain controller

• Step 2 - Install the EmpowerID DC Filter Service on the domain controller

• Step 3 - Export the public key and root certificates of the EmpowerID server certificate to the domain controller

• Step 4 - Import the public key and root certificates of the EmpowerID server certificate to the appropriate certificate stores on the domain controller

• Step 5 - Export the public key of the client certificate to the Empower server

• Step 6 - Add the client certificate to the EmpowerID certificate store

• Step 7 - Create a certificate-based service configuration file in Workflow Studio

• Step 8 - Edit the EmpowerID DC Password Filter Config file for certificate-based authentication

• Step 9 - Install the SSL certificate on the server

• Step 10 - Create an EmpowerID Person for the DC Password Filter Service

• Step 11 - Delegate the DC Filter Password Sync Access Level to the EmpowerID Person

• Step 12 - Map the Client Certificate to the EmpowerID Person

• Step 13 - Testing the EmpowerID DC Filter

Step 1 - Install Message Queuing 

Follow this installation on each Active Directory domain controller server.

1. Log into the server and in Server Manager, from the Manage menu, select Add Roles and Features.

2. In the Add Roles and Features Wizard that appears, click Next until you reach the Features tab.

3. Expand Message Queuing, then Message Queuing Services, and select Message Queuing Server. This provides the queuing system that the Windows EmpowerID DC Filter Service uses to store password requests until they are processed.
   
   

   Open

   

    

4. On the same tab, select .NET Framework 4.5 Features and .NET Framework 3.5 Features, click Next and then click Install.

Step 2 - Install the domain controller filter

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. (Note that you must specify the user name in the format domain\username.)
   
   

3. 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 is .\private$\queueName.

   In the example below, we are creating a queue named eid in the Private Queues section.
   
   

    

4. Select the folder location in which to place the installed files and then click Install to continue.
   
   

    

5. In the User Account Control dialog, click Yes to allow the program to make changes.

6. Wait for the wizard to complete the installation and then click Finish.

7. Reboot the domain controller.

8. Open the Computer Management console and expand Services and Applications, then Message Queuing, and select Private Queues to see the private queue you created for the DC Filter.
   
   

    

9. Double-click the queue to open the Properties dialog for it.

10. Click the Security tab and then click the service account you specified for the DC Filter to verify that the account has full permissions on the queue.
    
    

Step 3 - Export the server certificates to the Domain Controller

1. On the EmpowerID server that is to receive messages from the domain controller, open MMC.exe.

2. From the File menu, select Add/Remove Snap-in, then select Certificates and click Add.

3. In the dialog that appears, select the option to manage certificates for Computer account and click OK.

4. Under the Console Root, expand Certificates (Local Computer), then Personal and select Certificates.

5. From the Personal Certificates store, right-click the EmpowerID Server certificate (the one beginning with an asterisk) and select All Tasks, then Manage Private Keys.
   
   

    

6. Ensure that the DC Filter service account you specified has permissions for the keys.
   
   

    

7. From the Personal Certificates store, right-click the EmpowerID server certificate and select All Tasks, then Export.

8. In the Certificate Export Wizard that appears, click Next.

9. Select No, do not export the private key and click Next.

10. Select DER encoded binary X.509 (.CER) and click Next.

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

12. Back in the Certificate Export Wizard, click Next and then click Finish.

13. Click OK to close the certificate export success message.

14. Back in MMC, expand Trusted Root Certification Authorities and click Certificates.

15. From the Trusted Root Certification Authorities store, right-click the root certificate for the EmpowerID server certificate and select Export from the context menu.

16. In the Certificate Export Wizard that appears, click Next.

17. Select DER encoded binary X.509 (.CER) and click Next.

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

19. Back in the Certificate Export Wizard, click Next and then click Finish.

20. Click OK to close the certificate export message.

Step 4 - Import the server certificates to the DC Certificate Stores

1. On the domain controller, open MMC.exe and add the Certificates snap-in for the local computer.

2. From the File menu, select Add/Remove Snap-in, then select Certificates and click Add.

3. In the dialog that appears, select the option to manage certificates for Computer account and click OK.

4. Expand Certificates (Local Computer), then Personal, right-click Certificates and select All Tasks, then Import from the context menu.

5. In the Certificate Import Wizard that appears, click Next.

6. Click Browse, select the EmpowerID server public key certificate you just exported and then click Open.

7. Click Next.

8. Click Next again and then click Finish.

9. Click OK to close the import success message.

10. Back in the Certificates Snap-In of MMC, expand Trusted Root Certification Authorities, right-click Certificates and select All Tasks, then Import from the context menu.

11. In the Certificate Import Wizard that appears, click Next.

12. Click Browse, select the EmpowerID root certificate you exported earlier and click Open.

13. Click Next.

14. Click Next again and then click Finish.

15. Click OK to close the certificate import message.

Step 5 - Export the client certificate public key to the 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, then 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.

Step 6 - Add the client certificate to the server certificate store

1. In the EmpowerID Web interface navigation sidebar, expand Single Sign-On, then SSO Connections, and click SSO Components.

2. On the SSO Components page, click the Certificates tab and then click the Add button.
   
   

    

3. Browse for the client certificate you exported earlier and then click Open.

4. Leave Requires Password cleared.

5. Click Save.

Step 7 - Create a certificate-based service configuration file

1. On the EmpowerID server, log into 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.

Step 8 - Update the DC Password Filter Config file 

1. On the domain controller, navigate to C:\Program Files\EmpowerID Domain Controller Filter.

2. Create a backup subfolder, and copy the existing EmpowerIDPwdFilterService.exe.config file into the new subfolder.

3. Locate the EmpowerIDPwdFilterService.exe.config file you created in Workflow Studio and paste it into the C:\Program Files\EmpowerID Domain Controller Filter directory. 

4. When the Copy File dialog opens, select Copy and Replace. 

5. Open the EmpowerIDPwdFilterService.exe.config file you just copied with a text editor.

6. To specify the correct certificate for client cert authentication, locate the clientCertificate attribute and replace the findValue value with the thumbprint of your client certificate. 

   <clientCertificate findValue="9D49BEF8F5D9F419D61C5061869D1F7CFAAAA377" storeName="My" storeLocation="LocalMachine" x509FindType="FindByThumbprint"/>

    

7. To specify the correct service contract, locate the endpoint attribute and change the address value to point to the DCFilterService.svc and the contract value to DCFilterService.DCFilterService.

   <endpoint address="https://EID.tdnflab.com/EmpowerIDWebServices/DCFilterService.svc binding="ws2007FederationHttpBinding" bindingConfiguration="WS2007FederationHttpBinding_LoginService" contract="DCFilterService.DCFilterService" name="WS2007FederationHttpBinding_LoginService" behaviorConfiguration="ClientCertificateBehavior">

    

8. To specify the correct SSL certificate thumbprint, locate the certificateReference attribute and copy the findValue string. 

   <certificateReference findValue="1F47DEA25442BCADB60BB8F5F1C6A14A9B82AC9B" isChainIncluded="false" storeName="My" storeLocation="LocalMachine" x509FindType="FindByThumbprint"/>

9. From the Search menu of the text editor, select Replace.

10. In the Find what field, enter the copied findValue string.

11. In the Replace with field, enter the thumbprint of the SSL certificate used by the EmpowerID server and click Replace All.

12. Save your changes to EmpowerIDPwdFilterService.exe.config.

13. Restart the EmpowerID DC Filter service.

Step 9 - Install the SSL certificate on the server

1. On the EmpowerID server, locate your SSL certificate.

2. Right-click the certificate and select Install PFX.

3. Follow the steps in the wizard.

4. Repeat this process on each respective EmpowerID server. 

5. 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:
   
   

Step 10 - Create a person for the DC Password Filter service

1. On the navbar of the Web application, expand Identity Administration and click People.

2. On the Person page, click the Create Person Simple Mode action link.
   
   

    

3. 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, name it accordingly. In our example, we name the Person "dcsvcproxy."

4. Under Primary Role and Location, click Select a Role and Location.

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

       

   2. Click the Location tab to open the Location pane and then type Temp, press ENTER and click Temporary Role to select it.
      
      

       

   3. Click Select to select the Business Role and Location for the Person account and close the Business Role and Location.

5. Back in the main form, click Save to create the EmpowerID Person.

   After EmpowerID creates the Person, you should be directed to the View page for the Person. From this page, delegate to the Person the DC Filter Password Sync Access Level as outlined below.

Step 11 - Delegate the DC Filter Password Sync access level

1. On the Person Details page for the Person, click the Access Assignments accordion to expand it.

2. From the Access Assignments accordion, select By Location from the Assign direct to resource or other method? drop-down.
   
   

    

3. Click the Add New button located on the grid header.
   
   

    

4. In the Select the resource(s) to grant access to dialog that appears, do the following: 

   1. From the Resource Type drop-down, select Person, as the Password Reset Sync operation is executed against Person objects.

   2. Under For Resources in or Below, click the Select a Location link.

   3. In the Location Selector that appears, search for and select the appropriate location and then click Save to close the Location Selector. In our example, we grant the access assignment against all people in any location so we select Anywhere.
      
      

       

   4. From the Access Level drop-down, select DC Password Sync. This Access Level has one operation allowed, the Password Sync DC Filter workflow.

   5. Optionally, if you want to limit the access to a specified period of time, check Temporary Access (GMT/UTC Time) and select the appropriate dates and times from the calendar.

   6. Click Save to add the assignment to the shopping cart.

5. Click the Shopping Cart at the top of the page and in the Cart dialog that appears, type a reason for the assignment and then click Submit.
   
   

    

Next, map the client certificate to the same person as shown below.

Step 12 - Map the client certificate to the person

1. On the View page for the person, expand the Roles, Accounts, and Login Security  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.

Step 13 - Test the DC Filter Password service

1. On any EmpowerID server open Active Directory Users and Computers and locate a user account that has an EmpowerID Person linked to it.

2. Right-click the user and select All Tasks, then Reset Password, and reset the user's password.
   
   

    

3. Open the Event Viewer on the domain controller.

4. Expand Applications and Services Logs and click EmpowerID.

   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.
   
   

Updating Certificates

In the event that you are updating either the client certificate, the SSL certificate or both, you must update the EmpowerIDPWDFilterService.exe.config file with the thumbprints for the new certificates. Failure to do so will cause password resets to fail.

Additionally, if the client certificate is being replaced, you must upload the new certificate to the EmpowerID Certificate Store, remove the old client certificate from the EmpowerID Person to whom it is mapped and then map the new certificate to that same person.