Customizing the 3DEXPERIENCE Launcher Domain Name and Certificate for HTTPS Communication

The current launcher URL https://dslauncher.3ds.com may introduce two IT concerns that you can work around by customizing the launcher domain and certificate:

  • a security certificate that is generated by a third party is needed: to be able to verify its revocation status, a connection to internet is required, whereas on certain sites, end-user machines may not have access to the internet
  • the URL is not located inside a client network, which violates certain proxy, anti-virus or firewall rules

To avoid these difficulties, customize the launcher URL during the installation and the configuration. This allows you to specify a URL compatible with your proxy, anti-virus and firewall rules, and to generate your own security certificate.

You can customize your launcher setup by:

  • installing the launcher in a special mode that will not install the standard certificate/domain
  • setting a specific domain to be used by the launcher itself.

To comply with security needs, HTTPS allows securing the communication to and from the launcher. Therefore, the launcher must use a specific URL domain to be able to set up HTTPS communication, which also uses a specific type of certificate from the server to encrypt the communication. This type of certificate is only associated with the domain in which it will be used. The standard domain for the launcher is: dslauncher.3ds.com.

  1. Uninstall the existing 3DEXPERIENCE launcher if available.
    1. Select the Start > Control Panel > Programs > Programs and Features then double-click the Uninstall a Program control, and select 3DEXPERIENCE Launcher.

      A User Account Control (UAC) dialog box appears. Enter a username and a password with administration privileges.

    2. Remove the following remaining directories:

      • C\:Program Files\Dassault Systemes\3DEXPERIENCE Launcher
      • C\:ProgramData\DassaultSystemes\3DEXPERIENCE Launcher

  2. Install the launcher as follows:
    1. On the Windows desktop, select the Start > Control Panel > System > Advanced System Settings.
    2. Click Environment Variables and in both the User and System variables fields, set the following variable:DSYLauncherSkipDomainInstall with the value as 1.

      After the variable set up, the installation will not install the default template and will not start the 3DEXPERIENCE Launcher service at the end of the installation.

    3. Go to the directory that contains the launcher's MSI file, for example:C:\Program Files\Dassault Systemes\B424\Win_b64\resources\MSI
    4. Double-click the 3DEXPERIENCELauncher.msi file to start the installation.

      A User Account Control (UAC) dialog box appears.

      Enter a username and password with administration privileges. Continue to the end of the installation.

  3. Customize the domain name and port for the launcher:

    Create two files in the launcher installation folder:

    C\:Program Files\Dassault Systemes\3DEXPERIENCE Launcher

    The launcher reads these files during the startup to set up the HTTPS server context. Name the file as follows:

    • serv.domain: must contain the given domain to use, on a single line, for example: launcherdomain.mycom.com
    • serv.port: must contain the given port to use, on a single line. We strongly recommend that you use one of the following launcher default ports (20300, 33200, 40600) to facilitate the use of the launcher: 20300

  4. Install your own HTTPS certificates:

    Import the target certificates on the client machine in the Local Computer repository under the Trusted Root Certification Authorities, Intermediate Certification Authorities and the Personal sections before associating the launcher port and your certificates.

    If you are running Edge or Chrome:

    1. Go to the Start menu and enter the following command in the field:mmc to display the management console.
    2. Click File > Add/Remove Snap-in ….
    3. Click Certificates > Computer account. Click Next , then Finish, then OK to return to the main management console window that displays the Certificates (Local computer). Expand this node to see the sub-nodes.
    4. Right-click the Trusted Root Certification Authorities category.

      Click All Tasks > Import, then select the file ca.cert.pem and import it. For example: E:\MyCertificateAuthority\ca\certs\ca.cert.pem.

    5. Right-click the Intermediate Certification Authorities category.

      Select All Tasks -> Import, then select the file intermediate.cert.pem and import it. For example: E:\MyCertificateAuthority\ca\intermediate\certs\intermediate.cert.pem.

    6. Right-click the Personal category.

      Select All Tasks -> Import, then select the file launcherdomain.mydomain.com.pkcs12 and import it. For example: E:\MyCertificateAuthority\ca\intermediate\certs\launcherdomain.mydomain.com.pkcs12.

    If you are running Firefox:

    1. Open Firefox and select Tools> Options and go to Privacy&Security
    2. Select Security > > Certificates > View Certificates to access the certificate manager.
    3. Locate the Authorities category.

      Select the file ca.cert.pem and import it. For example: E:\MyCertificateAuthority\ca\certs\ca.cert.pem.

      Then select the file intermediate.cert.pem and import it. For example: E:\MyCertificateAuthority\ca\intermediate\certs\intermediate.cert.pem.

    4. Locate the Your Certificates category.

      Select the file launcherdomain.mydomain.com.pkcs12 and import it. For example: E:\MyCertificateAuthority\ca\intermediate\certs\launcherdomain.mydomain.com.pkcs12.

  5. Associate the port with your imported certificates:

    Windows needs to know the port on which communication will take place and the certificate to use for the HTTPS encryption.

    Use the netsh Windows command to associate a given certificate to specific port. In a command prompt window (run as Administrator), enter the following command:

    netsh http add sslcert ipport=0.0.0.0:[PORT] certhash=[CHASH] appid=[APPID] sslctlstorename=MY

    where:

    PORT
    The selected port on which the server set up the communication: 20300. It must be the same value as specified in the serv.port file.
    CHASH
    The thumbprint of the target certificate.

    Make sure you remove the spaces (if any) between the numbers:

    11 20 62 8c 13 2c 55 e8 52 3a 93 88 9b b0 f3 fe c3 2c 76 63

    is:

    1120628c132c55e8523a93889bb0f3fec32c7663

    APPID
    guid of the launcher that must be set to: {3073489c-ec98-4161-8379-1208180f6d9b}

    This value is hard-coded.

    MY
    Certificate Trust List Store Name (CTL Store Name). In our case: MY.

    For example, in a command prompt window (run as Administrator), enter the following command:

    netsh http add sslcertipport=0.0.0.0:20300
certhash=1120628c132c55e8523a93889bb0f3fec32c7663 appid={3073489c-ec98-4161-8379-1208180f6d9b}
sslctlstorename=MY
SSL Certificate successfully added

    To confirm that the configuration is correct, check the recorded contexts by running the following command:

    netsh http show sslcert ipport=0.0.0.0:[PORT]

    This command will display all contexts associated with the given ipport.

    In a cmd window (run as Administrator), enter the following command:

    C:\windows\system32> netsh http show sslcert ipport=0.0.0.0:20300

    to display output like this:

    SSL Certificate bindings:
IP:port                   :         0.0.0.0:20300
Certificate Hash          :         1120628c132c55e8523a93889bb0f3fec32c7663
Application ID            :         {3073489c-ec98-4161-8379-1208180f6d9b}
Certificate Store Name    :         (null)
Verify Client Certificate Revocation                   : Enabled
Verify Revocation Using Cached Client Certificate Only : Disabled
Usage Check               :         Enabled
Revocation Freshness Time :         0
URL Retrieval Timeout     :         0
Ctl Identifier            :         (null)
Ctl Store Name            :         MY
DS Mapper Usage           :         Disabled
Negotiate Client Certificate    :   Disabled

  6. Edit the Windows /etc/hosts file:

    This file allows you to specify to Windows that a specific domain must be resolved to a specific IP. In our case, you need to set redirection for the target domain name to localhost IP (both IPV4 and IPV6).

    Add the following lines to the %SystemRoot%\System32\drivers\etc\hosts file:

    127.0.0.1 [DOMAIN]
 ::1 [DOMAIN]

    where [DOMAIN] is the target domain name to use. So in our example, this would be:

    127.0.0.1 launcherdomain.mycom.com
 ::1 launcherdomain.mycom.com

  7. Restart your computer.

    The launcher is ready to be used with the new domain name, but for reliability reasons, we recommend that you restart the computer that in turn restarts the 3DEXPERIENCE Launcher service.

  8. Test that the launcher has been correctly configured:

    Enter the following URL containing your customized domain name in your browser:

    https://launcherdomain.mycom.com:20300/iframe

    If the launcher has been correctly configured, the following message will be displayed in the browser window:

    Communication Frame V0.1

  9. Customize the domain name on the 3DEXPERIENCE platform:

    Log in to the 3DEXPERIENCE platform as platform Administrator. In the Platform Management dashboard, click the Members tab, then click Configure Apps Installation, and enter the customized URL (with the protocol but without the port):

    https://launcherdomain.mycom.com

    in the 3DEXPERIENCE Launcher setting field. This setting will override the 3DEXPERIENCE platform default.

  10. Make sure that you update the launcher configuration when necessary.

    Typical maintenance and updating operations are:

    • updating the HTTPS certificate, refreshing certificate validity or changing the port

      You may need to replace the certificate (or the port) used for HTTPS communication: for example, when your certificate is about to expire, or when you want to change the domain name or the port in use. This involves removing the old configuration or the current certificate/ipport association, by running the following command:

      netsh http delete sslcert ipport=0.0.0.0:[PORT]

      For example, running the following command in a command prompt window (run as Administrator):

      C:\Windows\system32>netsh http delete sslcert ipport=0.0.0.0:20300

      displays the following message:

      SSL Certificate successfully deleted

      To refresh certificate validity, you just have to re-associate the certificate (or port) to the given port (or certificate) by performing step 5 again. Keep in mind that a new certificate also involves a new thumbprint.

    • changing the domain name: perform steps 3 to 6 again (along with specific compass and DNS-specific configuration).
    • uninstall or upgrade the 3DEXPERIENCE launcher after importing your own custom certificate: If you have changed the certificate in use, we strongly recommend that you remove the outdated certificate from the Windows certificate repository to avoid confusion.

      The launcher may be upgraded either manually through the launcher's MSI or by installing a new media that may contain a new version of the launcher. Upgrading removes the custom certificate. To prevent removal of the custom certificate, make sure the DSYLauncherSkipDomainInstall environment variable is still set.