TLS (and it's predecessor SSL) is the preferred method of encrypting and protecting HTTP sessions between a client and an HTTP server. You can also read more about TLS/SSL. Flow and Flow Enterprise require that TLS/SSL be used for both user sessions and our connectivity to your source code repositories and ticketing systems. This is an essential part of our security commitment.
When setting up Flow Enterprise, there are three scenarios for how you will obtain and manage your TLS/SSL certificates. These three scenarios are each very different and offer various pros and cons:
- Purchased Certificates: The most common method to obtain a TLS/SSL certificate is to purchase it from a public certificate authority like Verisign or DigiCert. These certificates will work in most browsers without problems.
- Use a Company Wide Certificate Authority: For large companies that utilize many TLS/SSL certificates, it is more cost effective to create their own certificate authority and self-sign certificates.
- Create Your Own: This is the least expensive option, but will require your users to accept the certificate before their browser will recognize it.
In all of these cases, you can create certificates in three ways to meet your needs:
- Specifically for the DNS of your server. For example, a certificate with a "Common Name" of "flow.mycompany.com" would only work for a server that receives requests for gitprime.mycompany.com.
- Using "Subject Alternative Names" is similar to the first option with a specific "Common Name", but with added "Subject Alternative Names" attached. For example, you could create the certificate with a "Common Name" of "gitprime.mycompany.com" and add "Subject Alternative Names" like "flow-analytics.mycompany.com" and "developer-info.mycompany.com" and it would apply to any of those names.
- Wildcard certificates allow you to create a single certificate for an entire domain. For example, using "*.mycompany.com" as the "Common Name" of the wildcard certificate would allow the certificate to be used for any DNS name that ended with "mycompany.com".
This document will describe how to configure Flow Enterprise for each of the three scenarios.
Purchasing certificates is the most common method of getting TLS/SSL certificates for a server and application. This option provides your server with a certificate that is guaranteed to be recognized as secure by most browsers and operating systems. Purchased certificates can be configured for both the specific server hostname, multiple hostnames, or in a wildcard fashion for an entire domain.
To purchase certificates, you should pick a well-respected certificate authority that sells certificates. There are many available and you can find many of them in this list. Once you have picked a provider, you should follow their instructions for requesting and purchasing a certificate.
Once that process is complete, you will have three or four files that are important:
- The private key. It is most likely that you created this when you created a certificate request to the authority.
- A certificate request file, sometimes called the CSR.
- The certificate itself.
- An intermediate certificate chain file. This file is only provided by some authorities if it is required. If it is provided, you will need it.
Using a Company Wide Certificate Authority
Many companies, when the grow to a large IT infrastructure, find the cost of purchasing certificates to be cost prohibitive. When that happens, they often establish their own internal certificate authority and begin signing and distributing their own certificates for internal (and sometimes external) use. Once in place, these organizations insure that their root certificate is trusted on all of the employee and infrastructure systems so that, as far as employees and servers are concerned, the certificates are 100% valid and trusted.
In the case that your company has gone this route, you will need to request certificates through their established processes. This process may be as simple as a web application where you can request a certificate and download it, or it may be part of a task tracking software like JIRA.
Once you have obtained the certificate, you should have, at a minimum:
- The private key for the certificate.
- The certificate itself.
You may also receive:
- The certificate request file, or CSR
- An intermediate certificate chain file that lets users find an appropriate trusted root when they access the servers using the certificate.
Signing Your Own Certificates
Signing your own certificates is relatively easy, however it has several downsides:
- It won't be automatically trusted by your users' browsers
- It won't be automatically trusted by other systems that contact the server
- It cannot be verified for authenticity in any way
Because of this, we do not recommend you use this method. This method is obviously inexpensive, but it has serious security and maintenance costs. However, if you choose to use this method, you can sign your own certificates using the following command on a server or workstation that has a modern version of OpenSSL on it.
openssl req -x509 -nodes -days <length of cert in days> -newkey rsa:2048 -keyout <path to private key> -out <path to certificate>
This command takes several options and you should replace values in <> with the values that best suit your needs. Here is an explanation:
- req: This tells OpenSSL that you want to make a new certificate request
- -x509: This option tells OpenSSL to use the x509 certificate format. This is the primary certificate format for all web certificates.
- -nodes: This tells OpenSSL that you do not want to use DES encryption on the private key. If you omit this option, you will be required to enter a password for the private key that is created. You will also be required to enter that password every time you restart a server that uses this private key.
- -days: This option specifies how many days the certificate should be valid for. For example, "-days 365" would create a certificate valid for one year.
- -newkey: This option tells OpenSSL to create a new RSA private key. The option value is in the format of <type of key>:<number of bits> . In the above example, it would create an RSA key that is 2048 bits of encryption strength.
- -keyout: This option places the generated private key into the file specified. For example /apache2/certs/myserverkey.pem.
- -out: This tells OpenSSL where to place the generated certificate.
When you execute the command, it is going to ask you several questions. You should enter values for all of them, but the one that matters the most is the "Common Name" field. You must enter a value here that matches the DNS name of the website you want to create the certificate for. For example, if you are configuring https://flow.mycompany.com, you would enter gitprime.mycompany.com when prompted for the "Common Name." Details about the questions are:
- Country Name: This is a 2-letter country code. For example, US for United States.
- State or Province Name: The full name of your state or province. For example, Colorado.
- Locality Name: This is the name of your City or some other location. For example, Denver.
- Organization Name: This can be your company name.
- Organizational Unit: This can be your department or group name inside the company. For example, Software Engineering.
- Common Name: This is the fully qualified domain name of your website. For example, for https://flow.mycompany.com, you'd enter flow.mycompany.com.
- E-mail Address: The address that users can reach for information.
When the command finishes, you should have a file at the path you specified in the -out parameter. You can verify the validity of this certificate by entering the following command:
openssl x509 -noout -text -in <path to certificate file>
This command will print out the information about your certificate. You should verify that the data matches what you expect.
If you need help, please email email@example.com for 24/7 assistance.