execute certificate local import automated

Use this command to import local certificates using the ACME protocol to get SSL/TLS certificates from Let's Encrypt or other ACME providers.

As part of the certificate importing functionality, FortiADC supports the Automatic Certificate Management Environment (ACME) protocol for automating the interactions between certificate authorities (CAs) and their users' web servers.

Certificates imported through Let's Encrypt have a ninety-day lifetime (which may differ from other ACME providers). These certificates must be renewed prior to expiration. FortiADC supports the TLS-ALPN-01 and DNS-01 challenge types. The TLS-ALPN-01 challenge supports automatic certificate renewal. The DNS-01 challenge requires manual certificate renewal, however, only the DNS-01 challenge can issue certificates containing wildcard domain names.

Before you begin:

• You must have Read-Write permission for System settings.

Syntax

execute certificate local import automated <cert_name> <domain> <email> <key_type> {RSA|ECDSA} <key_size> {<key_size>|<curve_name>} <password> <server_url> <ca_group> <challenge_type> {tls-alpn-01|dns-01} <renew_win> <challenge_wait> <cert_group>

Execute Parameter	Description
<cert_name>	Specify the certificate name that can be referenced by other parts of the configuration, such as www_example_com. The maximum length is 35 characters. Do not use spaces or special characters. Note: If the challenge_type is tls-alpn-01, and you choose to fulfill the TLS-ALPN-01 challenge using a placeholder certificate, the cert_name must match the name of the "placeholder" certificate that is linked to the HTTPS virtual server. For details, see Fulfilling the ACME TLS-ALPN-01 challenge with a placeholder certificate.
<domain>	Specify the web server domain(s) to be protected by the certificate. When inputting multiple domains, separate each domain using a comma with no additional spaces. Note: If the challenge_type is tls-alpn-01, all domains should be resolved to the IP address set by the VS. For details, see Fulfilling the ACME TLS-ALPN-01 challenge with a placeholder certificate.
<email>	Enter the email address that will receive notifications regarding the status of the certificate. Depending on which ACME service provider you use, you may receive notification for when the certificate request has been approved through the Certificated Services or when the certificate is due to expire.
<key_type>	Select either of the following key types: RSA ECDSA Note: If the challenge_type is tls-alpn-01, and you choose to fulfill the TLS-ALPN-01 challenge using a placeholder certificate, the key_type must match the key type of the "placeholder" certificate that is linked to the HTTPS virtual server. For details, see Fulfilling the ACME TLS-ALPN-01 challenge with a placeholder certificate.
<key_size>	Specify the key_size if the key_type is RSA. Select one of the following key sizes: 2048 3072 4096
<curve_name>	Specify the curve_name if the key_type is ECDSA. Select one of the following curve names: P256 P384 P521
<password>	Specify the password to decrypt the file. If the file was encrypted by a password when generated, the same password must be provided when the file is imported to FortiADC. If the file was generated without a password, there is no need to specify a password when importing the file to FortiADC. Enter null if there is no password.
<server_url>	To use Let's Encrypt as the ACME provider, enter null as the server_url. To use other ACME providers, such as Buypass AS, specify the URL of the ACME server. The ACME request URL must begin with "https://". After you have obtained the ACME certificate from your chosen ACME service provider, you will need to provide the ACME server URL to connect to FortiADC. This will enable FortiADC to act as the ACME client to send the ACME request and receive the ACME certificate/key. Note: The ACME server URL is unique to the ACME service provider. Please refer to the documentation from your ACME provider for further information.
<ca_group>	Specify the name of the CA Group. FortiADC will use the CA certificate in the CA Group to verify the certificate sent by the ACME provider. Enter null to not verify.
<challenge_type>	The ACME server requires validation that you control the domain names in the certificate using "challenges" as defined by the ACME standard. FortiADC supports the TLS-ALPN-01 and DNS-01 challenge types. Select either of the following challenge types: tls-alpn-01 — The TLS-ALPN-01 supports automatic certificate renewal. However, this method cannot be used to validate wildcard domains. In FortiADC, to fulfill the TLS-ALPN-01 challenge, the ACME server validates control of the domain name by connecting to the Virtual Server at one of the addresses resolved for the domain name. This is achieved by linking a certificate to an HTTPS virtual server to allow the ACME server resolving domain to point to its IP. Then FortiADC generates a temporary certificate to fulfill the validation. FortiADC offers two options to fulfill this requirement: 1) allow FortiADC to manage this process on the backend by selecting a Local Certificate Group, or 2) prepare the placeholder certificate before the certificate import configurations (for details, see Fulfilling the ACME TLS-ALPN-01 challenge with a placeholder certificate). dns-01 — The DNS-01 challenge can be used to issue certificates containing wildcard domain names. To use this challenge type, you will need to take steps to fulfill the challenge after completing the certificate import configurations (for details, see Fulfilling the ACME DNS-01 challenge). Certificates imported using the DNS-01 challenge need to be manually renewed.
<renew_win>	Specify the renew_win if the challenge_type is tls-alpn-01. Specify a renew window (in minutes) to automatically renew the certificate before it expires. (Range: 0-43200 minutes). Setting the renew window to 0 will disable the automatic certificate renewal.
<challenge_wait>	Specify the challenge_wait if the challenge_type is dns-01. Specify the ACME DNS-01 challenge wait time in minutes. (Range: 1-1440 minutes). The ACME DNS-01 challenge wait time refers to the amount of time you will have to fulfill the DNS-01 challenge. A longer challenge wait time is recommended to ensure enough time is allotted to perform the required Public DNS configuration changes and for the changes to take effect. For more information, see Fulfilling the ACME DNS-01 challenge.
<cert_group>	Specify the cert_group if the challenge_type is tls-alpn-01. Select a local certificate group to allow FortiADC to manage the placeholder certificate generation and removal process required for the TLS-ALPN-01 protocol on the backend. This is optional. Alternatively, you can prepare a placeholder certificate to fulfill the TLS-ALPN-01 challenge instead. For details, see Fulfilling the ACME TLS-ALPN-01 challenge with a placeholder certificate.

Example

FortiADC # execute certificate local import automated ACME-test test.com test@fortinet.com RSA 2048 null null null dns-01 3
Done.

FortiADC-VM (root) # execute certificate local import automated root-0408-1-rsa acme01.com,acme02.com mick@xx.com RSA 2048 null https://pebble:14000/dir null tls-alpn-01 1 root-empty-0
Done.

Fulfilling the ACME DNS-01 challenge

The DNS-01 challenge asks you to prove that you control the DNS for your domain name by putting a specific value in a TXT record under that domain name.

After you have executed the CLI command to import your automated local certificate, the ACME DNS challenge information is generated. With this information, you will configure your Public DNS Service to create the TXT record.

Certificates generated by the ACME DNS-01 challenge cannot be renewed automatically. Please manually renew the certificate before it expires.

To add the record the DNS challenge information to the Public DNS Service:

1. Obtain the ACME DNS challenge information using either of the following methods.
   
   • After you have executed the CLI command to import your automated local certificate, you will be shown the challenge information for each domain. Save this information for use later.
     

     FortiADC-VM (root) # execute certificate local import automated root-0418-dns-rsa acme100.com,acme200.com xxx@ccc.xom RSA 2048 null https://pebble:14000/dir null dns-01 1 
     [{"Domain":"acme100.com","Record":"_acme-challenge.acme100.com","Type":"TXT","Content":"2fZvf959V0SqtO4vip_Z6h0M249sg1YBRIAZwfS9poA","Note":"Some DNS managers add quotes automatically, A single set is needed"},{"Domain":"acme200.com","Record":"_acme-challenge.acme200.com","Type":"TXT","Content":"1zHG7WAYkIk_6BpcmKrCrUGX1T3yL5qh9FSoWV8wzZg","Note":"Some DNS managers add quotes automatically, A single set is needed"}]
     Done.
     

     Note: If using multiple domains, it is recommended you do not exceed 10 domains, as the excessive number of records cannot be displayed in the Local Certificate page. Which means that the DNS challenge information will only be available in this pop-up dialog, immediately after saving the certificate configuration.

   • If you missed the above information in the CLI, then you can view the information in the GUI.
     In the Local Certificate page, locate the local certificate record and click the (View icon) to see the details.
     
     Note: If the DNS challenge information exceeds the 520 character limit, then no records will be displayed in the Comments box. If there are no records in the Comments box, you can view it in the event log.
2. Login to your DNS service provider and go to your DNS Domain management page.
3. Add a record for each domain and input the challenge information into the corresponding fields.
   
   
4. Save the changes.
   The DNS configuration changes may take several minutes to take effect.

The ACME provider will then query the DNS system for that record to find a match. If there is a match, the ACME certificate passes validation (certificate status will progress from Pending → OK). However, if the record is not found within the specified challenge wait time then the certificate validation fails (certificate status is Fail).

If the certificate validation fails, then you will need to delete the record and import a new automated local certificate to try again.

It is recommended to set a longer challenge wait time to allow enough time for the DNS configuration changes to take effect. If the DNS configuration changes has not taken effect at the time the ACME provider queries the DNS system for the TXT record, then the validation will fail. Various factors may influence the speed of the DNS (such as the DNS service provider, network speed, network traffic), so the DNS configuration changes may take as long as 20 minutes to take effect.

Fulfilling the ACME TLS-ALPN-01 challenge with a placeholder certificate

FortiADC offers two options to fulfill the ACME TLS-ALPN-01 challenge: 1) select a certificate group from the Local Certificate Group field to allow FortiADC to manage the placeholder certificate generation and removal process on the backend, or alternatively 2) you can prepare the placeholder certificate prior to configuring the automated certificate using the TLS-ALPN-01 challenge.

In this section, we will cover how to fulfill the ACME TLS-ALPN-01 challenge by using a placeholder certificate.

In FortiADC, to fulfill the TLS-ALPN-01 challenge, the ACME server validates control of the domain name by connecting to the Virtual Server at one of the addresses resolved for the domain name. This is achieved by linking a certificate to an HTTPS virtual server to allow the ACME server resolving domain to point to its IP. Then FortiADC generates a temporary certificate to fulfill the validation.

Prepare the following before you configure the automated certificate using the TLS-ALPN-01 challenge:

• A valid local certificate that functions as a placeholder

• An HTTPS virtual server to link the placeholder certificate

Once the placeholder certificate has been linked to the HTTPS virtual server, you will then use the placeholder certificate name and the domain name from the virtual server to import the automated certificate using the TLS-ALPN-01 challenge. This certificate then replaces the placeholder certificate so that it will be linked to the HTTPS virtual server to fulfill the TLS-ALPN-01 challenge.

To prepare the placeholder certificate and HTTPS virtual server for the ACME TLS-ALPN-01 challenge:

1. Generate or import a local certificate. This certificate must be valid (Status is OK). Ensure the Key Type of this placeholder certificate matches the automated certificate you intend to import. For example, if the placeholder certificate is RSA, then the automated certificate you will be importing must also be RSA. Record the certificate name for use in later steps. For details, see execute certificate local or execute certificate local import automated.
   Note: If importing a local certificate, you should only import the following certificate types: Certificate, PKCS12 Certificate and Local CSR Certificate. As the placeholder certificate must be valid, it is not recommended to use an Automated certificate type for this purpose since this type of certificate cannot be valid until the ACME challenge is fulfilled.
   
2. Create a local certificate group and add the placeholder certificate you have created previously under this certificate group. Specify the placeholder certificate as the local certificate configuration. Record the certificate group name for use in later steps. For details, see config system certificate local_cert_group .
   
3. Create a Client SSL profile and add the certificate group you have created previously as the local certificate group. Record the Client SSL profile name for use in later steps. For details, see config load-balance client-ssl-profile.
4. Create an HTTPS virtual server. Apply the Client SSL profile you have created previously. For details, see config load-balance virtual-server.
   The Address of this HTTPS virtual server must be associated to a domain to ensure it can be reached by the ACME provider. It is recommended that this domain be registered at a DNS service provider so you can set the domain to point to a specific IP address. Record the domain for use in later steps.
5. Import the automated certificate using the TLS-ALPN-01 challenge type.
   Input the information for the following settings according to the guidelines below. For detailed steps, see execute certificate local import automated.
   

   Setting	Guideline
   <cert_name>	The name must match the name of the placeholder certificate. Once this automated certificate configuration is completed, it will replace the placeholder certificate.
   <domain>	Input the domain(s) of the HTTPS virtual server that has been linked to the placeholder certificate. The ACME provider will reach the domain(s) that points to the HTTPS virtual server IP address.
   <key_type>	The Key Type must match the placeholder certificate.