Skip to main content

Certificate

Certificates let the engine terminate TLS for the names they cover.

In the console CertificatesEngine resource ssl

What a certificate is​

A certificate lets the gateway answer HTTPS for the host names under Server names. A client that opens a TLS connection for one of them is served this certificate. Its request then goes to the route that takes it, as over plain HTTP, and the route needs no setting of its own for that.

The private key is sealed: the console never shows it again, and a certificate cannot be copied to another environment. Each environment gets the certificate with its key.

How the gateway picks a certificate​

A client that connects over TLS names the host it wants, and the gateway serves the certificate whose Server names cover that host:

  • a name like api.example.com covers that host, and one certificate may list several names;
  • a name with a leading *, like *.example.com, covers a host one level below it, portal.example.com for example, and neither example.com itself nor a host two levels below it;
  • a host no certificate covers gets no HTTPS: the TLS handshake fails, as it does for the names of a certificate you delete.

When to use it​

  • Clients call the gateway over HTTPS under your own host name, for example api.example.com.
  • A web application behind openid-connect with Cookie secure on keeps its session in a cookie that is sent over HTTPS only.
  • One certificate serves several host names, or every host one level below a domain.
  • Only clients that hold a certificate from your own CA may connect: Require client certificates.
  • A backend asks the gateway for a client certificate: a certificate of type Client certificate, chosen on the upstream.

Guides​

Pages that walk through a job with a certificate, step by step.

Set it up​

Answer HTTPS for api.example.com, the address your clients call​

The name api.example.com must lead to the gateway; clients then call https://api.example.com and are served this certificate.

Under General leave Type at server and fill Server names as in the JSON below. Under Certificate set Certificate to <certificate PEM> and set Private key to <private key PEM>.

The General section of the console's New certificate form, filled with this example.
ssl · as the console saves it
{
  "type": "server",
  "snis": [
    "api.example.com"
  ],
  "cert": "<certificate PEM>",
  "key": "<private key PEM>"
}

What you will see​

  • 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.
  • The same request over plain HTTP is still answered 200: the certificate adds HTTPS and turns nothing off.

More scenarios​

Serve every host one level below example.com with one wildcard certificate

The certificate itself must carry *.example.com. A leading * covers one level below it, such as 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.

Under General leave Type at server and fill Server names as in the JSON below. Under Certificate set Certificate to <certificate PEM> and set Private key to <private key PEM>.

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

What you will see​

  • A client that connects for portal.example.com is served the wildcard certificate and answered 200.
Serve api.example.com and www.example.com with one certificate

Under General leave Type at server, fill Server names as in the JSON below and fill Labels as in the JSON below. Under Certificate set Certificate to <certificate PEM> and set Private key to <private key PEM>.

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

What you will see​

  • A client that connects for api.example.com is served this certificate and answered 200.
  • So is a client that connects for www.example.com: one certificate serves both names.

Things to know​

  • The engine assigns the id when the object is created; it is not the name, and it is what other objects refer to.
  • Certificate — Renew it before it expires: replace the certificate and the key from Edit certificate; the gateway keeps serving the current one until then.
  • A certificate cannot be copied to another environment, because the gateway never returns its private key: add it in each environment with its key.
  • AdviceKeep the certificate and its key with your other certificates, and put the expiry date where your team will see it.

Settings​

The fields as the console shows them, section by section. A field under “When … is …” is there only while that value is set.

General​

Typetypestringdefault server
one of client, server

When Type is server​

Server namessnisarray of stringsRequired, or sni instead

Host names clients ask for (SNI). A leading * covers one level below it: *.example.com covers api.example.com, not example.com and not a.api.example.com. A single value may be stored under sni instead.

at least 1 item
Descriptiondescstring
up to 256 characters
Labelslabelsobject

Key and value pairs of your own, for grouping and filtering. They change nothing about traffic. An object whose keys are any name, each with a string as its value.

Enabledstatusintegerdefault 1

A disabled certificate stays stored but is not served.

one of 0, 1

Certificate​

Paste PEM text or choose files. The certificate is read as you paste; the engine has the final say when you save.

CertificatecertstringRequired

PEM. The leaf certificate first; intermediates may follow in the same text.

128 to 65536 characters
Private keykeystringRequired

PEM. The private key that belongs to the certificate. Sent to the engine and never shown again.

64 to 65536 characters

Additional certificates​

Extra certificate and key pairs for the same names, for example an ECDSA certificate next to an RSA one. The engine needs a key for every certificate.

Additional certificatescertsarray of strings

Its private keys are stored beside it under keys and never shown again.

each 128 to 65536 characters

Protocols​

TLS versionsssl_protocolsarray of strings

Leave all unchecked for the engine default.

up to 3 items · one of TLSv1.1, TLSv1.2, TLSv1.3

Client certificates​

Who may connect to the server names of this certificate.

Require client certificatesclientobject

Mutual TLS: clients must present a certificate signed by the CA you provide.

CA certificateclient.castringRequired

PEM. Clients must present a certificate signed by this CA.

128 to 65536 characters
Depthclient.depthintegerdefault 1

How many intermediate certificates may stand between a client certificate and the trusted CA.

at least 0
Skip for URIsclient.skip_mtls_uri_regexarray of strings

Requests whose path matches one of these regular expressions are served without asking for a client certificate.

at least 1 item
G8 dev · Apache APISIX® 3.19.0
Apache, Apache APISIX and APISIX are trademarks of The Apache Software Foundation.
Facts
In the console
Certificates
Engine resource
ssl