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
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 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 remain valid as long they have not timed out.
An API Sessions:
- can and are represented by a JSON data structure returned from the Client and Management APIs
- returned from:
- returned from:
- can be referenced by an internal
idand a security token that is in the format of a UUID
idcan be used on the following endpoints:
API Sessions are defined in the Client and Management Open API 2.0 specifications under
POST /edge/management/v1/authenticate response:
"name": "Default Admin"
Full vs Partial Authentication
API Sessions may exist in two states:
- Partially Authenticated - limited API access
- Fully Authenticated - full API access
Partial authentication occurs when a primary authentication method has been passed, but secondary Authentication Queries remain outstanding. Ziti Edge models MFA challenges as Authentication Queries. Authentication Queries include information that can be used to display user prompts or direct users to integrating websites for SSO. If no outstanding Authentication Queries are present for an API Session it is considered fully authenticated.
While partially authenticated, the API Session can only be used for a reduced set of operations:
- answering Authentication Queries
- enrolling in MFA TOTP
Authentication Queries are represented on an API Session the property
authQueries which is an array. An example
MFA challenge represented as an Authentication Query is provided below.
The existence of any Authentication Query on an API Session represents a partial authentication state. API Sessions
in this state will have reduced access to their target API. The data structure for Authentication Queries is defined
in the Client and Management Open API 2.0 specifications under the label
Associated Data & Removal
API Sessions, may be used to create ephemeral certificates called API Session Certificates and sessions for service access. Additionally, API Sessions are used to scope Posture Data. When an API Session is removed for any reason, all associated data is also removed. As an example, when removing an API Session used to create a Session the Session will also be removed. Removing a Session will also terminate any existing connections that used the security token associated with that Session and prevent it from being used to establish new connections.
Removal of an API Session occurs in the following scenarios:
- administrative removal
- client removal (logout)
The controller maintains a last accessed at timestamp for every API Session. This timestamp is used to determine whether the session timeout has been reached, signaling an API Session removal. Activities that update the timestamp include:
- Any maintained Edge Router connection
- Any valid Client or Management API interaction
The API Session timeout defaults to 30 minutes and can be configured in
edge.api.sessionTimeout in the controller
# sessionTimeout - optional, default 30m
# The number of minutes before an Edge API session will time out. Timeouts are reset by
# API requests and connections that are maintained to Edge Routers
Through the Edge Management API any API Session may be forcefully removed
DELETE /edge/management/v1/api-sessions<id> with an empty body.
Client Removal (Logout)
A client may terminate its own API Session at any time by calling:
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
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.
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:
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
id property on Identities. This mapping of JWT claim to
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.
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 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.
Similar to JWT primary authentication, a valid JWT must be present in the
Authentication header in the format of
bearer <JWT> on every request.
Example UPDB Authentication Request
Example Client Certificate Request
Note: The TLS connection to the controller MUST use a valid client certificate
Example JWT Authentication Request
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cC...
Example TOTP Authentication Query Response