Reference14r1:Concept Let's Encrypt
Certificates are automatically generated for innovaphone gateways and App Platforms.
Applies to
- innovaphone gateways from version 14r1
- innovaphone App Platform with version 14r1 apps (image version 110036 or higher)
How it works
- Each configured innovaphone client requests a new certificate 30 days before it's current certificate expires.
- Therefor an app websocket connection is opened to the Connector for Let's Encrypt App Service.
- The client sends a certificate signing request to the Connector for Let's Encrypt App Service.
- The Connector for Let's Encrypt App Service itself communitates via HTTPs and JWT with Let's Encrypt to request a new certificate.
- Let's Encrypt triggers an HTTP challenge for every DNS entry where the token for the DNS entry is verified.
- the HTTP challenge always works without HTTPS on Port 80 on a subpath of /.well-known/acme-challenge/, e.g. http://mydns.com/.well-known/acme-challenge/1290378712893z12983
- After successfull HTTP challenges for every DNS name, the new certificate is send back to the client.
- The certificate is installed X days before the old certificate expires, while X can be configured in the PBX Manager Plugin.
Flow without Reverse Proxy
Flow with Reverse Proxy
Requirements
ACMEv2 compliant certification service
Our Connector for Let's Encrypt App Service uses the ACMEv2 protocol. So in general every ACMEv2 compliant service could be used.
Officially tested is Let's Encrypt itself with this URL: https://acme-v02.api.letsencrypt.org
Gateways and App Platform
- Firmware from version 14r1 or later
- innovaphone App Platform with App Platform Manager version 14r1 or higher and image version 110036 or higher
- innovaphone App Connector for Let's Encrypt version 14r1 or higher
- working DNS configuration
Reverse-Proxy
- Port 80 must be available from WAN (external DNS should be correct for every DNS name, which gets a Let's Encrypt certificate) to the Reverse-Proxy, as the HTTP challenge uses this port to verify the token. (The ACMEv2 protocol doesn't allow another port!)
- The Reverse-Proxy automatically forwards incoming requests to
/.well-known/acme-challenge/to the Connector for Let's Encrypt App before the local ruleset is checked. The App checks if the challenge can be verified.- If this is not possible, because the App doesn't know anything about this request, the Reverse-Proxy takes care about the request by its normal configured ruleset.
- This means: if a 3rd-party device behind the Reverse-Proxy tries to generate a Let's Encrypt certificate by themselves (without the Connector for Let's Encrypt App) you have to create a rule for the Path "/.well-known/acme-challenge/" in your Reverse-proxy rules.
- Conclusion: If you want to use the automatic forwarding you have to connect the Reverse-Proxy as the first device to the app. Otherwise, devices behind Reverse-Proxy (mostly the PBX) can't obtain a certificate.
- The App Platform must be able to communicate with the Let's Encrypt URLs.
Limitations
- You can configure up to 100 DNS entries for a single device. More DNS entries are not supported by Let's Encrypt.
- You cannot configure DNS entries with wildcards. Such wildcard entries require the so called DNS challenge mechanism which is not supported by our Connector for Let's Encrypt App Service.
Configuration
Connector for Let's Encrypt PBX Manager Plugin
Configure the PBX Manager Plugin of the Connector for Let's Encrypt App Service.
innovaphone Gateways
Configure the Let's Encrypt service on every gateway which shall get a Let's Encrypt certificate.
innovaphone App Platform
Configure Let's Encrypt in the settings of the App Platform Manager on every App Platform which shall get a Let's Encrypt certificate.
RP
If your gateways and/or App Platforms are behind an innovaphone reverse proxy, you must configure the Let's Encrypt service here too.
You must configure all DNS names which are used by the individual devices behind the RP.
The RP will request a certificate with multiple SAN entries while every individual device will request an own certificate with a single SAN entry (or still multiple if a single device shall have multiple DNS entries).
Devices certificate configuration
If you want to rollout the Let's Encrypt root certificates to your devices, configure the URL for Let's Encrypt root certificates in a certificates configuration (App Devices -> Domains -> your domain -> Device Configurations) which will then ensure that always the latest root certificates are available in the trust list of your devices.
You can find this URL in the PBX Manager Plugin.
Tracing and logging
Gateways
The following trace flags can be activated at Maintenance/Diagnostics/Tracing.
- Let's Encrypt
- communication between gateway and the Connector for Let's Encrypt App Service
- processing of incoming id_tokens
- HTTP Client
- the HTTPS communication with the Connector for Let's Encrypt App Service
App Platform
Enable these trace flags for diagnostics:
App Platform Manager
- App
- requests of new certificates
- AppWebsocket
- communication with the Connector for Let's Encrypt App Service
- Websocket Client
- communication with the Connector for Let's Encrypt App Service
Connector for Let's Encrypt App Service
- App
- app logs
- HttpClient
- communication with Let's Encrypt itself
- AppWebsocket
- communication with the clients
Alarms and Events
- an event is generated for every failed certificate creation by the Connector for Let's Encrypt App Service
- an alarm is generated on the corresponding device as long as the certificate creation fails