How to Enroll Endpoints with your own Certificate Authority

Follow

You may import and verify your own certificate authority. This is helpful for creating endpoints in bulk. You will need to issue a user certificate for each device. You may then configure your verified CA to allow either of two methods of creating endpoints associated with that external CA: auto-enroll or one-time-token enroll, elaborated below. The "enroll" command permanently associates the user certificate from your external CA with a Ziti network as a unique identity. 

The three CA options pictured above are explained later in this article.

1. Allow auto-create
2. Allow pre-create
3. Enable connections

Verify your External CA By Issuing a User Certificate

After importing your CA certificate you must issue a special user certificate to prove you have the ability to issue a user certificate for each endpoint that will use this CA. The verification certificate's common name must exactly match the verification token, an alphanumeric string, as the common name (CN) property of the certificate.

For example, if your imported CA verification string is "3RreW5SmNT", then your verification certificate might have a Subject like this:

❯ openssl x509 -noout -subject < ~/pki/intermediate/certs/3RreW5SmNT.cert
subject=C = US, L = Charlotte, O = Cold River, OU = us-west, CN = 3RreW5SmNT

 

Endpoint Enrollment Methods

There are two endpoint enrollment methods you may use with your external CA. You may choose to allow either or both methods when you configure the external CA. The main difference is whether or not the endpoint is created automatically on-the-fly with the CA's default attributes or created in advance with custom attributes. The enroll command line options are very similar for these two approaches. For both enrollment methods the following parameters to the ziti edge enroll command are required:

1. cert: path to the user certificate issued by your external CA
2. key: path to the private key that backs the user certificate
3. jwt: path to enrollment token file (CA token or endpoint token, depending on enrollment method)
4. out: path in which to write the identity configuration JSON file

The output configuration JSON file provides the necessary file paths for the user certificate and private key to the Ziti Edge SDK or tunneler that will use this endpoint identity.

Ziti CLI

You may obtain the the ziti management CLI that is used in the following examples by downloading from GitHub. You may also perform the enrollment using the tunneler CLI "ziti-tunnel" from GitHub. All of the CLIs provide built-in help to guide you to the appropriate arguments and options.

Pre-Create Enroll Method

You will need to pre-create an endpoint and download its one-time enrollment token as a JWT file with the "download key" button. This method is useful for bulk-creating endpoints in advance with custom names and custom hashtag role attributes. The endpoint will already be visible in the web console and API but will not become "registered" and eligible for connections until this enroll command is executed.

# pre-created endpoint example using the tunneler CLI
$ ziti-tunnel enroll \
    --cert ./magenta-endpoint-01.cert \
    --key ./magenta-endpoint-01.key \
    --jwt ./magenta-endpoint-01-ott.jwt \
    --out ./magenta-endpoint-01-config.json

# pre-created endpoint example using management CLI
$ ziti edge enroll \
    --cert ./magenta-endpoint-01.cert \
    --key ./magenta-endpoint-01.key \
    --jwt ./magenta-endpoint-01-ott.jwt \
    --out ./magenta-endpoint-01-config.json

Auto-Create Enroll Method 

You will need to download the CA's enrollment token from the list of CAs in the web console as a JWT file. This method is useful for bulk-creating endpoints on-the-fly with the CA's default hashtag role attributes and with generated names based on values from the user certificate. The endpoint becomes visible and "registered" in the web console and API soon after this enroll command is executed.

# auto-created endpoint example using the tunneler CLI
$ ziti-tunnel enroll \
    --cert ./magenta-endpoint-01.cert \
    --key ./magenta-endpoint-01.key \
    --jwt ./magenta-intermediate-ca.jwt \
    --out ./magenta-endpoint-01-config.json

# auto-created endpoint example using the management CLI
ziti edge enroll \
    --cert ./magenta-endpoint-01.cert \
    --key ./magenta-endpoint-01.key \
    --jwt ./magenta-intermediate-ca.jwt \
    --out ./magenta-endpoint-01-config.json

Enable Connections

Scenarios

1. You could leave this option disabled while enrollment occurs, and then at a later time enable this option to begin allowing those endpoints to connect. 
2. If you experience a security incident affecting your CA you may disable authentication to prevent existing endpoints from creating new sessions.

Endpoint Name Format

Provide a template for the auto-created endpoint names.

• [caName] - replaced with the CA name
• [caId] - replaced with the Ziti ID of the CA
• [commonName] - replaced with the CN of the endpoint's user certificate
• [requestedName] - replaced with the custom name specified at the time of enrollment
• [identityId] - replaced with the Ziti ID of the endpoint

Troubleshooting

It is not necessary to import the root CA certificate if your user certificates are issued by an intermediate CA. Only the issuer CA certificate is imported.

References

• Bootstrapping Trust (OpenZiti)
• Overview of CA enrollment (OpenZiti)
• How to Build Your Own PKI (CloudFlare)