Reference15r1: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 Token is saved in the Let's Encrypt App Service)
- 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
- Let's encrypt will send the certificate challenge using HTTP on port 80. On your WAN interface (that is, the interface your DNS name points to), port 80 must be available therefore. Traffic must be forwarded to either the device itself or to a reverse proxy that forwards the certificate challenge to the device.
- On the reverse proxy there must be a rule for the host that corresponds to the DNS name of your AP where the Let's Encrypt App runs on that forwards HTTP path
/.well-known/acme-challenge/to the Let's Encrypt App. Of course, an empty rule (such as the one that the reverse proxy PBX Manager plugin creates) will do. - For 3rd-party devices behind the Reverse-Proxy which intend to obtain a certificate from Let's Encrypt (using their own client mechanism), a similar rule must be present that forwards the challenge to the 3rd-party device.
- For innovaphone devices, such rules are not necessary (except for the AP as outlined above).
- The App Platform must be able to communicate with the Let's Encrypt URLs.
Conclusion: the recommended steps for obtaining certificates are as follows:
- configure the rule that forwards the challenge for your AP DNS name to the AP (your-ap.example.com
/.well-known/acme-challenge/) - configure the Connector for Let's Encrypt App on your AP
- configure the Let's Encrypt client on your AP
- configure rules for all 3rd party devices behind the RP that forward the challenge for the respective 3rd-party device's DNS names to the these devices (your-3rd-party-device.example.com
/.well-known/acme-challenge/). This step is optional
Security Consideration
We do not recommend that a device can be reached directly from the Internet on port 80. Please use the reverse proxy variant described above.
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
Troubleshooting
Not working TLS connection between a reverse proxy/gateway and the app platform with the Connector for Let's Encrypt
If a gateway/reverse proxy cannot establish a TLS connection to the app platform where the Connector for Let's Encrypt is running, no new certificate can be created anymore.
As a workaround, you can temporarily switch to a non TLS connection under Services -> Let's Encrypt Let's Encrypt App URL by using ws instead of wss.
If all your systems have a valid TLS certificate again, don't forget to switch back to wss!
Known Issue
Geoblocking can prevent confirmation
To verify the correctness of DNS entries and HTTP Challenge, Let's Encrypt sends DNS/HTTP requests from multiple locations around the world. All of these requests must be successfully answered. If a request is not answered due to geoblocking, Let's Encrypt does not trust the issuer.