Use Let's Encrypt Certificates

Publish hosted websites with browser-trusted Banyan-managed Let's Encrypt certificates

  • Updated on Jan 08, 2024

This article describes features that are only available in the Banyan Enterprise edition and Banyan Unlimited edition.

Overview

Banyan provides three options to specify the TLS server certificate used for your Hosted Websites:

  1. Banyan PKI (default) - Banyan manages a Private PKI (Public Key Infrastructure), also known as an Internal Certificate Authority, for your organization named {orgname} Banyan Private Root CA. By default, Hosted Websites use a TLS server certificate issued by this Private PKI, and require devices be registered and possess a trusted device certificate.

  2. Custom Certificates - You may procure and upload your own Public or Private CA issued server certificate onto the Access Tier VMs in lieu of using the Banyan PKI, via our Custom Certificates capability. This option enables you to use default-browser-trusted certificates but requires additional configuration and ongoing management of the certificates.

  3. Let’s Encrypt Certificates - Hosted Websites use a TLS server certificate, issued by the free and open CA, Let’s Encrypt. Banyan manages issuance, renewal, and revocation of the certificates. Let’s Encrypt certificates are browser-trusted by default, providing better support both registered and unregistered devices connecting to Banyan-secured services.

How It Works

Banyan leverages Let’s Encrypt and the ACME protocol to configure the Access Tier and the Cloud Command Center to automatically obtain browser-trusted certificates from a Public CA without any human intervention.

A key element of the ACME protocol is a domain validation procedure which allows infrastructure software to obtain certificates without user interaction. In Banyan, this procedure is called Domain Registration. Once your domain is registered via the Banyan Command Center, we facilitate procurement and management of TLS server certificates that auto-renew every 90 days (or sooner). Read more about how Let’s Encrypt works at the Let’s Encrypt tutorial.

Please note in mind that Banyan does not issue Let’s Encrypt certificates for the following:

Steps

Prerequisites

Before proceeding through the steps below, ensure you have configured a Register Domain. In order to publish a Hosted Website that uses a Let’s Encrypt certificate, its Service Domain Name must match your Registered Domain patterns.

Ensure you have set up a Registered Domain that points to the applicable Access Tier for your Hosted Website.

You can set up an individual CNAME records as well as wildcard CNAME records:

*.yourdomain.com   CNAME access_tier_site_address.iaas.com
foo.yourdomain.com CNAME access_tier_site_address.iaas.com

Ensure you have set up a Registered Domain for your Hosted Website. You may need to configure a Custom Domain if your Hosted Website uses an FQDN that doesn’t fall under your Banyan-provided Org Domain.

If you’re using a custom domain, you can set up an individual CNAME records as well as wildcard CNAME records:

*.yourdomain.com   CNAME *.orgname.banyanops.com
foo.yourdomain.com CNAME *.orgname.banyanops.com

Step 1. Confirm your Registered Domain status is Verified

1.1 In the Banyan Command Center, navigate from Settings > Registered Domains, and select the Registered Domain you will use for your Hosted Website.

1.2 Ensure that the domain status for your Registered Domain shows Verified.

Step 2. Configure your Hosted Website to obtain a Let’s Encrypt Certificate

2.1 Navigate from Private Access > Hosted Websites, and then select + Add Hosted Website.

2.2 Configure the Access Details accordingly. Ensure you toggle on Use Let’s Encrypt Certificate if you’re using a Banyan-registered domain.

2.3 Optionally, attach a policy.

2.4 Save & Validate your hosted web service.

Step 3. Review the Certificate Status

3.1 While still in Settings, navigate to Issued Certificates.

3.2 Ensure the domain’s certificate status is Verified.

Certificates can have a status of Verified, Pending, or Failed. Please allow up to 10 minutes while we validate the domain and procure the certificate.


Notes

Certificate Status is Failed

Sometimes, you may see a certificate issuance failure when publishing a Hosted Website that uses a Let’s Encrypt certificate. A common error message is:

failed_reason: "error: one or more domains had a problem: [foo.example.com] [foo.example.com] acme: error presenting token: time limit exceeded: last error: Get "http://foo.example.com/.well-known/acme-challenge/Kv42PobsQ-ggnPiosH1HYt35QwFiTd2CfW-dXNAnyxk": dial tcp 35.247.123.123:80: connect: connection refused"

This is typically because the ACME protocol requires the Netagent to respond to a HTTP request from the Let’s Encrypt CA at the path .well-known/acme-challenge/ on Port 80 but traffic isn’t reaching the Netagent and times out.

Ensure that the Access Tier can receive traffic from the internet on Port 80, and that the Netagent binary is listening on that port. You can confirm by issuing a curl to the domain name of the your Hosted Website. You should get a 302 redirect to the corresponding HTTPS path.

curl http://foo.example.com/bar
<a href="https://foo.example.com/bar">Found</a>.

Another common error message is:

couldn't verify challenge for domain: foo.example.com, token: rIrwHK-Q2t6L64aYctU3ovCS7_Y1-BDdkRClw5gcMdw, err: time limit exceeded: last error: couldn't verify challenge
[INFO] [foo.example.com] acme: Could not find solver for: tls-alpn-01

In this case, ensure that you’re on Banyan Netagent v1.37.0+ in order for the Let’s Encrypt certificate issuance to succeed.

Confirm which CA is Used

You can confirm what type of certificate is being used by your Hosted Website by clicking on the lock icon on your browser’s URL bar. Select Certificate Details to see more information about the server certificate, and note the Issuer specifics.

When a certificate is issued by the Let’s Encrypt CA, the Issuer Common Name will be R3 and the Organization will be Let's Encrypt.

In contrast, when a certificate is issued by Banyan’s Private PKI, the Issuer Common Name will be {orgname} Banyan Private Root CA.


Can’t find what you’re looking for?

We’re happy to help. Contact our team.