Add link to managed acme service and update docs

Author: webprofusion-chrisc

docs/hub/guides/acme-server.md

@@ -3,29 +3,38 @@ title: Managed ACME Service
 ---
 
 ## Summary
-The Hub API can provide a simple ACME service which proxies certificate orders to real Certificate Authorities and takes care of the domain validation on behalf of the calling ACME client. 
+The Hub API can provide a simple ACME service *(currently experimental)* which proxies certificate orders to real Certificate Authorities and takes care of domain validation on behalf of the calling ACME client.
 
-This means you can point any ACME client client at the Hub ACME directory URL, ask it to complete HTTP domain validation (or none at all) and the hub will transparently order the corresponding certificate and complete domain validation on the clients behalf using a matching pre-configured a Managed Challenge. 
-
-If your ACME client support External Account Binding (EAB) this can be used to identify and authorize the client, if EAB is not supported you can optionally enable a unique ACME URL for each client.
+This means you can point any ACME client at the Hub ACME directory URL, ask it to complete HTTP domain validation (or none at all), and the hub will transparently order the corresponding certificate and complete domain validation on the client's behalf using a matching pre-configured Managed Challenge.
 
+If your ACME client supports External Account Binding (EAB), this can be used to identify and authorize the client.
 ### Example
 
-If you control a domain "projectbids.co.uk" and wanted to create a certificate "internal-app.projectbids.co.uk" from another device, that device has an ACME client but can't answer ACME http/dns challenges itself, you could instead use the hub to:
-- Configure a Managed Challenge which can update the target domain DNS.
-- Setup EAB credentials for your ACME client to use to identify itself to the hub and authorized it to use the required managed challenge.
-- Configure your ACME client to use the hub ACME API, providing the EAB credentials to identify itself to the hub during ACME account creation
-- Configure a new certificate in your ACME client with a domain/identifier matching the managed challenge.
+If you control a domain like `projectbids.co.uk` and want to create a certificate for `internal-app.projectbids.co.uk` from another device, that device may have an ACME client but can't answer ACME HTTP/DNS challenges itself (or you may not want it to). In that case, you can use the hub to:
+- Configure a Managed Challenge so the hub knows how to update the target domain's DNS zone.
+- Set up EAB credentials for your ACME client to identify itself to the hub, and authorize it to use the required Managed Challenge.
+- Configure your ACME client to use the Hub ACME API, providing the EAB credentials to identify itself to the hub during ACME account creation.
+- Configure a new certificate in your ACME client with a domain/identifier matching the Managed Challenge.
 
-## Setup your Managed Challenge
+## Set up your Managed Challenge
 
-Configure a [managed challenge](./managedchallenges.md) in the hub to answer challenges for your target domain. 
+Configure a [Managed Challenge](./managedchallenges.md) in the hub to answer challenges for your target domain.
 
 ### Creating EAB Credentials
-- Under Settings > Users, create an application security principal to represent your ACME client e.g. *Example ACME Client on firewall-01*. Assign the role *Managed ACME Consumer*
-- Under API Access, select Add API Token. Provide a descriptive title e.g. *Example ACME EAB Credentials*, select the security principle you created, select/scope the token to the *Managed ACME Consumer* role. 
-- Select *View as EAB* against the credential, copy the displayed values for use in your ACME client during initial ACME account creation.
+- Under Settings > Users, create an application security principal to represent your ACME client (e.g., *Example ACME Client on firewall-01*). Assign the role *Managed ACME Consumer*.
+- Under API Access, select Add API Token. Provide a descriptive title (e.g., *Example ACME EAB Credentials*), select the security principal you created, and scope the token to the *Managed ACME Consumer* role.
+- Select *View as EAB* against the credential, then copy the displayed values for use in your ACME client during initial ACME account creation.
+
+### Set up your ACME client
+
+In your ACME client of choice (on any device that can communicate with the hub API):
+- Configure the client to use the `<your Hub API URL>/acme/directory` ACME service and provide the EAB credentials you have created.
+- The ACME client will register a new account against the ACME service.
+- You can then order a new certificate for identifiers matching your Managed Challenge that you configured in the hub.
 
-### Setup your ACME client
+### Limitations and Known Issues
 
-In your ACME client of choice (on any device that can communicate with the hub API), configure the client to use the `<your hub api url>/acme/directory` ACME service and provide the EAB credentials you have created. The ACME client will register a new account against the ACME service, you can then order a new certificate for identifiers matching your managed challenge that was configured in the hub.
+- This method of "proxying" ACME orders is non-standard and may not work with every ACME client. It relies on ACME clients allowing authorizations to be instantly valid, but the order itself taking some time to process.
+- The choice of actual ACME CA used for the real certificate order depends on the hub's default CA selection. The client cannot currently indicate a preference; in the future, this may be possible using ACME profiles.
+- The temporary hub-managed certificate created for the order will be discarded as soon as the client downloads the final certificate. It will not participate in ACME ARI, etc., and automated renewal will depend on the client.
+- Currently ACME EAB support is required for account creation.

sidebars.js

@@ -118,6 +118,7 @@ export default {
           label: 'Managed Challenges',
           items: [
             'hub/guides/managedchallenges',
+            'hub/guides/acme-server',
           ]
         },
          {