Adding custom components to the Management Console ClickOnce manifest

EmpowerID is a flexible workflow platform that allows for the development of custom components to support your workflow applications. These custom components (developed using the EmpowerID Workflow Studio development environment) will not be included in the ClickOnce installation of the EmpowerID Management Console (EMC) by default. This may result in unintended behavior of your workflow applications. This guide will allow you to integrate these custom components into the ClickOnce manifest so end users receive them when they install the Management Console using the ClickOnce method. End users that installed the Management Console using the ClickOnce method prior to the integration of the custom components will also receive the custom components as an automatic update the next time they launch the Management Console on their workstation.

1. Download the Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 Service Pack 1 if you are running EmpowerID 2013 or the Windows Software Development Kit (SDK) for Windows 8 and .NET Framework 4.5 if you are running EmpowerID 2014 or newer. Once the file is downloaded, run the installer. When you reach the Installation Options screen, uncheck all of the available features except .NET Development Tools. Proceed with the installation.

2. Once the installation is finished, launch C:\Program Files\Microsoft SDKs\Windows\vx.x\Bin\mageui.exe. Replace x.x with the version of the Microsoft Windows SDK you have installed. If you chose an alternate installation location, please adjust the path as needed. You can also launch MageUI by clicking Start > All Programs > Microsoft Windows SDK vx.x > CMD Shell, click on the CMD Shell window, type MageUI and press ENTER. Replace x.x with the version of the Microsoft Windows SDK you have installed.

NOTE: If you receive an error "Manifest Generation And Editing Tool has stopped working" and have Federal Information Processing Standards (FIPS) enabled, you will need to disable Federal Information Processing Standards (FIPS) until you are finished performing the steps indicated here. The version of MageUI included with the Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 Service Pack 1 does not function with Federal Information Processing Standards (FIPS) enabled.

To temporarily disable Federal Information Processing Standards (FIPS), open Registry Editor and adjust the following registry value:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\FIPSAlgorithmPolicy\Enabled

0 = Federal Information Processing Standards (FIPS) is disabled.
1 = Federal Information Processing Standards (FIPS) is enabled.

You may also adjust the Group Policy setting System cryptography: Use FIPS compliant algorithms for encryption, hashing, and signing to configure this registry key.

3. In the Mage window, click File > Open and navigate to X:\Program Files\TheDotNetFactory\EmpowerID\Web Sites\EmpowerID.ClickOnce\Application Files\EmpowerIDManagementConsole_X_X_XXX_X\EmpowerIDManagementConsole.exe.manifest, where X:\ is the drive letter where EmpowerID is installed and EmpowerIDManagementConsole_X_X_XXX_X is the version of EmpowerID that is installed.

4. Copy the Dynamic-link library (DLL) of the custom component you wish to integrate into the ClickOnce manifest from C:\Program Data\CompilerTemp\ to X:\Program Files\TheDotNetFactory\EmpowerID\Web Sites\EmpowerID.ClickOnce\Application Files\EmpowerIDManagementConsole_X_X_XXX_X\

5. Bring up the Mage window again and click on the EmpowerIDManagementConsole.exe.manifest file to highlight it, then click Open. On the left hand side, click on the Files section. On the right hand side, click Populate. Click OK when prompted.

6. For each of the files you are integrating into the manifest, a Renaming files window will appear. Click Yes to these prompts. Wait until the status bar at the bottom returns to "This file is not signed" before proceeding to the next step.

7. On the left hand side, click on the Name section and increment the Version field by x.x.xxx.1. For example, if the Version field is currently 4.7.157.1, change it to 4.7.157.2

8. In the Mage window, click File > Save. In the Signing Options screen that appears, ensure that Sign with certificate file is selected. Across from the File field, click the ellipses ... and navigate to a certificate that has an enhanced key usage of 1.3.6.1.5.5.7.3.3 (Code Signing), contains a private key, and matches the ClickOnce URL being utilized by the end user. This certificate must also be added to the Personal Store using the Certificates MMC snap-in. You may use a self-signed certificate for this purpose, but please note that self-signed certificates should be used for testing only and are not recommended for production use. It is recommended to obtain the needed certificate from a trusted root Certification Authority (CA).

9. Click on the Password field and enter the password for the private key of the certificate you have chosen. The TimeStamping URI: field can be safely ignored. Click OK. The manifest file has now been updated.

10. In the Mage window, click File > Open and navigate to X:\Program Files\TheDotNetFactory\EmpowerID\Web Sites\EmpowerID.ClickOnce\EmpowerIDManagementConsole.application, where X:\ is the drive letter where EmpowerID is installed.

11. On the left hand side, click on the Name section and increment the Version field by x.x.xxx.1. For example, if the Version field is currently 4.7.157.1, change it to 4.7.157.2.

12. On the left hand side, click on the Application Reference section. Click the Select Manifest button and navigate to X:\Program Files\TheDotNetFactory\EmpowerID\Web Sites\EmpowerID.ClickOnce\Application Files\EmpowerIDManagementConsole_4_7_157_1\EmpowerIDManagementConsole.exe.manifest, where X:\ is the drive letter where EmpowerID is installed.

13. In the Mage window, click File > Save. In the Signing Options screen that appears, ensure that Sign with certificate file is selected. Across from the File field, click the ellipses ... and navigate to a certificate that has an enhanced key usage of 1.3.6.1.5.5.7.3.3 (Code Signing), contains a private key, and matches the ClickOnce URL being utilized by the end user. This certificate must also be added to the Personal Store using the Certificates MMC snap-in. You may use a self-signed certificate for this purpose, but please note that self-signed certificates should be used for testing only and are not recommended for production use. It is recommended to obtain the needed certificate from a trusted root Certification Authority (CA).

14. Click on the Password field and enter the password for the private key of the certificate you have chosen. The TimeStamping URI: field can be safely ignored. Click OK. The ClickOnce installation has now been updated.

15. To verify the custom components have been added successfully it is recommended to install the Management Console on a test workstation using the ClickOnce method. The default ClickOnce URL is https://FQDN/EmpowerIDClickOnce/empoweridmanagementconsole.application

You can also have an end user who previously installed the Management Console using the ClickOnce method close and re-launch their Management Console - it should automatically update.

Please feel free to contact us by e-mail at support@empowerid.com or by phone at (877) 996-4276 (Option 2) if you have any questions or concerns regarding this guide.

Have more questions? Submit a request

Comments

Powered by Zendesk