Skip to main content

Managed Challenges

Introduction​

A managed challenge provides a way for the management hub to perform ACME challenge responses on behalf of other ACME clients. This is useful for DNS based challenges, so that your ACME clients (including Certify Certificate Manager) don't need to know privileged credentials with direct access to your DNS API.

feature under development

This feature is under development and documentation may refer to features and procedures that are not yet available.

How It Works​

When you perform a certificate request on any ACME client, the CA will ask your ACME client to prepare a particular "challenge response" (an _acme-challenge TXT record) in your domains DNS. Your ACME client will call the Management Hub API with details of the record to be created and the hub will create the record on it's behalf.

Getting Started​

To use a managed challenge you need two things:

  • A configuration for the managed challenge. This will specify which DNS provider and credentials will be used and importantly it will specify the matching domains the challenge configuration can be used for with a Domain Match Rule.
  • An assigned API Token allowing access to use managed challenges. This will be used by your ACME client to call the management hub API. Generally you should use individual API keys specific to each consumer instead of sharing them across machines, that way when a service is retired you can also remove it's access and you can maintain a clear idea of which things still need access.

Define a Managed Challenge configuration​

Under Services > Managed Challenges, select + Add:

  • Select dns-01 as the challenge type
  • Select the DNS provider specific to your domains DNS service.
  • Add or select existing stored credentials for updating DNS via the selected API.
  • Populate the Domain Match Rule to specify the domains this configuration can update DNS for, then Save.

Configure API Access​

Before you can use your managed challenge you need to configure API access. This involves assigning an API token for a specific Service Principle (a specific user or app).

Under Settings > Security > Users, add a User to represent the consumer (user or app etc) accessing the service, then assign them the Managed Challenge Consumer Role. They can have any other roles they need, but you'll need this specific role to access managed challenges.

Under Settings > Security > API Access, select Add API Token, select the required security principle, enter a descriptive title etc for this consumer token so you know why it exists and what it's being used for. To scope the API access token to managed challenges only, select Managed Challenge Consumer from the Role list and click Add/Remove Role Scope, then Save. A new API token will be created and you will need the Client ID and Secret values to access the API and use the managed challenge.

Configure your ACME Client​

Where an ACME client supports Certify Managed Challenges you will follow the normal process for selecting that provider and you will be required to specify the Client ID and Secret from the above configuration, you will also need to specify the Management Hub API Url. When you then perform your certificate order it will call the Management Hub API to complete the DNS updates required.