How to Enroll Endpoints with your own Certificate Authority


This is helpful for creating and enrolling a.k.a. registering endpoints in bulk. You may import and verify your own CA's certificate. You may then configure the imported, trusted CA to allow one or both 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.precreated.png


# 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

This toggle in the CA's configuration allows enrolled endpoints to connect to services. Leaving this off allows for endpoints to enroll but not connect. Only the endpoints that are associated with the CA are affected.


  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 which may be rendered with values from the auto-created endpoints' user certificates to determine their endpoint names.

[caName] - replaced with the CA's name
[caId] - replaced with the CA's id
[commonName] - replaced with the common name of the enrolling certificate
[requestedName] - replaced with the name requested by the enrolling identity
[identityId] - replaced with the id of the resulting identity



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.




Was this article helpful?
0 out of 0 found this helpful



Article is closed for comments.