Skip to main content

Serve HTTPS with your certificate

A certificate lets the gateway answer HTTPS for the host names it carries. A client that connects for one of those names is served the certificate, and its request then goes to the route that takes it, as over plain HTTP. This guide adds the certificate for api.example.com, the host name your clients call. At the end, a client that calls api.example.com over HTTPS is served your certificate and reaches orders-api as before.

Before you start​

  • A certificate for the host names your clients call, api.example.com here, from an authority your clients trust, and its private key, both as PEM text. Your PKI team or the authority you buy from issues them. The gateway does not request or renew certificates.
  • Where HTTPS ends in your installation. Some installations end HTTPS at a load balancer in front of the gateway and send the gateway plain HTTP. There the certificate belongs on the load balancer, and none is needed here. Whoever runs the gateway knows which of the two your environment does, and whether the gateway's HTTPS port is published to clients.
  • The host name must lead to the gateway: whoever runs your DNS points api.example.com at the address the gateway answers HTTPS on.
  • The gateway's HTTPS port is 9443 until whoever runs the gateway publishes HTTPS on the standard HTTPS port, so the HTTPS request below names 9443.
  • This guide starts from orders-api as Route requests to a backend leaves it, with no other plugin. A plugin from another guide that this page does not name can change the answers below; remove it first or work on a copy of the route.
  • The requests below call /orders/42.
  • The host name of your gateway. In the console it is the first part of the Address line on a route's Overview tab, api.example.com in this page's examples; replace it in every request below.
  • The Environment administrator role in this environment, or a custom role that manages certificates. An Editor sees certificates but cannot add one.

Steps​

1. Open a new certificate​

In the menu, select Certificates, then New certificate. Under General, leave Type at Server certificate: the certificate the gateway serves to clients.

2. Paste the certificate and its private key​

Under Certificate, paste the certificate into Certificate, or select Choose file. Put the certificate for your names first and the intermediate certificates of your authority after it. Paste the private key into Private key.

The console reads the certificate as you paste it and shows the name it was issued for, how many names it carries and when it expires. When the key belongs to another certificate, the form says so under Private key: The private key does not match the certificate.

The Certificate section of the new-certificate form, with a certificate pasted and its summary shown.

Keep your own copy of the key. Once saved, the console never shows it again.

3. Name the hosts it serves​

Back under General, type api.example.com in Server names and press Enter, or select Use names from the certificate to take every name the certificate carries. Leave Enabled on and the other sections as they are.

List only names the certificate carries. The console warns under the field when a name you type is not in it.

4. Create the certificate​

Select Create certificate. The certificate is saved like this, with the key sealed:

ssl · as the console saves it
{
  "type": "server",
  "snis": [
    "api.example.com"
  ],
  "cert": "<certificate PEM>",
  "key": "<private key PEM>"
}

From now on, a client that connects for api.example.com over HTTPS is served this certificate. The route that takes the request, orders-api here, needs no setting of its own for that.

Check it​

Once api.example.com leads to the gateway, send the request over HTTPS. The -v flag in it makes curl print the certificate it was served. For a certificate from your own authority, point curl at that authority's certificate with its CA option, or curl refuses the connection before any answer.

curl -v -i 'https://<gateway host>:9443/orders/42'

Then send the same request over plain HTTP, to the port the gateway answers plain HTTP on.

curl -i 'http://<gateway host>/orders/42'
Over HTTPS
A client that connects to api.example.com over HTTPS is served this certificate, and its request goes on to the route that takes it: answered 200.
Over plain HTTP
The same request over plain HTTP is still answered 200: the certificate adds HTTPS and turns nothing off.

Plain HTTP keeps working beside HTTPS. To send clients that still call over plain HTTP to the HTTPS address, see Send HTTP clients to HTTPS.

What to know​

  • A name with a leading *, *.example.com for example, covers a host one level below it, portal.example.com, and neither example.com itself nor a host two levels below. List example.com as a name of its own when clients call it.
  • One certificate can carry several names. A client that connects for any of them is served it.
  • A host no certificate covers gets no HTTPS: the TLS handshake fails. The same happens for the names of a certificate you delete.
  • Renew the certificate before it expires, from Edit certificate, with the new certificate and its key. The gateway keeps serving the current one until you replace it, and the console shows the expiry date on the certificate's page.
  • A certificate cannot be copied to another environment, because the gateway never returns its private key. Add it in each environment with its key.
G8 dev