SBC certificate per tenant

What it is for

Microsoft accepts a Direct Routing trunk only if the SBC presents a publicly trusted certificate for exactly its hostname. EasyUC orders this certificate from Let’s Encrypt itself and stores it. The private key stays on the server. It is not displayed anywhere and cannot be downloaded.

EasyUC proves ownership of the hostname with the DNS-01 method: Let’s Encrypt requires a specific TXT record in the DNS zone of the domain. Port 80 does not have to be reachable from the Internet for this.

There are two ways. By hand: EasyUC shows the name and value of the TXT record, and you create it at your DNS provider. This works with every provider. Automatically: if credentials for Cloudflare are stored on the SBC page, EasyUC sets the record itself and renews the certificate without intervention.

Prerequisites

• Licence module teams. Without this module the EasyUC Teams workspace does not appear.
• Role EasyUC Teams (ROLE_APP_TEAMS_WORKSPACE) with the sub-permissions TENANTS (ROLE_APP_TEAMS_TENANTS) to read and TENANTS bearbeiten (ROLE_APP_TEAMS_TENANTS_EDIT) to change.
• The tenant exists and its hostname is correct.
• On the SBC page, Contact e-mail and Environment production are set, and Validation is DNS-01.
• You can create a TXT record in the public DNS zone of the domain. For the automatic way: a Cloudflare API token with write access to the zone.
• The EasyUC server reaches Let’s Encrypt over HTTPS and can resolve public DNS names.

Step by step: Get the certificate by hand with a TXT record

1. Open Teams Tenants, click the tenant and stay in the Settings section.
2. Go to the box Certificate for this hostname (Let’s Encrypt). The arrow next to Certificate in the header jumps straight to it.
3. Click Request certificate and confirm the prompt. EasyUC creates the order.
4. Wait for the box Now create this TXT record in the DNS zone of this domain. The state reads DNS entry required.
5. Copy Record name and Value with the Copy buttons. Copy line gives you the record as a single line in zone format.
6. At your DNS provider, create a record of type TXT with this name and this value. Set the TTL as short as possible; 60 seconds is ideal.
7. Wait until the record can be resolved publicly. Depending on the provider this takes a few minutes.
8. Click Check and issue now.
9. If the answer is „Let’s Encrypt prüft den Eintrag noch. Bitte in einer Minute erneut auf „Jetzt prüfen und ausstellen“ klicken.“, wait a minute and click again.
10. After the message „Das Zertifikat wurde ausgestellt und gespeichert.“ the box shows issued, valid until with the date and the days left.
11. Delete the TXT record again. It is no longer needed after issuance.

Step by step: Automatic issuance and renewal with Cloudflare

1. At Cloudflare, create an API token with permission to edit the DNS records of the zone.
2. Open EasyUC Teams → Teams → SBC Setup and click Edit.
3. Under DNS provider, enter cloudflare.
4. Under DNS credentials, enter the line CF_API_TOKEN=… with your token. Text without an equals sign is taken as the token itself.
5. Click Save. The overview then shows “DNS credentials stored, renewal runs on its own”.
6. EasyUC checks all active tenants daily at 03:30. If a certificate is missing, an attempt has failed or 30 days or fewer remain, EasyUC sets the TXT record, issues the certificate and removes the record again.
7. If you do not want to wait for the next run, request the certificate once by hand on the tenant page.

Fields and options

Check the result and narrow down errors

• Success: the tenant header shows valid until with a date under Certificate. The SBC picks up the certificate itself and restarts the tenant’s SIP profile as soon as no call is running.
• „Der TXT-Eintrag … ist noch nicht sichtbar. Bitte im DNS anlegen; je nach Anbieter dauert es einige Minuten, bis er abrufbar ist.“ Check name and type. Some providers append the zone name themselves; the name must not contain the domain twice.
• „Unter … steht bereits ein TXT-Eintrag, aber noch nicht der erwartete Wert. Meist stammt er aus einem früheren Versuch - bitte den Wert ersetzen und einige Minuten warten.“ Replace the old value.
• „Für Let’s Encrypt fehlt die Kontakt-E-Mail. Bitte sie auf der SBC-Seite eintragen.“ Add the e-mail in the SBC settings.
• „Es liegt keine offene Zertifikatsbestellung vor. Bitte zuerst „Zertifikat anfordern“.“ The order has expired. Request again; the TXT value is then a different one.
• „Der Hostname wurde seit der Bestellung geändert. Bitte das Zertifikat neu anfordern.“ Request again for the new name.
• A notice that the certificate comes from the test environment and is NOT publicly trusted: switch to production on the SBC page and request again.
• “This certificate expires in less than 30 days. Without stored DNS credentials nobody renews it automatically - request it again here in good time.” Repeat the manual procedure or store Cloudflare credentials.
• „In den DNS-Zugangsdaten wurde kein CF_API_TOKEN gefunden. Erwartet wird eine Zeile CF_API_TOKEN=...“ Correct the credentials on the SBC page.
• „Für den DNS-Anbieter „…“ gibt es noch keinen Treiber. Bitte das Zertifikat von Hand anfordern.“ Only Cloudflare works automatically.
• Certificate issued but the trunk stays down: check environment, exact hostname, TLS port and firewall. Continue in the chapter “Teams calls, SIP flow and captures”.