Use Let's Encrypt Certificates

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

This article describes features that require Banyan Netagent v1.37.0+.

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 - In this option, Hosted Websites use a TLS server cerificate issued by the free and open CA, Let’s Encrypt and 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.

To use Banyan-managed Let’s Encrypt certificates, you must follow the steps below to first register your specific Hosted Website domain with Banyan before publishing it to your end-users.

How It Works

Banyan leverages Let’s Encrypt and the ACME protocol to configure the Access Tier and the Cloud Command Center 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

At a high level, you will:


Prerequisites

Before proceeding through the steps below, ensure you have configured your DNS so that your Registered Domains points to the applicable Access Tier.

You may 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

In order to you publish a Hosted Website that uses a Let’s Encrypt certificate, its Service Domain Name must match your Registered Domain patterns.

Step 1. Register Your Domain to Obtain a Let’s Encrypt Certificate

1.1 In the Banyan Command Center, navigate to Directory & Infrastructure > Registered Domains and then click + Add Registered Domains.

1.2 Enter the Registration Domains Details:

  • Enter a valid Domain Name (supports wildcards)
  • Enter a description of the domain
  • Select the applicable Cluster and Access Tier

You may use wildcards (such as *.example.com) while registering your domains; however, Let’s Encrypt certificates can only be issued to single-domain web services and not multi-domain (aka wildcard) web services.

1.3 Click Save.

Please allow up to 10 minutes while we validate the domain and procure a certificate. Then, ensure the domain status shows Verified.

Certificates can have a status of Verified, Pending, or Failed.

Step 2. Configure a Hosted Website

2.1 Navigate to Manage Services > Hosted Websites, and then click + Register Service and select the Standard Website template.

2.2 Configure the Service Details, such as name, description and link shown to end users, icon, and cluster.

3.3 Configure the Service Attributes accordingly. Ensure you click the Let’s Encrypt checkbox and enter a Service Domain Name that matches a domain configured in Step 1.3.

Multi-domain (Wildcard) Web Services cannot be used in conjunction with Let’s Encrypt. If your organization would like to configure a wildcard web service, you must use a certificate issued via Banyan PKI or a Custom Certificate.

2.3 Optionally, attach a policy.

2.4 Click Register Service.

Step 3. Review the Certificate Status

3.1 While still on the Directory & Infrastructure section, navigate to Issued Certificates.

3.2 Ensure the domain’s certificate status is Verified.

Certificates can have a status of Verified, Pending, or Failed.

That’s it! You have successfully obtained a certificate for your domain and applied it to a hosted website.


Common Issues

Unable to Register Domain

Sometimes, you may see an error message while registering a domain:

Error occured while registering domain: example.com for orgID: 1234-abcd

This is typically because your DNS is not configured correctly, so the domain you are trying to register does not resolve to a Banyan Access Tier. The ACME protocol that’s used to procure Let’s Encrypt certificates uses domain validation so DNS needs to configured correctly for Banyan to manages issuance, renewal, and revocation.

Use the nslookup command (or an alternative such as dig or host) to check how your DNS records resolve. Once you configure your DNS so that your Registered Domains points to the applicable Access Tier domain registration will succeed.

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 Ecnrypt.

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

Last modified: Jul 12, 2021