Skip to main content

Create and verify a certificate authority

This guide walks you through the end-to-end process of integrating a 3rd-party Certificate Authority (CA) with the NetFoundry platform. Beyond the initial creation, this guide covers the cryptographic verification required to establish trust and the retrieval of the Network JWT used to trigger automated client enrollment. By using your own CA, you can leverage existing organizational Public Key Infrastructure (PKI) to manage identities and define custom authentication behaviors across your overlay network.

Create the CA​

  1. From the console, select your network from the dropdown in the left-hand menu.

  2. Click Authentication from the same menu.

  3. Click the Certificate Authorities tab.

  4. Click the plus icon (+) to open the Create Certificate Authority form.

  5. Fill in the required fields:

    • Name: Enter a unique name for the CA (e.g., NetFoundry-CA).

  6. (Optional) Configure the identity name format:

    • Identity Name Format: Enter a template that defines how a new identity's name will be constructed when it enrolls. By default, it uses the CA name and the certificate's common name ([caName]-[commonName]).

  7. (Optional) Configure the policy attributes:

    • Identity Roles: Enter the role attributes that should be automatically assigned to any identity that enrolls using this CA (e.g., #hr-user).

  8. Configure Enrollment Options (at least one must be enabled):

    • Auto Enroll: Toggle to YES to allow client identities to automatically enroll if they present a valid certificate issued by this CA.
    • OTT Enroll: Toggle to YES to allow identities to use the one-time token (OTT) enrollment method, but with certificates signed by this CA instead of the NetFoundry internal CA.
    • Auth Enabled: Toggle to YES to allow identities signed by this CA to successfully authenticate to the network.

  9. Configure External ID Claim (optional, used for third-party CAs):

    • Toggle External ID Claim to ON. This allows the CA to parse fields from the certificate to populate the identity's External ID field, which is used for integration with Identity Providers (IdPs).
    • Location: Select where the claim data is located within the certificate (e.g., Subject, SAN, or Issuer).
    • Matcher: Define how to match the data (e.g., Exact, Regex).
    • Parser: Define how to extract the claim data from the matched field.

  10. Provide the Certificate Authority (required for third-party CA):

    • Paste PEM: Paste the contents of the CA's public certificate file (in PEM format) into the text box, or click Select File to upload the file.

  11. (Optional) Toggle Show more options to ON to configure custom tags:

    • Custom tags: Use the Name and Value fields to attach non-functional metadata to the CA for tracking or inventory purposes.

  12. Click Save.

    The new Certificate Authority is now active. You can associate it with an identity provider for enrollment or use it to validate existing certificates within your environment.

Verify the CA​

Uploading the CA is only the first half of the process. You must now verify the CA to prove you own the private key associated with the certificate you uploaded. This Proof of Possession (PoP) is a security step that prevents unauthorized users from importing public CAs they don't control.

  1. In the Certificate Authorities table, click the three dots (ellipsis) for your new CA and select Verify.

  2. Copy the Token to your notepad.

    note

    This token is a random string intended to be used as a Common Name (CN) for a verification certificate.

  3. Use your PKI tools (like OpenSSL) to generate a certificate signed by your CA where the Common Name is exactly the token provided by the console.

  4. In the Verification modal, click Select File and upload the resulting signed certificate.

  5. Click Verify.

    Once verified, the CA will show a green checkmark in the Verified column.

Use the Network JWT​

After verification, the CA can be used for automated enrollment. To facilitate this, you must provide a specific Network JWT to your clients.

  1. In the Certificate Authorities table, click the certificate icon in the JWT column.

  2. Download the .jwt file.

  3. Provide this JWT to your users or embed it in your edge clients (like the Ziti Desktop Edge). When the client attempts to join the network using this JWT, the console will prompt for the identity's certificate and key to complete the enrollment.