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​

Clients 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 supports 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.

Auto External JWT Signer Enrollment​

External JWT Signers represent an external IdP that can sign JWTs as proof of identity (including OAuth/OIDC servers). Auto Ext-JWT-Signer enrollment allows a client with a JWT from a configured External JWT Signers to enroll without an administrator preconfiguring an identity for them.

For this to function, the following must be true:

  • the External JWT Signer is configured to validate incoming JWTs
  • the External JWT Signer is enabled
  • the External JWT Signer has a claimsProperty set that maps to an id value to use as externalId of enrolling identities.
  • either the enrollToCertEnable or enrollToTokenEnabled are set to true

The External JWT Signers options enrollToCertEnable and enrollToTokenEnabled are defined as follows:

  • enrollToCertEnabled - Allows clients with valid JWTs to request a certificate from the controller by providing a Certificate Signing Request (CSR). The resulting certificate will be used for authentication. The target enrollAuthPolicyId must be set to a policy that allows certificate authentication. If enrollAuthPolicyId is not set, the default policy will be used and must allow certificate authentication.
  • enrollToTokenEnabled- Allows clients with valid JWTs to continue to use JWTs for authentication. The target policy must be set to a policy that allows External JWT Signer authentication. If enrollAuthPolicyId is not set, the default policy will be used and must allow External JWT Signer authentication.

Additionally, there are optional values that can be used to control which claims within the JWT are significant:

  • enrollAttributeClaimsSelector - a root level property name (e.g. claims) or a JSON pointer (e.g. /claims) that points to a string or array of strings that will be used to populate the attributes field of the enrolling identity. Defaults to no value set and identities will enroll without attributes.
  • enrollAuthPolicyId - the id of the authentication policy to use for the enrolling identity. Defaults to no value set and the identity will enroll with the default authentication policy.
  • enrollNameClaimsSelector - the root level property name (e.g. claims) or a JSON pointer (e.g. /claims) that points to a string that will be used to populate the name field of the enrolling identity. Defaults to the subject property of the JWT (e.g. /sub)

These values are included on the OpenZiti CLI command ziti edge create ext-jwt-signer.

Identity Uniqueness​

The claimsProperty that selects the external id of the enrolling identity must be unique. Attempting to enroll with further duplicate external ids will result in an error. If desired, remove the previously enrolled identity to allow re-enrollment.

Enrollment Process​

In order for Auto External JWT Signer Enrollment to happen, a client must be used that implements the enrollment flow. This process is similar to External JWT Signer authentication (e.g. OIDC or OAuth).

  1. The client queries the public External JWT Signers list on the Client API

    GET /edge/client/v1/external-jwt-signers
    200 OK
    Content-Type: application/json

    {
        meta: {...},
        data: [
            {
                id: "20jgir0ji02",
                  "name": "Example 1",
                  "externalAuthUrl": "https://auth.example.com/login",
                  "clientId": "native",
                  "scopes": "openid profile email",
                  "openIdConfigurationUrl": "https://auth.example.com/.well-known/openid-configuration",
                  "audience": "myAudience",
                  "targetToken": "ACCESS",
                  "enrollToCertEnabled": true,
                  "enrollToTokenEnabled": false,
            },
            ...
        ]
    }

  2. The client presents a list to be selected from or selects a specific one.

  3. The client follows the authentication flow, enabling user input where necessary.

  4. The client receives a JWT from the external IdP.

  5. The client uses the JWT for enrollment. (see below)

Enrollment Token Submission​

The client can submit the JWT to the controller for enrollment that results in either certificate-based authentication (enrollToCert is true) or token-based authentication (enrollToToken is true).

Certificate Enrollment​

Certificate enrollment requires the creation of a Certificate Signing Request (CSR). The CSR can contain any values desired. However, they will be ignored by the controller. The only requirement is that a properly configured key set was used to create and sign the CSR.

POST /edge/client/v1/enroll/token
Authorization: Bearer <jwt from IdP>

<CSR>
200 OK
Content-Type: application/json

{
    "meta":{},
    "data":{}
}
200 OK
Content-Type: application/json

{
    "meta": {...},
    "data": {
        "cert": "<PEM encoded certificate chain>",
        "ca": "<PEM encoded CA certificate bundle>"
    }
}
Token Enrollment​

Token enrollment is a simple request to the controller with the JWT.

POST /edge/client/v1/enroll/token
Authorization: Bearer <jwt from IdP>

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.