Creating

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 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 controller is capable of using an existing PKI for authentication and authorization rather than to PKI configured in the controller. Certificates that are not controlled by the 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 controller. After using an existing PKI to reuse/generate a certificate, the 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 controller is easy using the console.

New CA via UI

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

New CA via REST

    Verb: POST

    name:
      The name of the CA to create
    isAutoCaEnrollmentEnabled:
      controls if the CA can be used for automatic enrollment
    isOttCaEnrollmentEnabled:
      controls if the CA be used for one time token enrollment
    isAuthEnabled:
      controls if the CA is enabled for authentication. Devices can enroll but not connect if set to false
    certPem:
      the CA to upload in PEM format
    body:
    {
      "name": "${string}",
      "isAutoCaEnrollmentEnabled": ${true|false},
      "isOttCaEnrollmentEnabled": ${true|false},
      "isAuthEnabled": ${true|false},
      "certPem": "${string}"
    }

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 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 identities and 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 the edge. This enrollment method allows for device provisioning processes to skip the manual configuration of the 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 edge 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.

New 3rd Party CA Identity via UI

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

New 3rd Party Identity via CLI

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

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.