OpenZiti Authentication API Integrations

OpenZiti Authentication API Integrations

In the OpenZiti project, we have created an overlay network that makes network services dark. Part of that system is authenticating devices and users before they connect. The challenge is that most companies already have methods to authenticate human users and hardware devices. The challenge we faced with OpenZiti was to provide ways to integrate both users and devices through external Identity Providers (IdP). Our solution was to allow two of the fundamental building blocks of modern authentication systems to be validated by OpenZiti: x509 certificates and JWTs.

For OpenZiti to validate both of those new data model entities were created to support them:

Both have several options that are documented in the above links. The main goal of both of these entities is to allow external systems to generate signed documents (certificates and JWTs) that can be verified (if you need a refresher on this, please see this article). These documents can have variable length lifetimes and other qualities that are outside the control of OpenZiti, we must delegate trust upwards to some higher authority, a "signer." For x509 certificates, this is either an intermediate Certificate Authority (CA) or a root CA. For JWTs this is simply a certificate that creates digital signatures.

3rd party id.png

Example Public Key Infrastructure

Above is an example charter of a Public Key Infrastructure (PKI). All PKIs have one root CA that can create zero or more intermediate CAs. Each CA can in turn also sign leaf certificates - certificates that cannot sign other certificates. The interesting part is that each certificate in a PKI has a number of flags that determine what it is allowed to do beyond creating other CAs. One of those flags is the ability to digitally sign documents. One of the types of documents that can be signed are JWTs. Whether one is using x509 certificates or JWTs, there is a PKI at work behind the scenes. Services like Auth0, Okta, and Google all have PKIs they are managing for you powering certificate issuing and signing JWTS.

Identities & External Authentication & Authorization

OpenZiti Identities are a core part of authentication and authorization. Authentication in OpenZiti uses an additional field on identities called externalId. The externalId or the internal id field can be used with 3rd Party CAs and External JWT signers to match certificates and JWTs to an identity.

3rd Party CAs support x509 Claims and External JWT Signers support a claimsProperty to determine which value from the JWT or certificate should be matched against the existing set of externalId or id values.

For authorization OpenZiti supports a rich and flexible Attribute Based Access Control system (ABAC). It powers all of OpenZiti's policies. Identities support attributes so that they can be tied to policies which determine authorization.

Example JWT Authentication Flow

Above, an external Identity Provider (IdP) is signing JWTs with the sub (subject) field set to the email address of the human authenticating. This email address is also the externalId of OpenZiti identities.

Extending Authentication To Services

Using 3rd Party CAs and External JWT Signers, it is also possible to developed applications with Ziti's SDKs that can make double use of the certificates and JWTs that are used for authentication. The double uage is:

  1. Use the certificate/JWT to authenticate with an OpenZiti overlay network
  2. Use the certificate/JWT to authenticate over OpenZiti to a target service

To accomplish this, the client accessing the service over OpenZiti must:

  • be configured to accept, verify, and trust the same signers (CA or JWT) that OpenZiti does
  • the client must embed a Ziti SDK and use the same certificate or JWT to authenticate to a service on connection

Using this pattern, it is possible to tie OpenZiti network authentication and service authentication together in one neat flow.