Skip to main content

Enrollment and trust

The term enrollment is the process of securely associating a specific identity (client or router) with the controller and the NetFoundry network. The method of association depends on the authentication strategy you choose.

One-time token (OTT) enrollment (standard client/router)​

This is the most common path for enrollment. During this process, the identity client generates a private key locally (which never leaves the device) and sends a Certificate Signing Request (CSR) to the controller to obtain a signed certificate.

  1. Creation: When you choose OTT as the enrollment type and create the identity, the controller generates a single-use token, delivered as a JWT.

  2. Delivery: You must securely deliver this token to the client device. The NetFoundry console allows you to deliver this token using the .jwt file, a QR code, or by emailing the token file directly to the user.

    warning

    The JWT contains a secret and is vulnerable to interception during delivery. Even though it's a single-use token (OTT), anyone who possesses the token can use it to enroll an identity. Always treat the token as a sensitive secret and ensure the delivery method is secure.

  3. Completion: The identity client software (e.g., the desktop or mobile edge) completes the enrollment. For an in-depth look at this process, see Bootstrapping Trust Part 1 on the OpenZiti Tech Blog.

important

Once the identity enrolls, the one-time token is immediately consumed and can't be used again.

External JWT signers (pre-configured trust)​

External JWT signers establish an external trust model. Instead of the standard enrollment process where the controller issues a specific credential to the identity, you configure the controller to trust the credentials (tokens) issued by an external entity, such as an IdP.

  • Trust configuration: You configure the trust relationship (using an External JWT signer) where the controller verifies the signature of tokens issued by the external entity.
  • Authentication flow: When a client attempts to connect, they present a JWT obtained from the external IdP. The controller validates the JWT against the configured External JWT signer, and if successful, maps the token's claims to a NetFoundry identity for authentication and authorization.
  • Use case: This is the primary method for integrating external identity systems (like Azure AD, Okta, or Auth0), allowing you to manage user access via your existing IAM infrastructure rather than issuing new NetFoundry certificates.

External certificate authorities (PKI integration)​

If you need to extend trust to another certificate authority (CA) and are capable of managing that CA, the NetFoundry overlay network is capable of integrating its trust model.

  • Trust model: You configure your overlay network to trust CAs external to the controller. Certificates that aren't created by the controller are referred to as external certificates.
  • Validation: When an identity presents an external certificate, the controller validates it against the external CA you've imported.
  • Use case: This allows you to reuse existing Public Key Infrastructure (PKI) to manage strong identities for your fleet of devices and servers.

Username/password database (UPDB) (legacy API access)​

The UPDB enrollment type is exclusively used for Controller API access and isn't recommended for production Edge client devices.

  • Function: This type requires a plaintext username and password for authentication against the controller's API.
  • Recommendation: For administration, it's strongly recommended to create a dedicated administrative identity and use the secure OTT enrollment method for API access instead of UPDB.