Installing a valid SSL Web certificate in Access Server

Upgrade to Latest Version

Introduction

OpenVPN Access Server’s web services secure the connection between the web browser and the web server using an SSL certificate. When you install Access Server, it generates a self-signed certificate so you can start and use the web server. This produces the inevitable warnings in the web browser like "Unable to verify authenticity" or other ominous messages. With a self-signed certificate, these messages are expected. To connect to the web services initially, you must bypass this warning message.

We recommend installing a signed SSL certificate for an FQDN (Fully Qualified Domain Name) for reaching your web services — the Admin Web UI and the Client UI — in a web browser. It requires these steps:

  1. Set up an FQDN DNS record.
  2. Assign this to your Access Server installation.
  3. Generate a private key.
  4. Use the key to create a CSR (Certificate Signing Request).
  5. Send the CSR to a trusted party to validate and sign.
  6. Install the signed certificate, private key, and intermediary file on your Access Server.

With these completed, the web interface is automatically trusted and shows a green padlock icon in most web browsers to indicate that the connection is trusted and secure.

This document covers the following:

  • An explanation of why you should install an SSL certificate.
  • How to generate a certificate signing request (CSR) for submission to a commercial certificate authority (CA).
  • How to install a commercial SSL certificate in Access Server.
  • Some common problems and solutions.
  • How to extend the self-signed certificate validity or change the common name of the self-signed certificate.
  • How to revert Access Server to a self-signed certificate (removing a commercial SSL certificate).

Note: The SSL web certificates are not related to VPN certificates as those are separate and managed in a different way. Alterations to the web certificates don’t affect VPN certificates.

Why should you replace the SSL certificate?

OpenVPN Access Server comes with self-signed certificates, which lead to warnings in web browsers. While the connection between the web browser and the web server is encrypted, and you can use the fingerprint of the SSL web certificate to provide proof of identity, this identity verification is a manual process. Web browsers use a method of trust that allows the automatic establishment of identity and trust of the web server by its FQDN, its web certificate, and a chain of trust leading up to a trusted root authority. This ensures that when you visit the Access Server's web interface for the first time from any device, it can establish identity and trust automatically. This helps to avoid Man-in-the-Middle (MitM) attacks.

We recommend replacing the SSL web certificate so you no longer receive warning messages and you enhance security. When you have things set up properly with a signed and verified SSL web certificate, your web browser displays the padlock icon in the browser's address bar for the secure connection.

We also have more information about what an SSL certificate is and how it works here.

Generate a Certificate Signing Request

To generate the proper keying materials for your Access Server software, you need a machine with OpenSSL installed. You can do this on a Linux system, such as the system running your OpenVPN Access Server.

Check if OpenSSL is installed:

  1. Sign in to your server.
  2. Obtain root privileges.
  3. See if OpenSSL is installed (if it is, skip the next step for installing it — if you get an error, you need to install it):
    openssl version

Install OpenSSL (if needed):

Install OpenSSL on Debian/Ubuntu systems:

apt-get install openssl

Or on CentOS/Red Hat systems:

yum install openssl

Generate a private key and certificate signing request:

With OpenSSL installed, create a private key and certificate signing request (4096 bits SHA256):

openssl req -out server.csr -new -newkey rsa:4096 -sha256 -nodes -keyout server.key

Answer the set of standardized questions. This is how we answered it in our example situation:

Country Name (2 letter code) [AU]: US
 State or Province Name (full name) [Some-State]: California
 Locality Name (eg, city) []: San Francisco
 Organization Name (eg, company) [Internet Widgits Pty Ltd]: Exampletronix, Inc.
 Organizational Unit Name (eg, section) []: IT Support
 Common Name (eg, YOUR name) []: vpn.exampletronix.com <- This is the FQDN name for your server.
 Email Address []:support@exampletronix.com
Please enter the following 'extra' attributes
 to be sent with your certificate request
 A challenge password []:
 An optional company name []:

In the example above, we didn't specify a challenge password or optional company name. Some certificate authorities don't let you specify an optional company name or know how to deal with a challenge password, so we recommend leaving those last two questions unanswered. You now have a server.key and a server.csr file.

The server.key file is the private key; ensure you keep it safe and secure. You will need this file once your certificate signing request has been approved and a certificate has been issued to you. Also, it is the underpinning of the SSL certificate security model. This private key stays with you and does not go to any other party.

The server.csr file is the certificate signing request. In the questions above, you provide a "Common Name," which is the FQDN name of your Access Server. For example, if you sign in to the Client Web UI with this address, https://vpn.exampletronix.com/, the Common Name is vpn.exampletronix.com. In our example, our certificate signing request is for the subdomain vpn.exampletronix.com on the domain exampletronix.com.

Get your SSL certificate

Now you’re ready to get an SSL certificate from a registered certificate authority (CA). 

Ensure you provide or choose the following to the certificate authority:

  • Your certificate signing request (CSR).
  • Apache or Apache2 compatible (we don’t use Apache software, but Access Server uses that same type of certificate).
  • Your server URL or domain.

Typically, the next step includes verification that you own the domain. The certificate authority might use one of these methods to do that:

  • Requiring you to place a file on your webserver the CA can retrieve.
  • Using a verification email sent to a registered email address on the domain.

Once they've verified your identity and received payment, they'll sign a certificate and send it to you. They'll also send you intermediary files, or they may have these available separately on their website. Intermediary files are separate certificates that complete the chain of trust between the certificate and a root certificate authority trusted by most web browsers and SSL-capable programs. Without the intermediary files, it may not be possible to establish a chain of trust between your signed public certificate and a trusted certificate authority.

Installing a commercial SSL certificate in Access Server

In this section, we describe the steps to install a commercial SSL certificate in Access Server via the Admin Web UI. But it can also be done via the command line. To install the certificate on your Access Server installation, you need these files:

  • The signed certificate from your certificate authority.
  • The CA bundle or intermediary files from your certificate authority.
  • The private key you created when making the certificate signing request (CSR).

A few notes about these files

Ensure these files are formatted with an Apache compatible format, also referred to as X509/Base64 or PEM/CER format. If the files are .p12 or .pfx format, those formats are suitable for Windows platforms but not for the Linux OpenVPN Access Server product. You can convert the certificates to the required format using a utility such as the DigiCert Certificate Utility.

The CA (Certificate Authority) bundle — or the intermediary files — is a set of certificates that complete the chain of trust between your signed certificate for your server and a root certificate authority trusted by web browsers and other SSL-capable programs. Without these files, web browsers will still display your certificate as being untrusted. The CA bundle may be a single file or separate files, and you need them to be in one file. If you have separate files, resolve this by opening them up in a text editor like Wordpad or notepad, copy and paste one after the other into a new file, and save the file as the CA bundle or intermediary file.

The private key must be the same private key you created and used to create the certificate signing request. You cannot use any other private key with the signed certificate. They are inextricably linked. If you have made the mistake of losing the original private key, your signed certificate is useless, and you must start over.

Installation steps in Admin Web UI

To install a commercial SSL certificate:

  1. Sign in to the Admin Web UI.
  2. Click Configuration > Web Server.
  3. Under Do you want to change the web server certificate? Click Yes for User-provided Certificate.
  4. Provide the three files necessary by clicking Choose File for the CA Bundle, Certificate, and Private Key.
  5. Click Save Settings and Update Running Server.

Recovering stored keys and certificates

Access Server stores the CA Bundle, Certificate, and Private Key files in the configuration database. If you’ve encountered an issue and the files got lost, you can retrieve them from the configuration database. Refer to Recovering SSL web certificates from the config DB.

Self-signed certificate behavior in Access Server

OpenVPN Access Server comes with a self-signed certificate. With the above instructions, you can load your own certificate. If you wish to learn more about how Access Server uses and manages the self-signed certificate, refer to Self-signed SSL web certificate behavior in Access Server.

Troubleshooting

Use our troubleshooting tips for the following error messages if you encounter issues.

Certificate doesn't match private key

This message occurs when your private key doesn’t match the one you used to sign the CSR submitted to your certificate authority. Ensure you use the same key file you used to generate your CSR.

If you lost this file, restart the certificate generation process and ask your certificate authority for a certificate replacement. The private key is unique and can’t be recreated. If you've lost it, the signed public certificate also becomes useless.

Problems getting password, bad password read

This message occurs when your private key is encrypted with a passphrase, and Access Server doesn’t know how to decrypt the private key (i.e., it doesn’t know the passphrase).

To resolve:

  1. Decrypt your private key by running this example command on the command line with the OpenSSL program.
    openssl rsa -in server.key -out decrypted.key
  2. Provide your passphrase.
  3. Load the resulting decrypted private key file into your Access Server.

OpenVPN Access Server doesn’t support passphrase-encrypted private key files for the web services.

PEM_read_bio, no start line

This is usually part of an error message like this:

Private Key Load Error [('PEM routines', 'PEM_read_bio', 'no start line')] (OpenSSL.crypto.Error)

This error occurs with an invalid private key. Ensure you provide the correct file. Check that you didn’t accidentally supply your public certificate as the private key, or vice-versa. The private key field in Access Server only accepts a valid private key.

If you’re sure the file is valid, check the formatting of the private key file. For example, without line breaks or with line breaks using a different EOL (End-of-Line) standard that isn’t acceptable. You may try to manually fix this problem yourself with proper EOL conversion tools or by contacting your certificate authority for assistance. We often see this problem with certain providers of SSL certificates that generate the private key for you. They may be providing it with Windows-type EOL characters, which can cause a problem. Usually, they can help you obtain a Linux-compatible version, or you can use a text editing tool to convert the file format to a type that doesn't contain these additional characters.

Certificate doesn't match private key, unsupported certificate purpose

The file supplied seems like valid keying material, although it doesn't look like a server certificate was provided. It’s possible that the CA bundle and the server certificate were accidentally swapped. Try to swap the order of the CA bundle and the certificate and try again. If this doesn’t work, make sure you provide the signed certificate you received from your CA, not the CSR you have generated on your machine. The CSR is not needed or wanted by OpenVPN Access Server; it’s only used to make the certificate signing request with your certificate authority.

Certificate Trust Warning: unable to get local issuer certificate

This message can occur in a variety of programs that try to verify the identity of a server using its public certificate. It can happen in OpenVPN Connect, but it can also occur in a web browser or a test program for SSL connections. The error occurs when the path from your server's certificate to a trusted root authority certificate can’t be established. Certificates are hierarchical, and each certificate knows its direct parent above it using a unique fingerprint. Using this method a chain can be formed going from your server certificate, to the certificate issuer, and from there to a (trusted) root authority. Sometimes there are more steps. Sometimes the direct parent is the root authority. But in most cases, there are steps in between called intermediaries. If there is one, only one intermediate certificate needs to be added to your chain of certificates. If there are more, you can copy-paste them into one file, one after the other, to make an intermediary bundle file containing all the intermediaries to complete the path of trust. If you already had a working certificate before but now have a new one from a different issuer, you will also need to update your intermediaries.

On the OpenVPN Connect v2 client, the intermediaries are stored on disk with the client, and to update this, you would need to update OpenVPN Connect v2. We recommend you use the same issuer when you need to renew a certificate and your clients are using OpenVPN Connect v2 with server-locked profiles. It doesn't make for user-locked and auto-login as the web interface only gets called when using server-locked.

On the OpenVPN Connect v3 client, we use the certificate store in the operating system to determine a path of trust.