Certificate-Based Authentication

This topic is applicable only to environments using Certificates for authentication and tenants for whom Certificate-based authentication has been enabled. Certificate-based authentication is an alternative to IP address authentication. This topic describes how an administrator can issue Certificates to one or more users via email.

1. As the administrative user who will send emails to the users needing Certificates for authentication, using an email client of your choice, create an email addressed to each user needing Certificates for authentication.
2. In the email, copy and paste the following text.
   Dear User,

   Thank you for your interest in Predix Essentials. Please follow these instructions to enable Certificate-based authentication on the devices you will use to access Predix Essentials.

   To access Predix Essentials, you must download a Certificate for your browser. To do so, please use the following link and instructions. When you select the link, you will need to log in with your standard Predix Essentials user name and password.

   Link to DCS Dashboard: <link to DCS Dashboard>

   Note: This is an unrestricted URL that can be accessed without any issues as long as you have internet access.

   Important: Once downloaded, you must run the script within 30 minutes or it will expire. If this occurs, you can follow the same link and download a new script.

   Note: Certificates for authentication expire after one year, at which point you must download and install a new Certificate for authentication.

   1. In the DCS Dashboard page, select the Script Usage Instructions link to access the Certificate-Based Authentication documentation, and then, based on whether you will install a Certificate for authentication on a Windows, Linux, or MacOSX device, follow the steps in the appropriate topic:

   • Install a Certificate on a Windows Device
   • Install a Certificate on a Linux or MacOSX Device

   2. As needed, repeat these steps to install Certificates for authentication on each device you will use to access Predix Essentials.

   After you have successfully installed a Certificate on a device, you can access Predix Essentials via the following link: <link to target system>

   If you encounter any issues, please contact an administrator.

   Thank you,

   Tenant Admin for <tenant name>

3. In the email text, replace the <link to the DCS Dashboard> text with the appropriate URL. To access the URL, in Predix Essentials, in the module navigation menu, select Admin, and then select Setup. In the Setup page, the URL appears in the DCS Dashboard URL row.
4. In the email text, replace the <link to target system> and the <tenant name> text with the appropriate values.
5. Send the email.

Complete these steps if you need to install a Certificate for authentication on a Windows device.

1. Use the link in the email you received to access the DCS Dashboard.
   The DCS Dashboard page appears.

   
2. Select the Windows button to download the appropriate script.
   The downloaded file appears in the browser page.

   
3. Select the downloaded file, and then save it in a location of your choice.
   Note: You must run the script in the downloaded file within 30 minutes of downloading it, after which the script expires.
4. Select the Start button () on the Windows taskbar, then enter powershell, and then, in the results that appear, right-click Windows PowerShell, and then select Run as Administrator, as shown in the following image.

   
5. In Windows PowerShell, enter cd <filepath>, where <filepath> is the location of the folder containing the downloaded script, and then press Enter.
6. If you receive a message indicating that a security restriction is preventing you from running the script, access Windows PowerShell, selecting the option to run the program as an administrator, and then enter the command > Get-ExecutionPolicy
7. Note the current value of the execution policy, as you will need to revert back to that value after executing the script. For example, the current value may be Restricted.
8. Run the command Set-ExecutionPolicy bypass -Force
   The command is run.

   
9. Run the following command to run the PowerShell Terminal in Admin mode: .\run-win.ps1
   The installation begins. When it is finished, in your browser, a message indicating whether or not the installation was successful appears. If you receive confirmation that the installation was successful, the Certificate installation procedure is complete. If successful, Windows PowerShell will display a screen similar to the following image.

   

   If you receive a message indicating that installation was not successful, please record the error message that you receive, and contact GE Global Support Services.
10. To revert the execution policy to its original value, run the command Set-ExecutionPolicy bypass -<x>, where <x> is the value you recorded in step 7.

Complete these steps if you need to install a Certificate for authentication on a Linux or MacOSX device.

1. Use the link in the email you received to access the DCS Dashboard, and then download the script for a Linux or MacOSX device.
   Note: You must run the script within 30 minutes of downloading it, after which the script expires.
2. Access the terminal.
3. Enter $ cd <filepath>, where <filepath> is the location of the folder containing the downloaded script, and then press Enter.
   The directory is changed to the folder in which the script is located.
4. Enter $ bash run-nix.sh, and then press Enter.