Skip to main content
Star us on GitHub Star

Ziti Identities

Ziti is built on the foundation of zero trust. A solid pillar of that foundation requires that all connections in a Ziti-enabled network are authenticated. Identities are the basis for Ziti authentication. All devices connecting to a Ziti network will have an Identity which is presented at the time of a connection being established by both the device initiating the connection and the device receiving the incoming connection. Ziti implements mutual TLS in order to authenticate both sides of a connection.

Conceptually an identity can be thought of as congruent to a user account. Identities are logical entities stored inside the Ziti Controller which map an X509 certificate to a particular named identity. Identities exist not only to authenticate connections but are also used to authorize identities within Ziti. See Policies for more information on authorization of identities.

3rd Party Certificates​

The certificate a Ziti Edge client presents can be generated by the Ziti Controller using the configured PKI or this certificate can come from an existing PKI not controlled by the Ziti Controller. Certificates which are not created by the Ziti Controller are referred to as "3rd Party" because from the perspective of the Ziti Controller the certificates are not from the configured PKI.

Creating an Identity​

The mechanism for creating identities is influenced by how your Ziti network is setup, specifically how the PKI is established. Identities are integrally linked to the PKI configured in a given Ziti network and directly affects how identities are created and enrolled. There are generally three enrollment methods for identities:

  • One Time Token (ott) identities using the configured PKI
  • One Time Token (ott) identities using a 3rd Party CA
  • 3rd Party auto-enrolled identities

Choosing an Enrollment Method​

Choosing which type of enrollment your identity will use comes down to whether you are using a 3rd Party CA or not. If the network does not have a 3rd Party Certificate configured the only option is to use the One Time Token (OTT) enrollment method.

If one or more 3rd Party CA is installed you will need to understand the intention of each 3rd Party certificate.

Each of the types of enrollments are secure it just depends on your actual network setup as to which type to choose. If you don't know - just use the One Time Token (OTT) method. The identity can always be recreated at a later date if necessary.

One Time Token (OTT)​

The One Time Token method is available to all Ziti networks. A one time token enrolled identity will have a token generated at the time of the identity's creation. This token is then submitted at some point in the future as part of the enrollment process. Once an identity is successfully enrolled - the one time token is no longer valid and cannot be used to enroll the same identity again.

One time tokens are delivered from the Ziti Controller as a jwt and the token expires 24 hours after the identity is created. The token is downloadable via the Ziti Admin Console. After you create a user you can go to the Identities page and click the icon that looks like a certificate to download the .jwt file.

You can also create an identity for one time token enrollment using the ziti cli tool. This command will create a new identity and output the jwt to the selected path. You can then transfer the .jwt file to the device where the permanent identity JSON file will be installed by running the enroll command.

#creates a new user named "NewUser"
ziti edge create identity user "NewUser" -o NewUser.jwt

3rd Party CA - Overview​

The Ziti Controller is capable of using an existing PKI for authentication and authorization rather than to PKI configured in the Ziti Controller. Certificates that are not controlled by the Ziti Controller are referred to as "3rd party". If you have an existing PKI setup you wish to reuse or if you are just interested in learning how to use a 3rd Party CA this section is for you.

info

Reusing a PKI is not a simple topic and managing and maintaining a PKI is out of the scope of this guide.

A 3rd Party CA will need to be created and the public certificate uploaded into the Ziti Controller. After using an existing PKI to reuse/generate a certificate, the Ziti Controller will be to create identities which will be expected to present a certificate during the connection process that is valid per the provided certificate.

Adding a 3rd Party CA to the Ziti Controller​

Adding a certificate to the Ziti Controller is easy using the Ziti Console.

  1. On the left side click "Certificate Authorities"
  2. In the top right corner of the screen click the "plus" image to add a new Certificate Authority
  3. Enter the name of the Certificate Authority you would like to create
  4. Choose if the CA should be used for Enrollment (yes) and Auth (yes)
  5. Click save

3rd Party CA - One Time Token​

3rd Party CA OTT enrollment is closely related to OTT Enrollment. The main difference is the utilization of a 3rd party CA certificate rather than the configured Ziti Edge CA and PKI. In this method, the system does not have access to the 3rd party CA private key and thus cannot provide CSR fulfillment capabilities. Instead it is assumed that the enrolling device has a separate process to acquire signed certificates. Rather than submitting a CSR the client uses an already acquired signed certificate as its client certificate for the enrollment request. The client certificate is validated against the CA certificate tied to the one time token.

Similar to the OTT Enrollment process, identities must be provisioned ahead of enrollment in order to generate one time token required and to creat the jwt that can be delivered to enrolling devices. This means that the provisioning of the Ziti Edge identities and the client certificates must be coordinated. Identities can be enrolled with a one time token flow similar to the one time token flow.

3rd Party CA - Auto Enrolled​

CA Auto Enrollment is useful in situations where devices are provisioned with certificates en-mass that need to be able to register as identities within Ziti Edge. This enrollment method allows for device provisioning processes to skip the manual configuration of Ziti Edge and instead allow clients to present a signed client certificate to generate an identity during the enrollment process. The identity will grant the client access to authenticate only - any authorization will need to be done after the device identities have been created.

A certificate can only be used for one identity. The Ziti Edge system does not allow the same certificate to be used for multiple identities. An enrollment request is comprised of a special enrollment URL used to perform an HTTP POST request using the signed client certificate as the TLS client certificate and an optional JSON payload that allows the client to specify the devices display name and internal username. See enrollment for more details on enrolling.

  1. On the left side click "Certificate Authorities"
  2. In the top right corner of the screen click the "plus" image to add a new Certificate Authority
  3. Enter the name of the Certificate Authority you would like to create
  4. Choose if the CA should be used for Enrollment (yes) and Auth (yes)
  5. Click save

Choosing an Identity Type​

The three types of identities are:

  • User
  • Device
  • Service

These are functionally equivalent and have identical properties. You may wish to express the intended purpose of an identity by choosing one or another type when the identity is created. The type can not be changed.

Enrolling an Identity​

All connections made to the Ziti network leverage mutual TLS which means every client needs a valid X509 certificate which it will present to the Ziti network during the connection process. The process of obtaining a key/certificate pair and presenting it securely to the Ziti Controller is called "Enrollment".

Overview​

All identities need to be enrolled with the Ziti Controller so the Ziti Controller can authenticate the incoming connection. This process is slightly different for each type of identity and is complex. The easiest way to enroll an identity is to use either the Ziti Desktop Edge/Ziti Mobile Edge for your operating system. Alternatively, you may perform the enrollment separate with the ziti CLI which can be downloaded from the GitHub releases page

One Time Token Enrollment - Internal PKI​

Perhaps the easiest path to an enrolled identity is by using the one-time token enrollment flow. This flow leverages the PKI configured in the Ziti Controller. Using the one-time token flow - the ziti CLI will generate a private key and a certificate signing request for the Ziti Controller's built-in certificate authority to fulfill.

Follow these steps to enroll an identity with a one-time token:

  • create the Identity
  • download or copy the JWT - this file contains the single use token
  • run the ziti CLI:

Example Usage:

ziti edge enroll \
    --jwt ${jwt_file} \
    --out ${identity_config_file}
caution

The output from the ziti CLI is a permanent identity configuration file which must be stored securely. This file contains within it the private key that backs the certificate issued by the Ziti Controller. This file should not be transferred or shared and should not be moved from the machine unless you are confident you understand the risks involved in doing so.

Example Usage for ziti-edge-tunnel CLI

# enroll from a token file
./ziti-edge-tunnel enroll --jwt ./myTunneler.jwt --identity ./myTunneler.json
# enroll from stdin
./ziti-edge-tunnel enroll --jwt - --identity ./myTunneler.json < ./myTunneler.jwt

3rd Party CA - One Time Token​

This flow allows you to pre-create identities for a 3rd party CA with distinct role attributes. This flow is similar to the One Time Token flow from above except that it expects that a private key and certificate have already been created on or distributed to the machine that is about to enroll and that the certificate presented is issued by a validated, third party CA.

Follow these steps to enroll a 3rd Party CA - one-time token identity:

  • create the Identity
  • download or copy the JWT - this file contains the one-time token
  • run the ziti CLI. Notice you can provide the filename of the identity config JSON file to output:

Example Usage:

ziti edge enroll \
    --cert ${user_certificate} \
    --key ${user_private_key} \
    --jwt ${one_time_jwt_file} \
    --out ${identity_config_file}

3rd Party CA - Auto​

When using a third party CA identity creation process in the Ziti Controller is automatic. Enrolling the identity will create it with the default role attributes that were specified when the 3rd party CA was created.

Like "3rd Party CA - One Time Token" - this flow expects that a private key and certificate have already been created on or distributed to the machine that is about to enroll. The certificate presented to the Ziti Controller must be issued by a third party CA that was already imported and verified in the Ziti Controller with the isAutoCaEnrollmentEnabled property set to true.

Using the ziti CLI will also require the re-use of a permanent JWT that is unique to the external CA. The JWT can be downloaded from the Ziti Controller from: ${controller_uri}/cas/${id}/jwt where ${controller_uri} represents the fully qualified address of the Ziti Controller api and ${id} represents the identifier for the given third party CA.

Example Usage:

ziti edge enroll \
    --cert ${user_certificate} \
    --key ${user_private_key} \
    --jwt ${reusable_ca_jwt_file} \
    --out ${identity_config_file}

If supplied, the argument to option --idname will be used as the name for the identity created. The default name of auto-created identities is generated from a template that uses values from the user certificate i.e. [caName]-[commonName].