Andon proxy HTTPS Support¶

Overview¶

Andon proxy HTTPS support defines the process for generating a Transport Layer Security (TLS) certificate (tls.crt) and a private key (tls.key) using OpenSSL. These files are essential for enabling HTTPS on your application. The guide covers certificate generation, Subject Alternative Name (SAN) verification and deployment steps.

Prerequisites¶

Windows 11¶

• Navigate to https://git-scm.com/download/win.
• Download and run the installer. Accept the default installation options, ensuring that "Git from the command line and also from third-party software" is selected to make OpenSSL available in your path.
• Verify OpenSSL Installation:
  • Open a command prompt or Git Bash.

  • Execute the following command:

    openssl version
    

Linux Server¶

1. Check OpenSSL Installation:

   • Open a terminal.

   • Execute the following command:

     openssl version
     

   • If OpenSSL is installed, its version will be displayed.

2. Install OpenSSL (if not present):

   • Debian/Ubuntu:

     sudo apt-get update
     sudo apt-get install -y openssl ca-certificates
     

   • RHEL/CentOS/Fedora:

     sudo yum install -y openssl ca-certificates || sudo dnf install -y openssl ca-certificates
     

   • SUSE:

     sudo zypper install -y openssl ca-certificates
     

Configuration Templates (DNS vs IP)¶

Choose one of the following templates based on how clients reach your server:

# Option A: Use a DNS hostname (clients connect via name)
[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
prompt = no

[req_distinguished_name]
C = US
ST = State
L = City
O = Organization
OU = Department
CN = di2inpun6769wv0.net.plm.eds.com

[v3_req]
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = di2inpun6769wv0.net.plm.eds.com

Configuration Templates (DNS vs IP) — Option B (IP)¶

Use Option B when clients connect by IP (no DNS name). Replace 192.168.1.100 with your server IP.

[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
prompt = no

[req_distinguished_name]
C = US
ST = State
L = City
O = Organization
OU = Department
# The Common Name (CN) can be your server's IP address
CN = 192.168.1.100

[v3_req]
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
# CRITICAL: For IP addresses, you MUST use IP.X instead of DNS.X
IP.1 = 192.168.1.100

Create a new file named server.cnf and replace 192.168.1.100 with your actual server IP.

Key Terminology¶

• CN (Common Name): The primary identity of the certificate (FQDN). Example: di2inpun6769wv0.net.plm.eds.com.

• OU (Organizational Unit): Department or team identifier (e.g., IT, R&D, DevOps) for administrative tracking.

• SAN (Subject Alternative Name): Required by modern clients, must include all hostnames used to reach the service.

Execution Steps (Certificate Generation)¶

1. Open Git Bash in your working folder.

2. Run the following command to generate tls.crt and tls.key:

   openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
   -keyout tls.key \
   -out tls.crt \
   -config san.cnf \
   -extensions v3_req
   

   Output files created:

   • tls.crt — public certificate.
   • tls.key — private key. Keep this file secret and restrict file permissions.

Verification¶

Confirm the SAN contains your hostname:

openssl x509 -in tls.crt -text -noout | grep -A 1 "Subject Alternative Name"

Deployment Instructions¶

1. Navigate to the application deployment directory (where the installation package was extracted).

2. Copy files and place tls.crt and tls.key into deployment\certs\ sub-folder.

3. From the root of the deployment folder, run start-deployment.bat.

4. When the script completes, the application should be accessible over HTTPS.

Trusting the Certificate (Client Side)¶

To avoid "Not Secure" browser warnings, every computer that needs to access the application must trust the certificate.

Follow these steps on the client computer:

1. Double-click the tls.crt file.

2. Click "Install Certificate".

3. Select Local Machine and click Next.

4. Select Place all certificates in the following store.

5. Click Browse and select Trusted Root Certification Authorities.

6. Click OK, Next and Finish.

7. Restart your browser to apply the changes.

Troubleshooting & Tips¶

• Hostname mismatch warnings: Ensure CN and SAN exactly match the hostname clients use (include additional SAN entries if you support multiple hostnames).

• Key permissions: Limit read access to tls.key to the service account or administrators only.

• Certificate lifetime: The command above issues a 365-day certificate. Reissue before expiry or adjust -days as needed.

Reference Commands¶