All of our APIs (as well as web front ends) are served via encrypted HTTPS. Doing so requires obtaining an SSL certificate from a certificate authority or one of its authorized resellers. There are many options for doing so (with varying costs and trust levels), but Vokal maintains a wholesale account through OpenSRS which allows us to purchase certs on a client's behalf from a handful of top providers.
There are some important considerations below, but feel free to skip ahead to generating a CSR, ordering a wildcard cert from OpenSRS, or uploading a cert for use in CloudFront.
Once your SSL cert is installed on a staging server and it has a proper domain name (e.g.
staging.example.com), you can verify that the server is immune to common exploits by checking the domain with Qualys SSL Labs SSL Server Test. Ask your PO/AM if you should save a copy of the generated report to share with the client.
Some important considerations
When should I get a cert?
As soon as possible after kicking off the project. Ideally it should be mentioned at some point in discovery that the project requires an SSL cert, but be sure to let your PO know about the cert and other prerequisites during your project's first sprint at the latest. If you allow the PO or client to put this off it will almost certainly delay production deployment and cause show-stopping problems when mobile or web clients must switch from HTTP to HTTPS later. Ideally staging should never be deployed without an SSL cert in-hand.
Who should get the cert?
The client may possess sufficient technical knowledge to obtain a cert on their own, but whenever possible we prefer to obtain certs directly on their behalf. Invariably issues arise keeping track of and/or properly securing the private key, generating the certificate signing request (CSR), or properly formatting the cert and/or the intermediate CA certs.
Make sure you secure from the client valid and verifiable contact information. If this cannot be verified by the certificate authority, a certificate will not be issued. Furthermore, have the client verify that their business information is properly registered and in good standing with the Secretary of State or other agency. If the certificate authority cannot verify this information, or if a company is listed as "NGS" or "Not Good Standing", a certificate will not be issued. Finally, make sure any domain registration information is up-to-date. Most certificate authorities will send a verification email to the email address listed in a WHOIS record. If that email cannot be verified, a certificate will not be issued. (Sensing a pattern here?)
While there are CAs that will issue certs without verifying this information (e.g. RapidSSL only verifies that the email address in the WHOIS info is controlled by the person requesting the cert via an emailed verification link), Thawte is currently our preferred provider and will check to make sure that requesting organizations are legitimate. Any company we do business with should have these sorts of basic things in order anyway, but problems can be (and have been) revealed when certs aren't requested until the last minute, blocking and delaying production deploys.
Wildcard SSL cert
SSL certificates are pinned to a particular domain. For example, if I want to secure
www.example.com, I request a cert for
www.example.com. If I want to secure
api.example.com, I need to obtain another cert. However, most CAs will issue wildcard certs if you generate a CSR for
*.example.com, and that can be used to secure any subdomain (but not sub-subdomains) of
example.com. This is much cheaper and much easier to manage than buying a separate cert for each service you plan to run, and is perfectly fine for non-public-facing services.
The client may want to obtain a separate certificate for any public-facing service, such as a website at
www.example.com. In particular, they may want to pay extra for an extended validation cert for this purpose. It costs quite a bit more, but particularly if they accept payment or other sensitive private data, an EV cert will turn the location bar in the browser green to indicate that the CA has more thoroughly vetted the company as an added indicator of trust.
Obtaining an SSL cert via OpenSRS
Generate private key and CSR
Use the following command to generate a 2048-bit RSA private key and CSR:
openssl req -out example.com.csr -new -newkey rsa:2048 -nodes -keyout example.com.key
OpenSSL will ask for some information for the CSR; you must fill out the following fields, and hit enter to leave the rest blank:
- Two-letter country code (usually US)
- State (the full name, not the abbreviation, e.g. Illinois)
- Locality Name, i.e. city (e.g. Chicago)
- Organization, i.e. official company name (e.g. ExampleBiz LLC; Example, Inc)
- Common Name, i.e. domain name (e.g.
You can and should skip the following by hitting enter:
- Organizational Unit
- Email Address
- Challenge password
- Optional company name
The contents of
example.com.csr is what you will use to request an SSL cert; it should look like:
-----BEGIN CERTIFICATE REQUEST----- MIICqDCCAZACAQAwYzELMAkGA1UEBhMCVVMxETAPBgNVBAgTCElsbGlub2lzMRAw DgYDVQQHEwdDaGljYWdvMRcwFQYDVQQKEw5FeGFtcGxlQml6IExMQzEWMBQGA1UE AxQNKi5leGFtcGxlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB ALN506N3gY3p84csxQE1SQrC6jP+LIQgz37u7pk01Adr0m/nP6En60Gh9Ax78HEb u3RK9a6VdbpJTqIIBucuoxEXdphAk6SLTVk5y7Y5Codbf9PI1GnjrTnIHKYgSHzb H2PB/m/O2kQEQniwpMiIT6CLEiqICS9Sk6qmzInpaKK2uY3mxy5lQlkAX9m8tnGR XHXqcKcNssm1ThnvD9hLqgfa9rI3clj8kcTYH53KKO5B/YIM4thSZ5zA0meoZ0yi hh90jxDgagsZLABgRGe924ISq1/eGqa+gAbsQD6C644iD2hU20jHHkeP/ttkSWjh HgcVSswbXYW1gpoDJF4LmIcCAwEAAaAAMA0GCSqGSIb3DQEBBQUAA4IBAQAwPFCH nvw9IYlz6npQBML1nUkr1LdUShvA8gx6Cl1Va28ZOdPr154O5JJ7Nn4QN+JMAvk1 BaoZvTwIS5+zwuXECXXsr+bEOyNIfbQtqF2koeqONBIrBkwY4IseXdEJBgX2VTL6 NrKQdgz2cMA9AS1PEfTdB265hl88+q6xV1xYohiR7NvcV0Kki3qFhCooTu/9K8RL 9kfZoIv9ggCv6pLIDwyRq1fA9GyBdQ0Gm4CsjOwfwFqVATizWpLbtHEjzqEzhfbV rDxZPNIK7MMvaxYZNSOhY8TjaxVYTkLGWpT6MvXPhx1U0C/7QJn60mITT2e62QEE Rme0GUmtF6+5ol1r -----END CERTIFICATE REQUEST-----
You can verify the information was entered correctly using:
openssl req -text -noout -verify -in example.com.csr
The ouptut should look something like:
verify OK Certificate Request: Data: Version: 0 (0x0) Subject: C=US, ST=Illinois, L=Chicago, O=ExampleBiz LLC, CN=*.example.com Subject Public Key Info: ...
Place an order via OpenSRS
- Obtain and secure the username and password for Vokal's OpenSRS account
- Go to https://opensrs.com
- Click on "Sign In" (in the upper left corner)
- Click on the "Sign In" button for "Reseller Control Panel" and sign in
- Click on "Trust" in the main navigation
- Click the "+" icon to add a new order
- Select "Thawte" for supplier and "SSL Web Server Certificate Wildcard" for service and click "Continue"
- Choose a one- or two-year period, and leave server and count at the default.
- Fill out the organization information with up-to-date client company info.
- Fill out Administration with an authorized company contact
- Fill out Billing with Austin Sheaffer's contact info
- Fill out Technical with your contact info
- Paste in the CSR generated above in the CSR box, and click "Save as Draft"
- Verify that all the info was entered correctly and click "Add Service". If you make any errors after submitting, you must cancel the order and create a whole new order.
From here, Thawte will verify the client's information. Be sure the client is prepared to respond to emails or phone calls to verify information. You can request help via OpenSRS to find out what, if anything, might be holding up an order. Certs typically take between 2-5 business days to process. The issued cert may be emailed directly to you, but make sure the client contact is prepared to forward to you just in case.
Install the cert on staging
You'll need to copy the cert and private key to your staging server. You can use
scp, but some find it easier to
ssh into staging,
cat the files locally, and paste into a new file created directly on the server using
vim. Be sure to set the permissions for these files to
600. You can find more details in our nginx config documentation.
Using an SSL cert with AWS CloudFront
To upload an SSL cert for use with CloudFront, you must install and configure the
awscli command line tool and use the following command to upload the cert into the IAM certificate store.
- The command requires the cert and intermediate CA cert be specified separately (as opposed to combined into the same file).
server-certificate-nameis the name that shows up in the drop down menu in the CloudFront console when you choose "custom SSL".
pathparameter must start with
/cloudfront/and can be anything; it's only used for organizing it internally within the certificate store in IAM.
aws iam upload-server-certificate --server-certificate-name Example_Cert --certificate-body file://example.crt --private-key file://example.key --certificate-chain file://rapidssl-ca.pem --path /cloudfront/example-cert/