Skip to main content
Star us on GitHub Star

Authentication

Authentication in Ziti Edge occurs when a client wishes to interact with the Ziti Edge Controller. Authentication has begun when the client receives and API Session and is complete when the API Session is fully authenticated. API Sessions are a high level security context that represents an authenticated session with either the Ziti Edge Client API or the Ziti Edge Management API.

  • Clients that are powered by a Ziti SDK that access services will authenticate with the Edge Client API
  • Clients that are managing a Ziti Network will authenticate with the Edge Management API

Authentication Flow​

Below is diagram showing initial authentication for some client. The same model is used between the Edge Client API and Edge Management API.

In the above a client has provided primary authentication credentials (certificate, JWT, username password) and then subsequently provided any secondary credentials necessary (JWT, TOTP, etc). The secondary credentials are requested via Authentication Queries and enable multifactor authentication to occur.

The goal of authentication is to obtain an API Session. API Sessions are used to interact with the Ziti Controller and Ziti Edge Routers. API Sessions for clients are represented by opaque tokens that are provided as headers in HTTP requests and by values in protobuf messages for the Edge protocol between routers and SDKs. API Sessions represent a security context that is used to determine authorization in the rest of the Ziti network.

API Sessions​

API Sessions are represented by opaque strings and are provided in the HTTP header zt-session and in Edge Router connection requests initiated by Ziti SDKs. API Sessions are subject to timeouts based on activity and have data removal implication. See the full API Session documentation.

Primary Authentication​

Primary authentication in Ziti establishes and API Sessions identity principal and enabled Ziti to determine which secondary authentication factors are necessary for an API Session to become fully authenticated. If no secondary authentication factors are required the API Session becomes fully authenticated immediately without any further interaction with the Client or Management API.

Primary authentication factors include:

  • x509 certificates
  • JWTs
  • Username/password

Valid primary authentication methods can be restricted via Authentication Policies. An Identity can have one Authentication Policies associated with it. This association is defined by the authPolicyId property on the identity. If noAuthentication Policy is set for an Identity, a special system defined Authentication Policy with the id of default will be used.

Authenticators​

Some primary authentication mechanisms (x509, username/password) need to store per-identity credentials. When necessary, these are stored as authenticators. Authenticators are manipulated using password management and certificate management.

Authenticators may be listed via the CLI:

ziti edge list authenticators

or via the Edge Management API:

GET /edge/management/v1/authenticators

x509 Certificate Primary Authentication​

x509 authentication requires the client to initiate a HTTPs authentication request using a x509 client certificate that is associated to the target Identity on an Authenticator. The client certificate can be issued by the Ziti Edge Controller's internal PKI or an external PKI. If an external PKI is being used, it must be registered as a 3rd Party CA via the Ziti Edge Management API, verified, and have authentication enabled. The client certificate must pass signature and CA chain-of-trust validation. All client, intermediate CA, and root CA functionality supports RSA and EC keys.

Please note that intermediate CA certificates may be provided during authentication if necessary. The client certificate should be in index zero and intermediate CA certificates in subsequent indexes in any order.

To associate a client certificate with an Identity and Authenticator see the Enrollment section.

Expired client certificates may be allowed via Authentication Policies if desired.

JWT Primary Authentication​

JWT authentication requires that an External JWT Signer be added via the Ziti Edge Management API. The definition of External JWT Signer allows configuration of which JWT claim should be used as a value to map against the unique externalId or id property on Identities. This mapping of JWT claim to externalId/id is used to determine which Identity is authenticating.

The JWT must be provided in the HTTP request in the Authentication header with a value in the format of Bearer <jwt>. The JWT provided must pass signature, expiration, issuer, and audience validation as configured on the External JWT Signer.

Username/password​

An internal username/password authentication system is provided for smaller deployments of Ziti. It is highly suggested that all username/password authenticators be replaced by x509 certificate/JWT authentication mechanisms. Passwords are stored individually salted and one-way cryptographically hashed using Argon2id.

Password policies may be enforced via Authentication Policies. Administrative management of passwords is also available.

Username/password authentication, while supported, is only suggested to be used for testing and R&D activities. For production environments JWT and X509 authentication is recommended.

Secondary Authentication​

Secondary authentication is represented by a series of Authentication Queries on an API Session in the authQueries property. At present the following secondary authentication mechanisms are supported:

  • TOTP - Time-Based One-Time Password (aka Authenticator Apps)
  • JWT - JSON Web Tokens

TOTP: Time-Based One-Time Password​

Ziti supports all authenticator application that implement RFC6238 which includes all major and popular TOTP applications such as Google Authenticator, Microsoft Authenticator, Authy, and many others.

TOTP is configured per-identity and must be client initiated due to the symmetric key exchange that must take place. Administrators can enforce TOTP usage through Authentication Policies and Posture Checks. Authentication Policy enforcement stops the client from transitioning between partially authenticated and fully authenticated status. This stops a client from accessing any service information or connect to any service. Posture Check enforcement allows a client to fully authenticate, but based on Service Policy restrict connection to specific services.

JWT​

Similar to JWT primary authentication, a valid JWT must be present in the Authentication header in the format of bearer <JWT> on every request.

Authentication Requests​

Example UPDB Authentication Request​

POST /edge/client/v1/authenticate?method=password

{
  "username": "my-name",
  "password": "my-password"
}

Example Client Certificate Request​

Note: The TLS connection to the controller MUST use a valid client certificate

POST /edge/management/v1/authenticate?method=cert

{}

Example JWT Authentication Request​

POST /edge/client/v1/authenticate?method=ext-jwt HTTP Header: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cC...

{}

Example TOTP Authentication Query Response​

POST /edge/client/v1/authenticate/mfa

{
  "code": "123456"
}