Installing a valid SSL Web certificate in Access Server
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 that the web server can at least start up and be used. This produces the inevitable warnings in the web browser like "Unable to verify authenticity" or other such 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:
- Set up an FQDN DNS record
- Assign this to your Access Server installation
- Generate a private key
- Use the key to create a CSR (Certificate Signing Request)
- Send the CSR to a trusted party to validate and sign
- 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 article will cover the following:
- An explanation 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 to these problems.
- 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. Those are separate and managed in a different way. Alterations to the web certificates will have no effect on VPN certificates.
Why should you replace the SSL certificate?
OpenVPN Access Server comes with self-signed certificates at first. You may have noticed when you started using Access Server for the first time, that you get warnings like warning: your connection is not private or could not verify identity of this server or such dire messages. While the connection between web browser and web server is still 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 can use a method of trust that allows 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.
So to answer the question as to why you should replace the SSL web certificate on the Access Server's web interface, you should do so to ensure that the warning messages on the web interface go away, and you can enhance security. If you have things set up properly with a signed and verified SSL web certificate, you will see the padlock icon in the browser's address bar, and not have to override any security warnings.
We also have some more information about what an SSL certificate is and how it works here.
Generate a Certificate Signing Request
To order to generate the proper keying materials for your Access Server software, you will need a machine with OpenSSL installed. This is most easily done on a Linux system, like for example the Linux operating system that your OpenVPN Access Server is running on. To see if you have OpenSSL already installed try logging on to your Linux server and obtain root privileges and then using the commands below. If you do not have OpenSSL installed, then use the indicated commands below to install it.
See if OpenSSL is installed:
If you get an error use this to install on Debian/Ubuntu systems:
apt-get install openssl
Or on CentOS/Red Hat systems:
yum install openssl
Now that OpenSSL is installed you can use it to 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
You will be asked a 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 :email@example.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 it's our recommendation to leave those last two questions unanswered and just press enter on them to continue. With the steps followed as above we now have a server.key and a server.csr file.
The server.key file is the private key and it is vital that this key is kept 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 were asked to provide a "Common Name". That is where the FQDN name where your Access Server can be reached on the Internet is supposed to go. If for example your Access Server has been set up at the address https://vpn.exampletronix.com/ then the Common Name is vpn.exampletronix.com just like in our example. This means that in our example, our certificate signing request is going to be for the subdomain vpn.exampletronix.com on the domain exampletronix.com.
Now you can go to your chosen SSL certificate authority. There are a great many out there. Pick one you like and they will ask you for a certificate signing request and what type of server you are looking to get a certificate for. If asked, the type of certificate you will want is Apache or Apache2 compatible. We don't actually use Apache software in our OpenVPN Access Server product, but we do use that same type of certificates.
Next copy and paste the contents of the file server.csr or upload it to them as a file. They will then look at it and see the answers you gave earlier. Now comes the part where they are going to try to verify that you are really the owner of the domain exampletronix.com. One way they can do this is to ask you to place a file on your web server, which they will then try to retrieve. Or they can send a verification email to a registered email address that is known at the domain registry for the domain exampletronix.com. These steps they do to ensure that they are dealing with the real owner of the domain exampletronix.com and not with someone pretending to be. Only the real owner would have access to the registered email address or the website running on the domain you are trying to get a certificate signed for.
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 their own certificates that complete the chain of trust between the certificate they're just issued you, and a root certificate authority that is trusted by the majority of 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
This guide shows you how to install a commercial SSL certificate in the Access Server via the Admin UI. But it can also be done via the command line. To be able to install the certificate on your Access Server installation, you will need these files:
- The signed certificate from your certificate authority.
- The CA bundle or intermediary files from your certificate authority.
- The private key you originally created when making the certificate signing request (CSR).
A few notes about these files. The format they should be in is Apache compatible format, also referred to as X509/Base64 or PEM/CER format. If you have mistakenly received files in .p12 or .pfx format or such, then those are of a type that are suitable for Windows platforms, but not for the Linux OpenVPN Access Server product. It is however possible to convert the certificates to the required format using for example the DigiCert Certificate Utility.
The CA (Certificate Authority) bundle, or also called intermediary files, are a set of certificates that complete the chain of trust between your signed certificate for your server, and a root certificate authority that is trusted by web browser and other SSL capable programs. Without these files the certificate may still show up as being untrusted or some errors may show up when trying to verify identity of the server certificate. Sometimes you receive one single file, but in other cases you may receive a number of separate files. You need them to be in one file. Fortunately this can be resolved by opening them up in a text editor like Wordpad or notepad and copying and pasting one after the other into a new file and saving and using that file as the CA bundle or intermediary file from here on in.
The private key must absolutely be the same private key that you originally 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 will have to start over.
To install a commercial SSL certificate, you must first login to the Admin Web UI.
Once logged in, visit the Web Server section in the menu.
Provide the three files necessary for certificate installation, then press the Validate button.
If you have provided all the necessary files correctly, a successful message should appear. Click save.
You may also want to click the Update Running Server button to effect your changes immediately. This may lead to you temporarily losing contact with the web services, but if you close your browser and open it again, it should now connect and show the green padlock if the certificate is installed correctly and trusted.
Recovering stored keys and certificates
The files you have submitted to the Access Server are stored in the configuration database files of the Access Server. In rare cases people have lost these files and need to retrieve them from the Access Server configuration database files. In order to do so you can consult the document describing how to recover SSL web certificates from the config DB.
Self-signed certificate behavior in Access Server
OpenVPN Access Server comes with a self-signed certificate from the start. 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 the document below:
If you did not provide the necessary files correctly, you may experience some of the problems below.
Certificate doesn't match private key Your private key does not match the one you have used to sign the CSR that you have submitted to your certificate authority. Make sure you are using the same key file that was used to generate your CSR. If you lost this file, you will need to restart the certificate generation process and ask your certificate authority for a certificate replacement. The private key is unique and cannot be recreated. If you've lost it, the signed public certificate also becomes useless.
Problems getting password, bad password read Your private key is encrypted with a passphrase and Access Server does not know how to decrypt the private key (i.e. it does not know what your passphrase is). Decrypt your private key by running the example command below on the command line with the OpenSSL program and then provide Access Server the decrypted private key file. The OpenVPN Access Server does not support using a private key for the web services that is additionally encrypted with a passphrase.
Decrypt a passphrase protected private key with OpenSSL:
openssl rsa -in server.key -out decrypted.key
You will be asked once for your passphrase. The resulting decrypted.key file can be loaded into the OpenVPN Access Server.
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 basically means that the private key you have provided is invalid in some way. Make sure that you have provided the correct file, and do not 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 are sure that the file is valid, and Access Server is not accepting the certificate file, it is most likely because of improper formatting of the private key file. For example without line breaks or with linebreaks using a different EOL (End-of-Line) standard that is not 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 and this can cause a problem. Usually they can help you to obtain a version that is compatible with Linux systems, 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 is 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 does not work, make sure you are providing the signed certificate you have received from your CA, and not the CSR you have generated on your own machine. The CSR is not needed or wanted by the OpenVPN Access Server, it is only used to do 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 occur in the Connect Client 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 could not 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 and these are called intermediaries. If there is one, only one intermediate certificate needs to be added to your chain of certificates, and if there are more, you can copy-paste them into one file, just one after the other, to make an intermediary bundle file that contains all the intermediaries to complete the path of trust. Please note that if you already had a working certificate before, but now have a new one from a different issuer, you will need to update your intermediaries as well.
On the OpenVPN Connect v2 client, the intermediaries are stored on disk with the client and to update this you would need to update the OpenVPN Connect v2. It is therefore best to stick to the same issuer when you need to renew a certificate and your clients are using OpenVPN Connect v2 with server-locked profiles. For user-locked and auto-login it doesn't make a difference 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.