Skip to main content

Trust SSL Certificate Guide

This guide explains how to trust the self-signed CA certificate on different operating systems and browsers so your HTTPS connection works without warnings.

📋 Table of Contents​

🍎 macOS​

Via Keychain Access​

  1. Locate the certificate file:

    • Open Finder and navigate to the certs folder
    • Find the file ca-cert.pem

  2. Import the certificate:

    • Double-click ca-cert.pem
    • In the popup dialog, select "login" keychain
    • Click "Add"
    • Enter your macOS password if prompted

  3. Trust the certificate:

    • Press Cmd + Space and type "Keychain Access" to open the app
    • In the left sidebar, click "login" keychain
    • In the bottom-left category selector, choose "Certificates"
    • Search for "localhost" in the search box (top right)

  4. Set trust level:

    • Double-click the "localhost" certificate
    • Click the ▶ triangle next to "Trust" to expand the section
    • Change "When using this certificate" dropdown to "Always Trust"
    • Optionally, set "Secure Sockets Layer (SSL)" to "Always Trust"

  5. Save changes:

    • Close the certificate window
    • Enter your macOS password when prompted

  6. Restart your browser (important!)

  7. Test: Visit https://localhost:8443 - should show secure! 🔒

Remove Certificate from macOS​

Via Keychain Access:

  1. Open Keychain Access
  2. Find "localhost" certificate
  3. Right-click → Delete "localhost"
  4. Enter password

Via Command Line:

# From login keychain
security delete-certificate -c "localhost" ~/Library/Keychains/login.keychain-db

🪟 Windows​

Via Certificate Manager​

  1. Open Certificate Manager:

    • Press Win + R to open Run dialog
    • Type certmgr.msc and press Enter
    • Or search for "Manage user certificates" in Start menu

  2. Import the certificate:

    • In the left panel, expand "Trusted Root Certification Authorities"
    • Right-click on "Certificates" folder
    • Select Action → All Tasks → Import...

  3. Certificate Import Wizard:

    • Click "Next"
    • Click "Browse..." and navigate to your certs folder
    • Change file type filter to "All Files (.)"
    • Select ca-cert.pem
    • Click "Open" then "Next"

  4. Choose certificate store:

    • Select "Place all certificates in the following store"
    • Ensure it says "Trusted Root Certification Authorities"
    • Click "Next" then "Finish"
    • Click "OK" on the success message

  5. Verify installation:

    • In Certificate Manager, navigate to "Trusted Root Certification Authorities" → "Certificates"
    • You should see "localhost" or "Development" in the list
    • Double-click to view details

  6. Restart your browser (close all windows completely)

  7. Test: Visit https://localhost:8443 - should show secure! 🔒

Remove Certificate from Windows​

  1. Open Certificate Manager (certmgr.msc)
  2. Navigate to "Trusted Root Certification Authorities" → "Certificates"
  3. Find "localhost" certificate
  4. Right-click → Delete
  5. Confirm deletion

🦊 Firefox (All Platforms)​

Firefox uses its own certificate store, independent of the operating system.

Import Certificate to Firefox​

  1. Open Firefox Settings:

    • Click menu (☰) → Settings
    • Or type about:preferences in the address bar

  2. Navigate to Privacy & Security:

    • Click "Privacy & Security" in the left sidebar
    • Or go directly to about:preferences#privacy

  3. Access Certificates:

    • Scroll down to the "Security" section
    • Find "Certificates" heading
    • Click "View Certificates..." button

  4. Import CA Certificate:

    • In the Certificate Manager window, click the "Authorities" tab
    • Click "Import..." button
    • Navigate to your certs folder
    • Select ca-cert.pem
    • Click "Open"

  5. Set trust options:

    • In the popup dialog, check:
      • ✅ "Trust this CA to identify websites"
      • ✅ "Trust this CA to identify email users" (optional)
    • Click "OK"

  6. Verify import:

    • In the Authorities tab, look for "Development" or organization name
    • Expand it to find "localhost"

  7. Close and restart Firefox

  8. Test: Visit https://localhost:8443 - should show secure! 🔒

Remove Certificate from Firefox​

  1. Go to about:preferences#privacy
  2. Click "View Certificates"
  3. Click "Authorities" tab
  4. Find "Development" → "localhost"
  5. Select it and click "Delete or Distrust..."
  6. Confirm deletion

Troubleshooting​

Still seeing "Not Secure" warning?​

  1. Restart your browser - Browsers cache certificate trust settings
  2. Check the certificate is in login keychain - Look in Keychain Access
  3. Verify trust settings - Must be set to "Always Trust"
  4. Clear browser cache - Especially SSL state
  5. Check hostname - Must use localhost, not 127.0.0.1

Browser not trusting certificate?​

Chrome/Edge (Windows):

  • These browsers use the Windows certificate store
  • Make sure you imported to "Trusted Root Certification Authorities"
  • Restart the browser completely

Chrome/Safari (macOS):

  • These browsers use the macOS Keychain
  • Make sure certificate is in "login" keychain
  • Trust must be set to "Always Trust"
  • Restart the browser completely

Firefox (All Platforms):

  • Firefox has its own certificate store
  • See Firefox section above
  • Must import the certificate directly into Firefox

Certificate Details​

CA Certificate (ca-cert.pem):

  • Type: Root CA Certificate
  • Validity: 5 years (1825 days)
  • Purpose: Sign server certificates
  • Trust: Add to system trust store

Server Certificate (cert.pem):

  • Type: Server Certificate
  • Validity: 2+ years (825 days)
  • Signed by: Our CA
  • Hostnames: localhost, *.localhost, 127.0.0.1
  • Purpose: HTTPS server

Private Keys:

  • ca-key.pem: CA private key (password protected)
  • key.pem: Server private key (no password for convenience)

Security Notes​

⚠️ These certificates are for local development only!

  • Never use these certificates in production
  • Keep ca-key.pem secure (it can sign certificates)
  • The CA password is: uiplatform (change if needed)
  • Don't commit private keys to version control
  • Add to .gitignore: *.pem, *.key

Regenerate Certificates​

If you need to regenerate the certificates:

cd ssl
./generate-certs.sh

Then re-trust the new CA certificate using the steps above.