Skip to main content
Star us on GitHub Star

Enrollment

Enrollment is the process of some Edge client or edge router associating itself with a Ziti network. Client enrollment results in the creation of an identity or associating security credentials with a pre-provisioned identity. Ziti Router enrollment is exclusively associating security credentials with a pre-provisioned Edge Router.

Edge clients "learn" the controller's address and port when they enroll, so it is necessary to re-enroll or replace the identity if the controller's advertised address or port changes.

Routers​

Upon creation of an Edge Router, enrollment details in the form of a JWT that acts as a one-time-token become available in the enrollmentJWT field.

Create: POST /edge/management/v1/edge-routers

{
  "name": "test3"
}

Get: GET /edge/management/v1/edge-routers/PYvobLGzj

{
    "data": {
        ...,
        "name": "test3",
        "enrollmentJwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbSI6ImVyb3R0IiwiZXhwIjoxNjYwMDU4ODU5LCJpc3MiOiJodHRwczovLzEyNy4wLjAuMToxMjgwIiwianRpIjoiYjkzZjg2NTgtZGQ3ZC00NTc4LWJkYTYtMmZhZWNlZjkyMTc3Iiwic3ViIjoiUFl2b2JMR3pqIn0.UN6QiifUfCMUvzsKwjSUarl9iWyOr1zsaa_6VzNTRn7EQ_PjtHFMm9QEjj8ErtkNIbyh-vaVLZL-TPOAIZsaQX2Ye5k8-M7dbWGiQ35DbgQaJSWLMJ0xzazHYBvhZvZ9Wc5F96HKA_qTGiSq5Lsm3WraAffepEqCe_F_HwBwjBPrsgO9U23pKuoz1X8pQbAj95yoz6rBNWo63mlZDeDn7McEiJLY0i7EyPQ3paEjJ0sSntVjfmZ7aPgThoG2HCYbhvj_DkXD_HRSwMxoQHR1yIA4sW4ukdQ_S3nVMurLOG06d0VSUzlIecQSuJT8XV56AhqZ-ZNIEzp-bp2YaL1FlA",
        "enrollmentToken": "b93f8658-dd7d-4578-bda6-2faecef92177",
        ...
        "isVerified": false,
        ...
    },
    "meta": {}
}

To enroll a router, deliver the enrollmentJWT to the host that will run the edge router and perform enrollment via:

ziti router enroll -j <jwt_path>

Router Enrollment Extension​

Routers will automatically maintain their enrollment by refreshing their certificates seven days before they expire.

Clients​

Client enroll in one of two major categories:

  • pre-provisioned - identities are created before the client attempts to run and are provided with one-time-tokens to enroll
    • OTT, OTT CA
  • post-provisioned - an identity is created during enrollment
    • Auto CA

OTT Enrollment​

OTT Enrollment involves creating an identity and then delivering the enrollment JWT to client software that can then complete enrollment.

Create​

Ziti CLI​

ziti edge create identity [device|service|user] test-user10 -j ./my.token.jwt

Edge Management API​

POST /edge/management/v1/identities

{
  "name": "test-user10",
  "type": "User",
  "isAdmin": false,
  "roleAttributes": [
    "dial"
  ],
  "enrollment": {
    "ott": true
  }
}

Read​

Ziti CLI​

ziti edge list identities 'id="-ItUkLGKUE"'

Edge Management API​

GET /edge/management/v1/identities/-ItUkLGKUE

{
    "data": {
        ...
        "id": "-ItUkLGKUE",
        "tags": {},
       ...
        "enrollment": {
            "ott": {
                "expiresAt": "2022-08-09T15:37:16.619Z",
                "id": "uFtU28GKj",
                "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbSI6Im90dCIsImV4cCI6MTY2MDA1OTQzNiwiaXNzIjoiaHR0cHM6Ly8xMjcuMC4wLjE6MTI4MCIsImp0aSI6IjdjM2VmOWFkLTE2ZjAtNDk4OS05MDQ3LTNmYzFmYTE5NDgyYyIsInN1YiI6Ii1JdFVrTEdLVUUifQ.JnLlHP9wdMlfgteAf4Y-KMnxRv_00EOhEtRRmMABg_dD7xRK2RQt-bwt5rkosfgghZPR4jppuR9Prg1F1skf7JGa9Z-CmEIVvmHB8LAT6AvNnRmfkNBioD4g-Q0LP1o_xZyfePUslSxwNYPevzYYdCwgXK-TuIW34sCirX1edZ25eRtlnTUq9T0cgqMyVCEtX03WkAhb8C_TLIzhWxCwxxJTY3lgOqwuMXQEqLrWFiuG6Q1aIAA8hjh57043z5a1GQ8sUGIWP0U7YuXBWzl50VY4fenrstaaanweQLDPCZlZGPKh08mPCAGAc4Fun10hBzYaezJXGb8BpEPKXrtmLA",
                "token": "7c3ef9ad-16f0-4989-9047-3fc1fa19482c"
            }
        },
        ...
    },
    "meta": {}
}

Alternatively, enrollments for an identity can be reviewed at /edge/management/v1/identities/<id>/enrollments or /edge/management/v1/enrollments or ziti edge list enrollments.

OTT CA Enrollment​

OTT CA Enrollment requires that the enrolling client also has an existing client certificate signed by a 3rd Party CA. When creating an identity the id of the target 3rd Party CA is specified.

Create​

Edge Management API​

POST /edge/management/v1/identities

{
  "name": "test-user10",
  "type": "User",
  "isAdmin": false,
  "roleAttributes": [
    "dial"
  ],
  "enrollment": {
    "ottca": "<ott-ca-id>"
  }
}

An enrollment JWT can be retrieved in the same manner as OTT Enrollment

Auto CA Enrollment​

Auto CA enrollment allows a 3rd Party CA to have clients enroll with a Ziti network without first creating an identity or distributing a JWT enrollment token. Create a 3rd Party CA and ensure that isAutoCaEnrollmentEnabled is set to true.

The name of enrolling clients is controlled by the identityNameFormat of the 3rd Party CA. The format support a number of replacement strings:

  • [caName] - the Ziti name of the 3rd Party CA that validates the enrolling certificate
  • [caId] - the Ziti id of the 3rd Party CA that validates the enrolling certificate
  • [commonName] - the common name of the enrolling certificate
  • [requestedName] - clients can submit a requested name during enrollment
  • [identityId] - the id of the created identity

The default format is [caName] - [commonName].

Identity names are unique and if a collision occurs, incrementing numbers are appended.

Client Re-Enrollment​

Clients may request to extend enrollments that generated x509 certificates if the client certificate was issued by Ziti. If the client's certificate was issued by a 3rd Party CA, the client certificate renewal must be handled outside of Ziti.