Skip to main content

Set OpCon API certificate

  • September 11, 2024
  • 5 replies
  • 627 views
AndreaDowning
Forum|alt.badge.img

Set API certificate:

This article will show you how to set an auto-signed certificate or your own signed certificate to your OpCon Rest. You'll find three scenarios :

1. Generate a new self-signed certificate if no certificate found.

2. Generate a new self-signed certificate if the existing certificate is expired.

3. Set your own signed certificate.

 

1. No certificate found:

In some cases the OpCon API is not reachable because the certificate is not find by the API, in this case you may only have to apply this procedure to allow the API to use it own auto-generated self-signed certificate :

 1. Stop the RestAPI service: SMA OpCon RestAPI

 2. Open a command prompt as Administrator

 3. Navigate to the SAM folder (for installation on the system drive C:\Program Files\OpConxps\SAM)

 4. Run the following command SMAOpConRestApi.Controllers.exe -setcertificate (for older version replace

SMAOpConRestApi.Controllers.exe by SMAOpConRestApi.OwinService)

 5. Verify the process completed successfully, the log file SMAOpConRestApi.log should tell you :

23/12/2020 11:48:40.338  Logging is set up...

23/12/2020 11:48:40.339  Configuration read successfully...

23/12/2020 11:48:40.822  Certificate created successfully.

 6. Start the SMA OpCon RestAPI service

 7. Open a browser and navigate to https://[machinename]:[TLSPort]/api/version and verify that the version information returns successfully.

 

2. Existing certificate is expired:

The certificate auto-generated by the OpCon API is valid for two years, so it can expire, for this reason or another you could have to replace the existing/old certificate by a new auto-generated self-signed certificate :

 1. Stop the RestAPI service: SMA OpCon RestAPI

 2. Open the configuration file SMAOpConRestAPI.ini

 3. Remove the value on the line CertificateSerialNumber=

 4. Open a command prompt as Administrator

 5. Navigate to the SAM folder (for installation on the system drive C:\Program Files\OpConxps\SAM)

 6. Run the following command SMAOpConRestApi.Controllers.exe -setcertificate (for older version replace

SMAOpConRestApi.Controllers.exe by SMAOpConRestApi.OwinService)

 7. Verify the process completed successfully, the log file SMAOpConRestApi.log should tell you :

23/12/2020 11:48:40.338  Logging is set up...

23/12/2020 11:48:40.339  Configuration read successfully...

23/12/2020 11:48:40.822  Certificate created successfully.

 8. Start the SMA OpCon RestAPI service

 9. Open a browser and navigate to https://[machinename]:[TLSPort]/api/version and verify that the version information returns successfully.

 10. You can go on your application Manage Computer Certificates and delete the old self-signed certificate.

 

3. Set own signed certificate:

Here you will see how to set your own signed certificate (which must be registered in the Personal certificate store) to the OpCon API :

 1. Stop the RestAPI service: SMA OpCon RestAPI

 2. Go to ..\OpConxps\SAM and open the SMAOpConRestApi.ini file. (C:\ProgramData\OpConxps\SAM for installation on the system drive)

 If you are running OpCon version 20.0 and higher ignore steps 3. and 4.

3. Make sure UseTLS=true.

4. Make sure PortForTLS has a valid port number.

5. At the line CertificateSerialNumber=, insert the custom certificate serial number value of your own certificate.

6. Save and close the configuration file.

7. Open the command prompt as administrator.

8. Navigate to the SAM folder (for installation on the system drive C:\Program Files\OpConxps\SAM)

9. Input the following, port number and certificate thumbprint

netsh http delete sslcert ipport=0.0.0.0:<port>

netsh http add sslcert ipport=0.0.0.0:<port> certhash=<certificate thumbprint> appid={1664a5b8-3de3-460a-86da-f27ed83a139a}

10. Run the following command SMAOpConRestApi.Controllers.exe -setcertificate (for older version replace

SMAOpConRestApi.Controllers.exe by SMAOpConRestApi.OwinService)

11. Go to ..\OpConxps\SAM\Log and retrieve the SMAOpConRestApi.log file to get the results of the command.

12. Start the SMA OpCon RestAPI service

13. Open a browser and navigate to https://[machinename]:[TLSPort]/api/version and verify that the version information returns successfully, and you don't have a warning on your certificate validity

 

Warning :

  • In some cases, the step 10 of the paragraph 3. is not required, so you can go through all the steps and jump from 9 to 11 and the certificate will be added to the OpCon API.
  • It is not mentioned in the OpCon documentation, signed certificate for the OpCon API need to contain a private key or the command SMAOpConRestApi.Controllers.exe -setcertificate and the API will reject your certificate.
  • Preferred format: PFX/P12/PKCS#12.
  • Please ensure that your certificate is registered in the "Trusted Root Certification Authorities" and "personal" store.

    5 replies

    MBagard
    Forum|alt.badge.img
    • MBagard
    • December 10, 2024

    For the 10th step of "Set your own signed certificate", if you get a "the parameter is incorrect" error, you can try adding simple quotes for the appid: 

    netsh http add sslcert ipport=0.0.0.0:<port> certhash=<certificate thumbprint> appid='{1664a5b8-3de3-460a-86da-f27ed83a139a}'.

     

    If you have an error "SSL Certificate add failed, Error : 1312 - A specified logon session does not exist. It may already have been terminated".

    The certificate is most likely not in the correct location, you need to import it into the local machine certificate store (certlm.msc).

    Bagard Maxence
      jhanna
      Forum|alt.badge.img+1
      • jhanna
      • October 9, 2025

      I’m adding a certificate using option #3.  Can there be other causes for the error message “SSL Certificate add failed, Error: 1312”?  I’ve added my certificate in both the Trusted Root Certification Authorities and Personal.  Would the missing private key cause this error?

       

      For the 10th step of "Set your own signed certificate", if you get a "the parameter is incorrect" error, you can try adding simple quotes for the appid: 

      netsh http add sslcert ipport=0.0.0.0:<port> certhash=<certificate thumbprint> appid='{1664a5b8-3de3-460a-86da-f27ed83a139a}'.

       

      If you have an error "SSL Certificate add failed, Error : 1312 - A specified logon session does not exist. It may already have been terminated".

      The certificate is most likely not in the correct location, you need to import it into the local machine certificate store (certlm.msc).

       

       

      Janice
      M
      Forum|alt.badge.img
      • Minniem3
      • March 11, 2026

      can all these tasks be automated using the script feature?
      Can’t OpCon able to stop/restart and so?
      If not why?

      AndreaDowning
      Forum|alt.badge.img
      • AndreaDowning
      • Author
      • Continuous Community Team
      • April 9, 2026

      ​@Minniem3 Sorry for the delay in getting a response back to you. Here is information from our OpCon Wizard about automating the tasks using the script feature.

      Since the SMA OpCon RestAPI service will be offline during parts of this process, the entire certificate renewal workflow should be built as a single, self-contained script rather than relying on OpCon to trigger each step individually. Once the RestAPI is stopped, OpCon can no longer communicate mid-process, so the script itself must carry the logic from start to finish.

      What the script does

      1. Stop the RestAPI service — Brings down the SMA OpCon RestAPI Windows service and waits to confirm it has fully stopped before proceeding.
      2. Clear the CertificateSerialNumber (renewal only) — Uses PowerShell to blank the CertificateSerialNumber value in the .ini file. Only required when renewing an expired certificate.
      3. Run the -setcertificate command — Executes the command-line call directly within the script and captures output for logging.
      4. Start the RestAPI service — Brings the service back online and waits to confirm it reaches a running state.
      5. Verify the log for success — Parses SMAOpConRestApi.log for "Certificate created successfully" and exits with an appropriate success or failure code.

      How to invoke it in OpCon

      Since the RestAPI will be down mid-execution, you will want to kick off this script before the service stops, meaning the job that launches the script should be triggered while OpCon is still fully operational. Use one of the following options:

      • Embedded Script job (PowerShell) — Recommended, as it keeps everything version-controlled within OpCon.
      • Windows Command job — Points to a .ps1 or .bat file stored locally on the server.

      Important caveats

      Administrator privileges are required. The script must run under an account with local Administrator rights on the target machine, especially if you are binding a custom certificate via netsh commands (Scenario 3). Configure this in the job's Run as User settings within OpCon.

      No mid-script OpCon feedback — Since the RestAPI is down during execution, any OpCon event-driven logic such as notifications or job dependencies will not fire until the service is restored. Build your success and failure handling inside the script itself, for example by writing to a log, sending an SMTP alert, or exiting with a specific error code that OpCon reads upon completion.

      Sample script

      # ============================================================

      # SMA RestAPI Certificate Renewal Script

      # Run this script under an account with Administrator privileges

      # ============================================================

       

      $ServiceName     = "SMA_RestApi"

      $IniFilePath     = "C:\ProgramData\OpConxps\SAM\SMAOpConRestApi.ini"

      $SetCertExe      = "C:\Program Files\OpConxps\SAM\SMASetCertificate.exe"

      $LogFilePath     = "C:\ProgramData\OpConxps\SAM\Log\SMAOpConRestApi.log"

      $SuccessString   = "Certificate created successfully"

       

      # ============================================================

      # STEP 1 — Stop the RestAPI Service

      # ============================================================

       

      Write-Host "Stopping $ServiceName..."

       

      Stop-Service -Name $ServiceName -Force -ErrorAction Stop

       

      # Wait to confirm service is fully stopped

      $timeout = 30

      $elapsed = 0

      while ((Get-Service -Name $ServiceName).Status -ne "Stopped") {

          Start-Sleep -Seconds 2

          $elapsed += 2

          if ($elapsed -ge $timeout) {

              Write-Error "Timed out waiting for $ServiceName to stop. Exiting."

              exit 1

          }

      }

       

      Write-Host "$ServiceName stopped successfully."

       

      # ============================================================

      # STEP 2 — Clear CertificateSerialNumber in .ini File

      #           (Only needed if renewing an expired certificate)

      # ============================================================

       

      Write-Host "Clearing CertificateSerialNumber in .ini file..."

       

      if (Test-Path $IniFilePath) {

          $iniContent = Get-Content $IniFilePath

          $iniContent = $iniContent -replace "(?i)^(CertificateSerialNumber\s*=).*", '$1'

          Set-Content -Path $IniFilePath -Value $iniContent

          Write-Host "CertificateSerialNumber cleared successfully."

      } else {

          Write-Error "INI file not found at $IniFilePath. Exiting."

          exit 1

      }

       

      # ============================================================

      # STEP 3 — Run the -setcertificate Command

      # ============================================================

       

      Write-Host "Running -setcertificate command..."

       

      if (Test-Path $SetCertExe) {

          $result = & $SetCertExe -setcertificate

          Write-Host "Certificate command output: $result"

      } else {

          Write-Error "SetCertificate executable not found at $SetCertExe. Exiting."

          exit 1

      }

       

      # ============================================================

      # STEP 4 — Start the RestAPI Service

      # ============================================================

       

      Write-Host "Starting $ServiceName..."

       

      Start-Service -Name $ServiceName -ErrorAction Stop

       

      # Wait to confirm service is fully running

      $elapsed = 0

      while ((Get-Service -Name $ServiceName).Status -ne "Running") {

          Start-Sleep -Seconds 2

          $elapsed += 2

          if ($elapsed -ge $timeout) {

              Write-Error "Timed out waiting for $ServiceName to start. Exiting."

              exit 1

          }

      }

       

      Write-Host "$ServiceName started successfully."

       

      # ============================================================

      # STEP 5 — Verify Log for Success

      # ============================================================

       

      Write-Host "Checking log for success confirmation..."

       

      # Give the service a moment to write to the log

      Start-Sleep -Seconds 5

       

      if (Test-Path $LogFilePath) {

          $logContent = Get-Content $LogFilePath -Tail 50

          if ($logContent -match $SuccessString) {

              Write-Host "SUCCESS: Certificate renewal confirmed in log."

              exit 0

          } else {

              Write-Error "FAILURE: Success string not found in log. Manual review required."

              exit 1

          }

      } else {

          Write-Error "Log file not found at $LogFilePath. Manual review required."

          exit 1

      }

      M
      Forum|alt.badge.img
      • Minniem3
      • April 14, 2026

      Thank you this.😊

      Terms & ConditionsCookie settingsAccessibility statement