Encryption
Configures how encryption should be applied to the server.
Example
A certificate from Let’s Encrypt, accepting only clients with a certificate from a partner’s CA:
-
YAML
-
JSON
tls:
- name: acme
id: public
hosts:
- tiles.example.com
- name: pem
id: partner-clients
caFile: /etc/tilegroxy/tls/partner-client-ca.pem
server:
encrypt:
httpPort: 80
tls: public
mtls: partner-clients{
"tls": [
{
"name": "acme",
"id": "public",
"hosts": [
"tiles.example.com"
]
},
{
"name": "pem",
"id": "partner-clients",
"caFile": "/etc/tilegroxy/tls/partner-client-ca.pem"
}
],
"server": {
"encrypt": {
"httpPort": 80,
"tls": "public",
"mtls": "partner-clients"
}
}
}Configuration
| Parameter | Description | Type | Required | Default |
|---|---|---|---|---|
|
The ID of the TLS profile supplying the certificate served to clients |
string |
Yes |
None |
|
The ID of the TLS profile holding the CA used to validate client certificates. Required to use client certificates with Let’s Encrypt |
string |
No |
None |
|
How client certificates are handled. |
string |
No |
|
|
The port used for non-encrypted traffic. Required if using Let’s Encrypt to provide for the ACME challenge, in which case this needs to indirectly be 80 (that is, this can be set to e.g. 8080 if something ahead of this redirects 80 to 8080). Everything except .well-known will be redirected to the main port when set. |
int |
No |
None |
| Configuration Parameter | Environment Variable |
|---|---|
|
|
|
|
|
|
|
|
Redirects
When HttpPort is set, we redirect requests to HTTPS. The redirect uses the Host header only if that host is in the Hosts of the TLS profile. As long as there’s a non-wildcard host in Hosts we fall back to the first one, with a 400 being the last resort to avoid CSRF vectors. If the Host header uses the implicit port 80, we redirect to the implicit port 443. Otherwise we redirect to the main port in our config.
A pem profile with no Hosts and a certificate with no DNS names has nothing to redirect to, so every request gets the 400. A warning is logged when this happens. Set Hosts to fix it.
Client Certificates
With MTLSMode set to required, Mutual TLS (mTLS) requires every client to present a certificate with incoming requests. mTLS operates at the protocol level, this has a couple implications:
-
A connection without a valid certificate fails during the TLS handshake, without ever reaching tilegroxy’s logging or error handling.
-
mTLS does not automatically provide any facility for application-level authentication. Meaning it doesn’t associate a request with a user, nor does it provide any means for authorization by layer or bounds.
mTLS applies to the main port. The redirect served on HttpPort and the health port don’t ask for a certificate. If a proxy terminates TLS in front of tilegroxy, the certificate being validated is the proxy’s rather than the original client’s.
The CA comes only from the profiles referenced here. The client section’s profiles are never used to validate incoming clients.