Overview
This article outlines verifying control of an x509 certificate authority and enrolling its client certificates as endpoint identities.
- Verify your authority.
- Get an enrollment token.
- Generate a private key.
- Issue a client certificate.
- Enroll.
Verify Your Authority
- Submit the CA certificate.
- Issue the verification certificate.
- Submit the verification certificate.
Submit the CA Certificate
In the console, go to Authentication > Add a Certificate Authority. Paste your CA certificate and elect the desired CA options.
Auto-create: These identities are created just in time with the naming convention and role attributes you specify on this screen. Valid certificates from the CA may enroll with a reusable token (JWT) unique to the CA obtained from the list of certificate authorities.
Pre-create: These identities are administratively created in advance with unique names and role attributes. Valid certificates from the CA may enroll with a one-time token (JWT) from the list of endpoints.
Enable connections: Enrolled identities may authenticate. If disabled, identities with certificates from this CA cannot connect to services.
Issue the Verification Certificate
After submitting the CA certificate, obtain the verification token from the list of certificate authorities. In your CA, issue a client certificate with the verification token as the subject name, i.e., the Common Name (CN) part of the Distinguished Name (DN).
Submit the Verification Certificate
Submit the certificate's PEM form to complete the verification process.
Get an Enrollment Token
You enabled one or both CA enrollment methods in the "Submit the CA Certificate" step above and must obtain the correct token for each enrollment method. Enrollment tokens are usually stored as JWT files or QR codes, sometimes called "registration keys" or "identities."
Auto-create
Auto-created endpoint identities are provisioned at the time of enrollment. Obtain the reusable enrollment token (JWT) from the list of certificate authorities.
Pre-create
When administratively creating identities in advance of enrollment, you must select your verified CA. After creation, obtain the one-time enrollment token (JWT) from the endpoint identity screen.
Generate a Private Key
Each endpoint identity will have a private key. RSA >= 2048 and Elliptic Curve P224, P256, P384, and P521 are supported. For security, generate the key (PEM) on the device where it will be used.
Issue a Client Certificate
In your CA, issue a client certificate for each endpoint identity. Store the client certificate (PEM) where the private key was generated on the endpoint device.
Enroll
This final step composes an enrollment request using the enrollment token (JWT), client certificate (PEM), and private key (PEM). Successful enrollment produces an endpoint identity configuration file (JSON) that may be used with any OpenZiti tunneler or Edge SDK to dial or bind services.
Enrolling with the ziti CLI
Install the CLI from a download or Linux package
ziti edge enroll \
--cert endpoint100.cert.pem \
--key endpoint100.key.pem \
--jwt endpoint100.ott.jwt \
--out endpoint100.json
References
- Bootstrapping Trust - A blog series about cryptographic trust
- 3rd Party CAs - documentation about using x509 authorities external to OpenZiti
Auto-Created Endpoint Name Format
Auto-created endpoint identities are provisioned at the time of enrollment. You may use these tokens in the naming convention template when creating or updating your CA to influence the name of the enrolled endpoint identity.
- [caName] - replaced with the CA name
- [caId] - replaced with the Ziti ID of the CA
- [commonName] - replaced with the CN of the endpoint's user certificate
- [requestedName] - replaced with the custom name specified at the time of enrollment
- [identityId] - replaced with the Ziti ID of the endpoint
Comments
0 comments