Installing ACME Responder using PKI Server ACME CLI - dogtagpki/pki GitHub Wiki

Overview

This document describes the process to install an ACME responder on a PKI server that already has a CA subsystem using pki-server acme commands.

In general pki-server acme commands provide a more flexible way compared to pkispawn for installing ACME responder. If there is a problem during installation, usually only the failing step needs to be fixed, then the installation can be resumed.

Prerequisites

This document assumes that the following DS service is available to use as ACME database and ACME realm:

  • URL: ldap://ds.example.com:3389

  • Bind DN: cn=Directory Manager

  • Bind password: Secret.123

It also assumes that the following CA service is available to use as ACME issuer:

Creating ACME Responder

To create ACME responder in PKI server execute the following command:

$ pki-server acme-create

The command will create the initial configuration files in /var/lib/pki/pki-tomcat/conf/acme folder.

Setting Up ACME Metadata

To configure ACME metadata:

$ pki-server acme-metadata-mod
The current value is displayed in the square brackets.
To keep the current value, simply press Enter.
To change the current value, enter the new value.
To remove the current value, enter a blank space.

Enter the location of the terms of service.
  Terms of Service [https://www.example.com/acme/tos.pdf]:

Enter the location of the website.
  Website [https://www.example.com]:

Enter the CAA identities.
  CAA Identities [example.com]:

Enter true/false whether an external account is required.
  External Account Required [false]:

See also Configuring ACME Metadata.

Setting Up ACME Database

To configure ACME database:

$ pki-server acme-database-mod
The current value is displayed in the square brackets.
To keep the current value, simply press Enter.
To change the current value, enter the new value.
To remove the current value, enter a blank space.

Enter the type of the database. Available types: ds, in-memory, ldap, openldap, postgresql.
  Database Type: ds

Enter the location of the LDAP server (e.g. ldap://localhost.localdomain:389).
  Server URL [ldap://localhost.localdomain:389]: ldap://ds.example.com:3389

Enter the authentication type. Available types: BasicAuth, SslClientAuth.
  Authentication Type [BasicAuth]:

Enter the bind DN.
  Bind DN [cn=Directory Manager]:

Enter the bind password.
  Bind Password [********]: Secret.123

Enter the base DN for the ACME subtree.
  Base DN [dc=acme,dc=pki,dc=example,dc=com]:

To import the DS schema for ACME database:

$ ldapmodify \
    -H ldap://ds.example.com:3389 \
    -D "cn=Directory Manager" \
    -w Secret.123 \
    -f /usr/share/pki/acme/database/ds/schema.ldif

To create the DS indexes for ACME database:

$ ldapadd \
    -H ldap://ds.example.com:3389 \
    -D "cn=Directory Manager" \
    -w Secret.123 \
    -f /usr/share/pki/acme/database/ds/index.ldif

To create the DS subtrees for ACME database:

$ ldapadd \
    -H ldap://ds.example.com:3389 \
    -D "cn=Directory Manager" \
    -w Secret.123 \
    -f /usr/share/pki/acme/database/ds/create.ldif

See also Configuring ACME Database.

Setting up ACME Issuer

To configure ACME issuer:

$ pki-server acme-issuer-mod
The current value is displayed in the square brackets.
To keep the current value, simply press Enter.
To change the current value, enter the new value.
To remove the current value, enter a blank space.

Enter the type of the certificate issuer. Available types: nss, pki.
  Issuer Type: pki

Enter the location of the PKI server (e.g. https://localhost.localdomain:8443).
  Server URL [https://localhost.localdomain:8443]: https://pki.example.com:8443

Enter the certificate nickname for client authentication.
This might be the CA agent certificate.
Enter blank to use basic authentication.
  Client Certificate:

Enter the username of the CA agent for basic authentication.
Enter blank if a CA agent certificate is used for client authentication.
  Agent Username [caadmin]:

Enter the CA agent password for basic authentication.
Enter blank if the password is already stored in a separate property file
or if a CA agent certificate is used for client authentication.
  Agent Password [********]: Secret.123

Enter the certificate profile for issuing ACME certificates (e.g. acmeServerCert).
  Certificate Profile [acmeServerCert]:

See also Configuring ACME Issuer.

Setting Up ACME Realm

To configure the ACME realm:

$ pki-server acme-realm-mod
The current value is displayed in the square brackets.
To keep the current value, simply press Enter.
To change the current value, enter the new value.
To remove the current value, enter a blank space.

Enter the type of the realm. Available types: ds.
  Database Type: ds

Enter the location of the LDAP server (e.g. ldap://localhost.localdomain:389).
  Server URL [ldap://localhost.localdomain:389]: ldap://ds.example.com:3389

Enter the authentication type. Available types: BasicAuth, SslClientAuth.
  Authentication Type [BasicAuth]:

Enter the bind DN.
  Bind DN [cn=Directory Manager]:

Enter the bind password.
  Bind Password [********]: Secret.123

Enter the base DN for the ACME users subtree.
  Users DN [ou=people,dc=acme,dc=pki,dc=example,dc=com]:

Enter the base DN for the ACME groups subtree.
  Groups DN [ou=groups,dc=acme,dc=pki,dc=example,dc=com]:

To create DS subtrees for ACME realm:

$ ldapadd \
    -H ldap://$HOSTNAME \
    -x -D "cn=Directory Manager" \
    -w Secret.123 \
    -f /usr/share/pki/acme/realm/ds/create.ldif

See also Configuring ACME Realm.

Deploying ACME Responder

Once everything is ready, deploy the ACME responder with the following command:

$ pki-server acme-deploy

The command will create a deployment descriptor at /var/lib/pki/pki-tomcat/conf/Catalina/localhost/acme.xml.

The server will start the ACME responder automatically in a few seconds. It is not necessary to restart PKI server.

Verifying ACME Responder

To verify that the ACME responder is running, execute the following command:

$ curl -s -k https://pki.example.com:8443/acme/directory | python -m json.tool
{
    "meta": {
        "caaIdentities": [
            "example.com"
        ],
        "externalAccountRequired": false,
        "termsOfService": "https://www.example.com/acme/tos.pdf",
        "website": "https://www.example.com"
    },
    "newAccount": "https://pki.example.com:8443/acme/new-account",
    "newNonce": "https://pki.example.com:8443/acme/new-nonce",
    "newOrder": "https://pki.example.com:8443/acme/new-order",
    "revokeCert": "https://pki.example.com:8443/acme/revoke-cert"
}

Undeploying ACME Responder

To undeploy the ACME responder execute the following command:

$ pki-server acme-undeploy

The command will remove the deployment descriptor at /var/lib/pki/pki-tomcat/conf/Catalina/localhost/acme.xml.

The server will stop the ACME responder automatically in a few seconds. It is not necessary to restart PKI server.

To restart the ACME responder, execute pki-server acme-deploy again.

Removing ACME Responder

To remove the ACME responder execute the following command:

$ pki-server acme-remove

See Also

Tip
 To find a page in the Wiki, enter the keywords in search field, press Enter, then click Wikis.
⚠️ **GitHub.com Fallback** ⚠️