edge_apis

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 13, 2025 License: Apache-2.0 Imports: 48 Imported by: 11

Documentation

Index

Constants

View Source 
const (
	AuthRequestIdHeader = "auth-request-id"
	TotpRequiredHeader  = "totp-required"
)
View Source 
const (
	ClientApiPath     = "/edge/client/v1"
	ManagementApiPath = "/edge/management/v1"
)
View Source 
const DefaultOidcRedirectUri = "http://localhost:8080/auth/callback"

DefaultOidcRedirectUri is the default redirect URI for the OIDC PKCE flow that satisfies the default OIDC redirects for the Ziti Edge OIDC API. It is not an actual server, rather an intercepted redirect URI that is used to extract the resulting OIDC tokens.

View Source 
const JwtTokenPrefix = "ey"

JwtTokenPrefix is the standard prefix for JWT tokens, representing the first two characters of a Base64URL-encoded JWT header. This prefix is used to identify JWT-format tokens.

Variables

This section is empty.

Functions

func ClientUrl added in v0.20.66 

func ClientUrl(hostname string) string

ClientUrl returns a URL with the given hostname in the format of `https://<hostname>/edge/management/v1`. The hostname provided may include a port.

func ManagementUrl added in v0.20.66 

func ManagementUrl(hostname string) string

ManagementUrl returns a URL with the given hostname in the format of `https://<hostname>/edge/management/v1`. The hostname provided may include a port.

func NewHttpClient added in v1.3.0 

func NewHttpClient(tlsAwareHttpTransport TlsAwareTransport) *http.Client

NewHttpClient creates an HTTP client with the given transport.

func NewRuntime added in v0.23.23 

func NewRuntime(apiUrl *url.URL, schemes []string, httpClient *http.Client) *openapiclient.Runtime

NewRuntime creates an OpenAPI runtime for communicating with a controller endpoint. Used for HA failover to add multiple controller endpoints.

func Randomize added in v1.2.9 

func Randomize[T any](s []T)

func RedirectUntilUrlPrefix added in v1.3.0 

func RedirectUntilUrlPrefix(urlPrefixToStopAt ...string) resty.RedirectPolicy

RedirectUntilUrlPrefix returns a redirect policy that follows redirects until the request URL matches one of the provided URL prefixes. Once a matching prefix is encountered, the redirect is not followed, allowing the caller to inspect the redirect response.

Types

type ApiAccessClaims added in v0.23.0 

type ApiAccessClaims struct {
	jwt.RegisteredClaims
	ApiSessionId     string   `json:"z_asid,omitempty"`
	ExternalId       string   `json:"z_eid,omitempty"`
	IsAdmin          bool     `json:"z_ia,omitempty"`
	ConfigTypes      []string `json:"z_ct,omitempty"`
	ApplicationId    string   `json:"z_aid,omitempty"`
	Type             string   `json:"z_t"`
	CertFingerprints []string `json:"z_cfs"`
	Scopes           []string `json:"scopes,omitempty"`
}

ApiAccessClaims represents the JWT claims for API session access tokens, including identity attributes, administrative status, and configuration bindings.

type ApiClientConfig added in v0.24.0 

type ApiClientConfig struct {
	ApiUrls          []*url.URL
	CaPool           *x509.CertPool
	TotpCodeProvider TotpCodeProvider
	Components       *Components
	Proxy            func(r *http.Request) (*url.URL, error)
}

ApiClientConfig contains configuration options for creating API clients.

type ApiClientTransport added in v0.23.23 

type ApiClientTransport struct {
	runtime.ClientTransport
	ApiUrl *url.URL
}

ApiClientTransport wraps a runtime.ClientTransport with its associated API URL, enabling tracking of which controller endpoint a transport communicates with.

type ApiSession added in v0.22.6 

type ApiSession interface {
	//GetAccessHeader returns the HTTP header name and value that should be used to represent this ApiSession
	GetAccessHeader() (string, string)

	//AuthenticateRequest fulfills the interface defined by the OpenAPI libraries to authenticate client HTTP requests
	AuthenticateRequest(request runtime.ClientRequest, _ strfmt.Registry) error

	//GetToken returns the ApiSessions' token bytes
	GetToken() []byte

	//GetExpiresAt returns the time when the ApiSession will expire.
	GetExpiresAt() *time.Time

	//GetAuthQueries returns a list of authentication queries the ApiSession is subjected to
	GetAuthQueries() rest_model.AuthQueryList

	//GetIdentityName returns the name of the authenticating identity
	GetIdentityName() string

	//GetIdentityId returns the id of the authenticating identity
	GetIdentityId() string

	//GetId returns the id of the ApiSession
	GetId() string

	//RequiresRouterTokenUpdate returns true if the token is a bearer token requires updating on edge router connections.
	RequiresRouterTokenUpdate() bool

	GetRequestHeaders() http.Header

	// GetType returns the authentication method used to establish this session, enabling
	// callers to determine whether legacy or OIDC-based authentication is in use.
	GetType() ApiSessionType

	json.Marshaler
	json.Unmarshaler
}

func UnmarshalApiSession added in v1.3.0 

func UnmarshalApiSession(data []byte) (ApiSession, error)

type ApiSessionJson added in v1.3.0 

type ApiSessionJson struct {
	Type             string `json:"type"`
	ZtSessionToken   string `json:"ztSessionToken,omitempty"`
	OidcAccessToken  string `json:"oidcAccessToken,omitempty"`
	OidcRefreshToken string `json:"oidcRefreshToken,omitempty"`
}

type ApiSessionJsonWrapper added in v1.3.0 

type ApiSessionJsonWrapper struct {
	ApiSession ApiSession
}

ApiSessionJsonWrapper provides JSON marshaling and unmarshaling capabilities for ApiSession interface types. It allows polymorphic ApiSession implementations (ApiSessionLegacy and ApiSessionOidc) to be correctly serialized and deserialized by delegating to the underlying ApiSession's JSON methods.

This wrapper enables ApiSession instances to be embedded in structs and marshaled to/from JSON.

func (*ApiSessionJsonWrapper) MarshalJSON added in v1.3.0 

func (a *ApiSessionJsonWrapper) MarshalJSON() ([]byte, error)

func (*ApiSessionJsonWrapper) UnmarshalJSON added in v1.3.0 

func (a *ApiSessionJsonWrapper) UnmarshalJSON(bytes []byte) error

type ApiSessionLegacy added in v0.23.0 

type ApiSessionLegacy struct {
	Detail         *rest_model.CurrentAPISessionDetail
	RequestHeaders http.Header
}

ApiSessionLegacy represents OpenZiti's original authentication API Session Detail, supplied in the `zt-session` header. It has been supplanted by OIDC authentication represented by ApiSessionOidc.

func NewApiSessionLegacy added in v1.3.0 

func NewApiSessionLegacy(token string) *ApiSessionLegacy

func (*ApiSessionLegacy) AuthenticateRequest added in v0.23.0 

func (a *ApiSessionLegacy) AuthenticateRequest(request runtime.ClientRequest, _ strfmt.Registry) error

func (*ApiSessionLegacy) GetAccessHeader added in v0.23.0 

func (a *ApiSessionLegacy) GetAccessHeader() (string, string)

GetAccessHeader returns the header and header token value should be used for authentication requests

func (*ApiSessionLegacy) GetAuthQueries added in v0.23.0 

func (a *ApiSessionLegacy) GetAuthQueries() rest_model.AuthQueryList

func (*ApiSessionLegacy) GetExpiresAt added in v0.23.0 

func (a *ApiSessionLegacy) GetExpiresAt() *time.Time

func (*ApiSessionLegacy) GetId added in v0.23.0 

func (a *ApiSessionLegacy) GetId() string

func (*ApiSessionLegacy) GetIdentityId added in v0.23.0 

func (a *ApiSessionLegacy) GetIdentityId() string

func (*ApiSessionLegacy) GetIdentityName added in v0.23.0 

func (a *ApiSessionLegacy) GetIdentityName() string

func (*ApiSessionLegacy) GetRequestHeaders added in v0.23.40 

func (a *ApiSessionLegacy) GetRequestHeaders() http.Header

func (*ApiSessionLegacy) GetToken added in v0.23.0 

func (a *ApiSessionLegacy) GetToken() []byte

func (*ApiSessionLegacy) GetType added in v1.2.9 

func (a *ApiSessionLegacy) GetType() ApiSessionType

func (*ApiSessionLegacy) MarshalJSON added in v1.3.0 

func (a *ApiSessionLegacy) MarshalJSON() ([]byte, error)

func (*ApiSessionLegacy) NewApiSessionLegacy added in v1.3.0 

func (a *ApiSessionLegacy) NewApiSessionLegacy(token string) *ApiSessionLegacy

func (*ApiSessionLegacy) RequiresRouterTokenUpdate added in v0.23.28 

func (a *ApiSessionLegacy) RequiresRouterTokenUpdate() bool

func (*ApiSessionLegacy) UnmarshalJSON added in v1.3.0 

func (a *ApiSessionLegacy) UnmarshalJSON(bytes []byte) error

type ApiSessionOidc added in v0.23.0 

type ApiSessionOidc struct {
	OidcTokens     *oidc.Tokens[*oidc.IDTokenClaims]
	RequestHeaders http.Header
}

ApiSessionOidc represents an authenticated session backed by OIDC tokens.

func NewApiSessionOidc added in v1.3.0 

func NewApiSessionOidc(accessToken, refreshToken string) *ApiSessionOidc

func (*ApiSessionOidc) AuthenticateRequest added in v0.23.0 

func (a *ApiSessionOidc) AuthenticateRequest(request runtime.ClientRequest, _ strfmt.Registry) error

func (*ApiSessionOidc) GetAccessClaims added in v0.23.0 

func (a *ApiSessionOidc) GetAccessClaims() (*ApiAccessClaims, error)

func (*ApiSessionOidc) GetAccessHeader added in v0.23.0 

func (a *ApiSessionOidc) GetAccessHeader() (string, string)

GetAccessHeader returns the header and header token value should be used for authentication requests

func (*ApiSessionOidc) GetAuthQueries added in v0.23.0 

func (a *ApiSessionOidc) GetAuthQueries() rest_model.AuthQueryList

func (*ApiSessionOidc) GetExpiresAt added in v0.23.0 

func (a *ApiSessionOidc) GetExpiresAt() *time.Time

func (*ApiSessionOidc) GetId added in v0.23.0 

func (a *ApiSessionOidc) GetId() string

func (*ApiSessionOidc) GetIdentityId added in v0.23.0 

func (a *ApiSessionOidc) GetIdentityId() string

func (*ApiSessionOidc) GetIdentityName added in v0.23.0 

func (a *ApiSessionOidc) GetIdentityName() string

func (*ApiSessionOidc) GetRequestHeaders added in v0.23.40 

func (a *ApiSessionOidc) GetRequestHeaders() http.Header

func (*ApiSessionOidc) GetToken added in v0.23.0 

func (a *ApiSessionOidc) GetToken() []byte

func (*ApiSessionOidc) GetType added in v1.2.9 

func (a *ApiSessionOidc) GetType() ApiSessionType

func (*ApiSessionOidc) MarshalJSON added in v1.3.0 

func (a *ApiSessionOidc) MarshalJSON() ([]byte, error)

func (*ApiSessionOidc) RequiresRouterTokenUpdate added in v0.23.28 

func (a *ApiSessionOidc) RequiresRouterTokenUpdate() bool

func (*ApiSessionOidc) UnmarshalJSON added in v1.3.0 

func (a *ApiSessionOidc) UnmarshalJSON(bytes []byte) error

type ApiSessionType added in v1.2.9 

type ApiSessionType string

ApiSessionType identifies the authentication mechanism used to establish an API session. 

const (
	// ApiSessionTypeLegacy indicates a session created using the original Ziti authentication
	// with session tokens passed in the zt-session header.
	ApiSessionTypeLegacy ApiSessionType = "legacy"

	// ApiSessionTypeOidc indicates a session created using OpenID Connect authentication
	// with JWT bearer tokens.
	ApiSessionTypeOidc ApiSessionType = "oidc"
)

type ApiType 

type ApiType interface {
	ZitiEdgeManagement | ZitiEdgeClient
}

ApiType is an interface constraint for generics. The underlying go-swagger types only have fields, which are insufficient to attempt to make a generic type from. Instead, this constraint is used that points at the aliased types.

type AuthEnabledApi 

type AuthEnabledApi interface {
	// Authenticate authenticates using the provided credentials and returns an ApiSession for subsequent authenticated requests.
	Authenticate(credentials Credentials, configTypes []string, httpClient *http.Client) (ApiSession, error)
	// SetUseOidc forces OIDC mode (true) or legacy mode (false).
	SetUseOidc(bool)
	// ListControllers returns the list of available controllers for HA failover.
	ListControllers() (*rest_model.ControllersList, error)
	// GetClientTransportPool returns the transport pool managing multiple controller endpoints.
	GetClientTransportPool() ClientTransportPool
	// SetClientTransportPool sets the transport pool.
	SetClientTransportPool(ClientTransportPool)
	// RefreshApiSession refreshes an existing session.
	RefreshApiSession(apiSession ApiSession, httpClient *http.Client) (ApiSession, error)
}

AuthEnabledApi is a sentinel interface that detects APIs supporting authentication. It provides methods for authenticating, managing sessions, and discovering controllers for high-availability.

type AuthMethod added in v1.3.0 

type AuthMethod string
const (
	AuthMethodCert   AuthMethod = "cert"
	AuthMethodUpdb   AuthMethod = "password"
	AuthMethodEmpty  AuthMethod = "empty"
	AuthMethodJwtExt AuthMethod = "ext-jwt"
)

type BaseClient 

type BaseClient[A ApiType] struct {
	API            *A
	AuthEnabledApi AuthEnabledApi
	Components
	AuthInfoWriter runtime.ClientAuthInfoWriter
	ApiSession     atomic.Pointer[ApiSession]
	Credentials    Credentials
	ApiUrls        []*url.URL
	ApiBinding     string
	ApiVersion     string
	Schemes        []string
	// contains filtered or unexported fields
}

BaseClient provides shared authentication and session management for OpenZiti API clients. It handles credential-based authentication, TLS configuration, session storage, and controller failover.

func (*BaseClient[A]) AddOnControllerUpdateListeners added in v0.23.23 

func (self *BaseClient[A]) AddOnControllerUpdateListeners(listener func([]*url.URL))

AddOnControllerUpdateListeners registers a callback that is invoked when the list of available controller endpoints changes.

func (*BaseClient[A]) Authenticate 

func (self *BaseClient[A]) Authenticate(credentials Credentials, configTypesOverride []string) (ApiSession, error)

Authenticate authenticates using provided credentials, updating the TLS configuration based on the credential's CA pool. On success, stores the session and processes controller endpoints for HA failover. On failure, clears the session and credentials.

func (*BaseClient[A]) AuthenticateRequest 

func (self *BaseClient[A]) AuthenticateRequest(request runtime.ClientRequest, registry strfmt.Registry) error

AuthenticateRequest authenticates outgoing API requests using the current session or credentials. It implements the openapi runtime.ClientAuthInfoWriter interface.

func (*BaseClient[A]) AuthenticateWithPreviousSession added in v1.3.0 

func (self *BaseClient[A]) AuthenticateWithPreviousSession(credentials Credentials, prevApiSession ApiSession) (ApiSession, error)

func (*BaseClient[A]) GetCurrentApiSession 

func (self *BaseClient[A]) GetCurrentApiSession() ApiSession

GetCurrentApiSession returns the ApiSession that is being used to authenticate requests.

func (*BaseClient[A]) ProcessControllers added in v0.23.23 

func (self *BaseClient[A]) ProcessControllers(authEnabledApi AuthEnabledApi)

ProcessControllers discovers peer controllers and registers them for HA failover. Called after successful authentication.

func (*BaseClient[A]) SetAllowOidcDynamicallyEnabled added in v0.23.10 

func (self *BaseClient[A]) SetAllowOidcDynamicallyEnabled(allow bool)

SetAllowOidcDynamicallyEnabled configures whether the client checks the controller for OIDC support and switches modes accordingly.

func (*BaseClient[A]) SetOidcRedirectUri added in v1.3.0 

func (self *BaseClient[A]) SetOidcRedirectUri(redirectUri string)

func (*BaseClient[A]) SetUseOidc added in v0.23.2 

func (self *BaseClient[A]) SetUseOidc(use bool)

SetUseOidc forces the API client to operate in OIDC mode when true, or legacy mode when false.

func (*BaseClient[A]) Url added in v0.23.23 

func (self *BaseClient[A]) Url() url.URL

Url returns the URL of the currently active controller endpoint.

type BaseCredentials 

type BaseCredentials struct {
	// ConfigTypes is used to set the configuration types for services during authentication
	ConfigTypes []string

	// AuthHeaders is a map of strings to string arrays of headers to send with auth requests.
	AuthHeaders http.Header

	// RequestHeaders is a map of string to string arrays of headers to send on non-authentication requests.
	RequestHeaders http.Header

	// EnvInfo is provided during authentication to set environmental information about the client.
	EnvInfo *rest_model.EnvInfo

	// SdkInfo is provided during authentication to set SDK information about the client.
	SdkInfo *rest_model.SdkInfo

	// CaPool will override the client's default certificate pool if set to a non-nil value.
	CaPool *x509.CertPool
}

BaseCredentials is a shared struct of information all Credentials implementations require.

func (*BaseCredentials) AddAuthHeader added in v0.23.40 

func (c *BaseCredentials) AddAuthHeader(key, value string)

AddAuthHeader provides a base implementation to add a header to authentication requests.

func (*BaseCredentials) AddJWT added in v0.20.50 

func (c *BaseCredentials) AddJWT(token string)

AddJWT adds additional JWTs to the credentials. Used to satisfy secondary authentication/MFA requirements. The provided token should be the base64 encoded version of the token. Convenience function for AddHeader.

func (*BaseCredentials) AddRequestHeader added in v0.23.40 

func (c *BaseCredentials) AddRequestHeader(key, value string)

AddRequestHeader provides a base implementation to add a header to all requests after authentication.

func (*BaseCredentials) AuthenticateRequest 

func (c *BaseCredentials) AuthenticateRequest(request runtime.ClientRequest, _ strfmt.Registry) error

AuthenticateRequest provides a base implementation to authenticate an outgoing request. This is provided here for authentication methods such as `cert` which do not have to provide any more request level information.

func (*BaseCredentials) GetCaPool 

func (c *BaseCredentials) GetCaPool() *x509.CertPool

GetCaPool provides a base implementation to return the certificate pool of a Credentials instance.

func (*BaseCredentials) GetRequestHeaders added in v0.23.40 

func (c *BaseCredentials) GetRequestHeaders() http.Header

GetRequestHeaders returns headers that should be sent on requests post authentication.

func (*BaseCredentials) Payload 

func (c *BaseCredentials) Payload() *rest_model.Authenticate

Payload will produce the object used to construct the body of an authentication requests. The base version sets shared information available in BaseCredentials.

func (*BaseCredentials) ProcessRequest added in v0.23.40 

func (c *BaseCredentials) ProcessRequest(request runtime.ClientRequest, _ strfmt.Registry) error

ProcessRequest proves a base implemmentation mutate runtime.ClientRequests as they are sent out after authentication. Useful for adding headers.

func (*BaseCredentials) TlsCerts 

func (c *BaseCredentials) TlsCerts() []tls.Certificate

TlsCerts provides a base implementation of returning the tls.Certificate array that will be used to setup mTLS connections. This is provided here for authentication methods that do not initially require mTLS (e.g. JWTs).

type CertCredentials 

type CertCredentials struct {
	BaseCredentials
	Certs []*x509.Certificate
	Key   crypto.PrivateKey
}

CertCredentials represents authentication using certificates that are not from an Identity configuration file.

func NewCertCredentials 

func NewCertCredentials(certs []*x509.Certificate, key crypto.PrivateKey) *CertCredentials

NewCertCredentials creates Credentials instance based upon an array of certificates. At least one certificate must be provided and the certificate at index zero is assumed to be the leaf client certificate that pairs with the provided private key. All other certificates are assumed to support the leaf client certificate as a chain.

func (*CertCredentials) GetIdentity 

func (c *CertCredentials) GetIdentity() identity.Identity

func (*CertCredentials) Method 

func (c *CertCredentials) Method() AuthMethod

func (*CertCredentials) TlsCerts 

func (c *CertCredentials) TlsCerts() []tls.Certificate

type ClientApiClient 

type ClientApiClient struct {
	BaseClient[ZitiEdgeClient]
}

ClientApiClient provides access to the Ziti Edge Client API for identity operations.

func NewClientApiClient 

func NewClientApiClient(apiUrls []*url.URL, caPool *x509.CertPool, totpCallback func(chan string)) *ClientApiClient

NewClientApiClient will assemble a ClientApiClient. The apiUrl should be the full URL to the Edge Client API (e.g. `https://example.com/edge/client/v1`).

The `caPool` argument should be a list of trusted root CAs. If provided as `nil` here unauthenticated requests will use the system certificate pool. If authentication occurs, and a certificate pool is set on the Credentials the certificate pool from the Credentials will be used from that point forward. Credentials implementations based on an identity.Identity are likely to provide a certificate pool.

For OpenZiti instances not using publicly signed certificates, `ziti.GetControllerWellKnownCaPool()` can be used to obtain and verify the target controllers CAs. Tools should allow users to verify and accept new controllers that have not been verified from an outside secret (such as an enrollment token).

func NewClientApiClientWithConfig added in v0.24.0 

func NewClientApiClientWithConfig(config *ApiClientConfig) *ClientApiClient

NewClientApiClientWithConfig creates a Client API client using the provided configuration.

type ClientTransportPool added in v0.23.23 

type ClientTransportPool interface {
	runtime.ClientTransport

	// Add registers a new transport for the specified API URL.
	Add(apiUrl *url.URL, transport runtime.ClientTransport)

	// Remove unregisters the transport for the specified API URL.
	Remove(apiUrl *url.URL)

	// GetActiveTransport returns the currently selected transport.
	GetActiveTransport() *ApiClientTransport

	// SetActiveTransport designates which transport to use for subsequent operations.
	SetActiveTransport(*ApiClientTransport)

	// GetApiUrls returns all registered API URLs.
	GetApiUrls() []*url.URL

	// IterateTransportsRandomly provides a channel for iterating through available transports
	// in random order.
	IterateTransportsRandomly() chan<- *ApiClientTransport

	// TryTransportsForOp attempts to execute an operation, trying different transports
	// on connection failures.
	TryTransportsForOp(operation *runtime.ClientOperation) (any, error)

	// TryTransportForF executes a callback function, trying different transports
	// on connection failures.
	TryTransportForF(cb func(*ApiClientTransport) (any, error)) (any, error)
}

ClientTransportPool manages multiple runtime.ClientTransport instances representing different controller endpoints in a high-availability OpenZiti network. It provides automatic failover capabilities when individual controllers become unavailable.

type ClientTransportPoolRandom added in v0.23.23 

type ClientTransportPoolRandom struct {
	// contains filtered or unexported fields
}

ClientTransportPoolRandom implements a randomized failover strategy for controller selection. It maintains an active transport and switches to randomly selected alternatives when the active transport becomes unreachable.

func NewClientTransportPoolRandom added in v0.23.23 

func NewClientTransportPoolRandom() *ClientTransportPoolRandom

NewClientTransportPoolRandom creates a new transport pool with randomized failover.

func (*ClientTransportPoolRandom) Add added in v0.23.23 

func (c *ClientTransportPoolRandom) Add(apiUrl *url.URL, transport runtime.ClientTransport)

func (*ClientTransportPoolRandom) AnyTransport added in v0.23.23 

func (c *ClientTransportPoolRandom) AnyTransport() *ApiClientTransport

AnyTransport returns a randomly selected transport from the pool, or nil if empty.

func (*ClientTransportPoolRandom) GetActiveTransport added in v0.23.23 

func (c *ClientTransportPoolRandom) GetActiveTransport() *ApiClientTransport

func (*ClientTransportPoolRandom) GetApiClientTransports added in v0.23.23 

func (c *ClientTransportPoolRandom) GetApiClientTransports() []*ApiClientTransport

GetApiClientTransports returns a snapshot of all registered transports.

func (*ClientTransportPoolRandom) GetApiUrls added in v0.23.23 

func (c *ClientTransportPoolRandom) GetApiUrls() []*url.URL

func (*ClientTransportPoolRandom) IterateRandomTransport added in v0.23.23 

func (c *ClientTransportPoolRandom) IterateRandomTransport() []*ApiClientTransport

func (*ClientTransportPoolRandom) IterateTransportsRandomly added in v0.23.23 

func (c *ClientTransportPoolRandom) IterateTransportsRandomly() chan<- *ApiClientTransport

func (*ClientTransportPoolRandom) Remove added in v0.23.23 

func (c *ClientTransportPoolRandom) Remove(apiUrl *url.URL)

func (*ClientTransportPoolRandom) SetActiveTransport added in v0.23.23 

func (c *ClientTransportPoolRandom) SetActiveTransport(transport *ApiClientTransport)

func (*ClientTransportPoolRandom) Submit added in v0.23.23 

func (c *ClientTransportPoolRandom) Submit(operation *runtime.ClientOperation) (any, error)

func (*ClientTransportPoolRandom) TryTransportForF added in v0.23.23 

func (c *ClientTransportPoolRandom) TryTransportForF(cb func(*ApiClientTransport) (any, error)) (any, error)

func (*ClientTransportPoolRandom) TryTransportsForOp added in v0.23.23 

func (c *ClientTransportPoolRandom) TryTransportsForOp(operation *runtime.ClientOperation) (any, error)

type Components 

type Components struct {
	HttpClient        *http.Client
	TlsAwareTransport TlsAwareTransport
	CaPool            *x509.CertPool
}

Components provides the foundational HTTP client infrastructure for OpenAPI clients, bundling the HTTP client, transport, and certificate pool as a cohesive unit.

func NewComponentsWithConfig added in v0.24.0 

func NewComponentsWithConfig(cfg *ComponentsConfig) *Components

NewComponentsWithConfig assembles a new set of components using the provided configuration.

type ComponentsConfig added in v0.24.0 

type ComponentsConfig struct {
	Proxy func(*http.Request) (*url.URL, error)
}

ComponentsConfig contains configuration options for creating Components.

type Credentials 

type Credentials interface {
	// Payload constructs the objects that represent the JSON authentication payload for this set of credentials.
	Payload() *rest_model.Authenticate

	// TlsCerts returns zero or more tls.Certificates used for client authentication.
	TlsCerts() []tls.Certificate

	// GetCaPool returns the CA pool that this credential was configured to trust.
	GetCaPool() *x509.CertPool

	// Method returns the authentication necessary to complete an authentication request.
	Method() AuthMethod

	// AddAuthHeader adds a header for all authentication requests.
	AddAuthHeader(key, value string)

	// AddRequestHeader adds a header for all requests after authentication
	AddRequestHeader(key, value string)

	// AddJWT adds additional JWTs to the credentials. Used to satisfy secondary authentication/MFA requirements. The
	// provided token should be the base64 encoded version of the token.
	AddJWT(string)

	// ClientAuthInfoWriter is used to pass a Credentials instance to the openapi runtime to authenticate outgoing
	//requests.
	runtime.ClientAuthInfoWriter

	// GetRequestHeaders returns a set of headers to use after authentication during normal HTTP operations
	GetRequestHeaders() http.Header
}

Credentials represents the minimal information needed across all authentication mechanisms to authenticate an identity to an OpenZiti network.

type EdgeOidcAuthConfig added in v1.3.0 

type EdgeOidcAuthConfig struct {
	ClientTransportPool ClientTransportPool
	Credentials         Credentials
	ConfigTypeOverrides []string
	HttpClient          *http.Client
	TotpCodeProvider    TotpCodeProvider
	RedirectUri         string
	ApiHost             string
}

EdgeOidcAuthConfig represents the options necessary to complete an OAuth 2.0 PKCE authentication flow against an OpenZiti controller.

type EdgeOidcAuthenticator added in v1.3.0 

type EdgeOidcAuthenticator struct {
	*EdgeOidcAuthConfig
	// contains filtered or unexported fields
}

EdgeOidcAuthenticator handles the OAuth 2.0 PKCE authentication flow for the Ziti Edge API. It submits user credentials to the authorization endpoint, handles optional TOTP verification, and exchanges the authorization code for OIDC tokens. The HTTP client follows redirects during the authorization flow and extracts the authorization code from the final redirect.

func NewEdgeOidcAuthenticator added in v1.3.0 

func NewEdgeOidcAuthenticator(config *EdgeOidcAuthConfig) *EdgeOidcAuthenticator

NewEdgeOidcAuthenticator creates a new EdgeOidcAuthenticator configured for PKCE authentication. It sets up an HTTP client with a custom redirect policy that follows redirects during the authorization flow but stops when the callback redirect URI is reached, allowing code extraction from the redirect URL. The redirectUri parameter defines where the authorization server will redirect with the authorization code in the query parameters.

func (*EdgeOidcAuthenticator) Authenticate added in v1.3.0 

func (e *EdgeOidcAuthenticator) Authenticate() (*oidc.Tokens[*oidc.IDTokenClaims], error)

Authenticate performs the complete OAuth 2.0 PKCE authentication flow. It initiates authorization with PKCE parameters, submits credentials and handles optional TOTP verification, then exchanges the resulting authorization code for OIDC tokens.

func (*EdgeOidcAuthenticator) SetRedirectUri added in v1.3.0 

func (e *EdgeOidcAuthenticator) SetRedirectUri(redirectUri string)

SetRedirectUri sets the redirect URI for the authorization server. The default value is included in the default Edge OIDC controller configuration, but if it has been set to custom values, this function can be used to reflect that configuration.

type EmptyCredentials added in v1.3.0 

type EmptyCredentials struct {
	BaseCredentials
}

func (EmptyCredentials) Method added in v1.3.0 

func (e EmptyCredentials) Method() AuthMethod

type IdClaims added in v0.23.28 

type IdClaims struct {
	oidc.IDTokenClaims
}

IdClaims wraps oidc.IDToken claims to fulfill the jwt.Claims interface

func (*IdClaims) GetAudience added in v0.23.28 

func (r *IdClaims) GetAudience() (jwt.ClaimStrings, error)

func (*IdClaims) GetExpirationTime added in v0.23.28 

func (r *IdClaims) GetExpirationTime() (*jwt.NumericDate, error)

func (*IdClaims) GetIssuedAt added in v0.23.28 

func (r *IdClaims) GetIssuedAt() (*jwt.NumericDate, error)

func (*IdClaims) GetIssuer added in v0.23.28 

func (r *IdClaims) GetIssuer() (string, error)

func (*IdClaims) GetNotBefore added in v0.23.28 

func (r *IdClaims) GetNotBefore() (*jwt.NumericDate, error)

func (*IdClaims) GetSubject added in v0.23.28 

func (r *IdClaims) GetSubject() (string, error)

type IdentityCredentials 

type IdentityCredentials struct {
	BaseCredentials
	Identity identity.Identity
}

func NewIdentityCredentials 

func NewIdentityCredentials(identity identity.Identity) *IdentityCredentials

NewIdentityCredentials creates a Credentials instance based upon and Identity.

func NewIdentityCredentialsFromConfig 

func NewIdentityCredentialsFromConfig(config identity.Config) *IdentityCredentials

NewIdentityCredentialsFromConfig creates a Credentials instance based upon and Identity configuration.

func (*IdentityCredentials) AuthenticateRequest added in v0.20.20 

func (c *IdentityCredentials) AuthenticateRequest(request runtime.ClientRequest, reg strfmt.Registry) error

func (*IdentityCredentials) GetCaPool 

func (c *IdentityCredentials) GetCaPool() *x509.CertPool

func (*IdentityCredentials) GetIdentity 

func (c *IdentityCredentials) GetIdentity() identity.Identity

func (*IdentityCredentials) Method 

func (c *IdentityCredentials) Method() AuthMethod

func (*IdentityCredentials) TlsCerts 

func (c *IdentityCredentials) TlsCerts() []tls.Certificate

type IdentityProvider 

type IdentityProvider interface {
	GetIdentity() identity.Identity
}

IdentityProvider is a sentinel interface used to determine whether the backing Credentials instance can provide an Identity that can provide a certificate and private key used to initiate mTLS connections.

type JwtCredentials 

type JwtCredentials struct {
	BaseCredentials
	JWT                string
	SendOnEveryRequest bool
}

func NewJwtCredentials 

func NewJwtCredentials(jwt string) *JwtCredentials

NewJwtCredentials creates a Credentials instance based on a JWT obtained from an outside system.

func (*JwtCredentials) AuthenticateRequest 

func (c *JwtCredentials) AuthenticateRequest(request runtime.ClientRequest, reg strfmt.Registry) error

func (*JwtCredentials) Method 

func (c *JwtCredentials) Method() AuthMethod

type ManagementApiClient 

type ManagementApiClient struct {
	BaseClient[ZitiEdgeManagement]
}

ManagementApiClient provides the ability to authenticate and interact with the Edge Management API.

func NewManagementApiClient 

func NewManagementApiClient(apiUrls []*url.URL, caPool *x509.CertPool, totpCallback func(chan string)) *ManagementApiClient

NewManagementApiClient will assemble an ManagementApiClient. The apiUrl should be the full URL to the Edge Management API (e.g. `https://example.com/edge/management/v1`).

The `caPool` argument should be a list of trusted root CAs. If provided as `nil` here unauthenticated requests will use the system certificate pool. If authentication occurs, and a certificate pool is set on the Credentials the certificate pool from the Credentials will be used from that point forward. Credentials implementations based on an identity.Identity are likely to provide a certificate pool.

For OpenZiti instances not using publicly signed certificates, `ziti.GetControllerWellKnownCaPool()` can be used to obtain and verify the target controllers CAs. Tools should allow users to verify and accept new controllers that have not been verified from an outside secret (such as an enrollment token).

func NewManagementApiClientWithConfig added in v0.24.0 

func NewManagementApiClientWithConfig(config *ApiClientConfig) *ManagementApiClient

NewManagementApiClientWithConfig creates a Management API client using the provided configuration.

type OidcEnabledApi added in v0.23.2 

type OidcEnabledApi interface {
	// SetUseOidc forces an API Client to operate in OIDC mode (true) or legacy mode (false). The state of the controller
	// is ignored and dynamic enable/disable of OIDC support is suspended.
	SetUseOidc(use bool)

	// SetAllowOidcDynamicallyEnabled sets whether clients will check the controller for OIDC support or not. If supported
	// OIDC is favored over legacy authentication.
	SetAllowOidcDynamicallyEnabled(allow bool)

	// SetOidcRedirectUri sets the redirect URI for the OIDC PKCE flow. The default value is used if not set.
	// Should only be necessary to call for custom redirect controller configurations.
	SetOidcRedirectUri(redirectUri string)
}

type ServiceAccessClaims added in v0.22.6 

type ServiceAccessClaims struct {
	jwt.RegisteredClaims
	ApiSessionId string `json:"z_asid"`
	IdentityId   string `json:"z_iid"`
	TokenType    string `json:"z_t"`
	Type         string `json:"z_st"`
}

ServiceAccessClaims represents the JWT claims for service-level access tokens, including identity and session binding information specific to a service connection.

type SingularTokenRequestor added in v1.3.0 

type SingularTokenRequestor struct {
	// contains filtered or unexported fields
}

SingularTokenRequestor serializes TOTP token requests, ensuring only one is active at a time. This prevents duplicate authentication attempts when multiple operations require TOTP.

func NewSingularTokenRequestor added in v1.3.0 

func NewSingularTokenRequestor(codeProvider TotpCodeProvider, tokenRequestor TotpTokenRequestor) *SingularTokenRequestor

NewSingularTokenRequestor creates a token requestor that coordinates code collection and token exchange. Only one request can be active at a time; subsequent requests return nil if one is already in progress.

func (*SingularTokenRequestor) Request added in v1.3.0 

func (r *SingularTokenRequestor) Request() <-chan TotpTokenResult

Request initiates a TOTP token request, returning nil if a request is already in progress. The returned channel delivers the token result once the code is collected and exchanged.

type TlsAwareHttpTransport added in v1.3.0 

type TlsAwareHttpTransport struct {
	*http.Transport
}

TlsAwareHttpTransport is a concrete implementation of TlsAwareTransport that wraps http.Transport.

func NewTlsAwareHttpTransport added in v1.3.0 

func NewTlsAwareHttpTransport(cfg *ComponentsConfig) *TlsAwareHttpTransport

NewTlsAwareHttpTransport creates a TlsAwareHttpTransport with default HTTP/2 and TLS settings.

func (*TlsAwareHttpTransport) GetProxy added in v1.3.0 

func (a *TlsAwareHttpTransport) GetProxy() func(*http.Request) (*url.URL, error)

GetProxy returns the proxy function currently set on the transport.

func (*TlsAwareHttpTransport) GetTlsClientConfig added in v1.3.0 

func (a *TlsAwareHttpTransport) GetTlsClientConfig() *tls.Config

GetTlsClientConfig returns the TLS configuration from the underlying transport.

func (*TlsAwareHttpTransport) SetProxy added in v1.3.0 

func (a *TlsAwareHttpTransport) SetProxy(proxyFunc func(*http.Request) (*url.URL, error))

SetProxy sets the proxy function for the transport.

func (*TlsAwareHttpTransport) SetTlsClientConfig added in v1.3.0 

func (a *TlsAwareHttpTransport) SetTlsClientConfig(config *tls.Config)

SetTlsClientConfig updates the TLS configuration on the underlying transport.

type TlsAwareTransport added in v1.3.0 

type TlsAwareTransport interface {
	http.RoundTripper

	// GetTlsClientConfig returns the current TLS configuration.
	GetTlsClientConfig() *tls.Config
	// SetTlsClientConfig updates the TLS configuration.
	SetTlsClientConfig(*tls.Config)

	// SetProxy sets the proxy function for HTTP requests.
	SetProxy(func(*http.Request) (*url.URL, error))
	// GetProxy returns the current proxy function.
	GetProxy() func(*http.Request) (*url.URL, error)

	// CloseIdleConnections closes all idle HTTP connections.
	CloseIdleConnections()
}

TlsAwareTransport abstracts HTTP transport to allow API implementations to dynamically configure TLS settings during authentication (e.g., adding client certificates) and manage proxy configuration.

type TotpCodeProvider added in v1.3.0 

type TotpCodeProvider interface {
	// GetTotpCode returns a channel that delivers the TOTP code result.
	GetTotpCode() <-chan TotpCodeResult
}

TotpCodeProvider supplies TOTP codes for multi-factor authentication. Implementations typically prompt users to enter codes from authenticator apps.

func NewTotpCodeProviderFromChStringFunc added in v1.3.0 

func NewTotpCodeProviderFromChStringFunc(stringFunc func(ch chan string)) TotpCodeProvider

NewTotpCodeProviderFromChStringFunc adapts legacy func(chan string) callbacks to the TotpCodeProvider interface. This enables backward compatibility while allowing a smoother migration path to the new interface.

type TotpCodeProviderFunc added in v1.3.0 

type TotpCodeProviderFunc func() <-chan TotpCodeResult

TotpCodeProviderFunc is a function adapter that implements TotpCodeProvider.

func (TotpCodeProviderFunc) GetTotpCode added in v1.3.0 

func (f TotpCodeProviderFunc) GetTotpCode() <-chan TotpCodeResult

type TotpCodeResult added in v1.3.0 

type TotpCodeResult struct {
	Code string
	Err  error
}

TotpCodeResult represents the outcome of requesting a TOTP code from a user or provider, containing either the code string or an error if the request failed.

type TotpTokenProvider added in v1.3.0 

type TotpTokenProvider interface {
	// Request initiates a TOTP token request, returning a channel with the result.
	Request() <-chan TotpTokenResult
}

TotpTokenProvider coordinates the complete TOTP authentication flow, obtaining codes and exchanging them for tokens.

type TotpTokenProviderFunc added in v1.3.0 

type TotpTokenProviderFunc func() <-chan TotpTokenResult

TotpTokenProviderFunc is a function adapter that implements TotpTokenProvider.

func (TotpTokenProviderFunc) Request added in v1.3.0 

func (f TotpTokenProviderFunc) Request() <-chan TotpTokenResult

Request implements TotpTokenProvider.

type TotpTokenRequestor added in v1.3.0 

type TotpTokenRequestor interface {
	// RequestTotpToken exchanges a TOTP code for a session token.
	RequestTotpToken(code string) <-chan TotpTokenResult
}

TotpTokenRequestor exchanges TOTP codes with the authentication service for session tokens.

type TotpTokenResult added in v1.3.0 

type TotpTokenResult struct {
	Token    string
	IssuedAt time.Time
	Err      error
}

TotpTokenResult represents the outcome of exchanging a TOTP code for a session token, including the token value, issuance timestamp, and any errors encountered.

type UpdbCredentials 

type UpdbCredentials struct {
	BaseCredentials
	Username string
	Password string
}

func NewUpdbCredentials 

func NewUpdbCredentials(username string, password string) *UpdbCredentials

NewUpdbCredentials creates a Credentials instance based on a username/passwords combination.

func (*UpdbCredentials) AuthenticateRequest added in v0.20.20 

func (c *UpdbCredentials) AuthenticateRequest(request runtime.ClientRequest, reg strfmt.Registry) error

func (*UpdbCredentials) Method 

func (c *UpdbCredentials) Method() AuthMethod

func (*UpdbCredentials) Payload 

func (c *UpdbCredentials) Payload() *rest_model.Authenticate

type ZitiEdgeClient 

type ZitiEdgeClient struct {
	*rest_client_api_client.ZitiEdgeClient

	TotpCodeProvider    TotpCodeProvider
	ClientTransportPool ClientTransportPool
	OidcRedirectUri     string
	// contains filtered or unexported fields
}

ZitiEdgeClient is an alias of the go-swagger generated client that allows this package to add additional functionality to the alias type to implement the AuthEnabledApi interface.

func (*ZitiEdgeClient) Authenticate 

func (self *ZitiEdgeClient) Authenticate(credentials Credentials, configTypesOverrides []string, httpClient *http.Client) (ApiSession, error)

func (*ZitiEdgeClient) ControllerSupportsHa added in v1.3.0 

func (self *ZitiEdgeClient) ControllerSupportsHa() bool

ControllerSupportsHa checks if the controller supports high-availability by inspecting its capabilities.

func (*ZitiEdgeClient) ControllerSupportsOidc added in v1.3.0 

func (self *ZitiEdgeClient) ControllerSupportsOidc() bool

ControllerSupportsOidc checks if the controller supports OIDC authentication by inspecting its capabilities.

func (*ZitiEdgeClient) ExchangeTokens added in v0.22.6 

func (self *ZitiEdgeClient) ExchangeTokens(curTokens *oidc.Tokens[*oidc.IDTokenClaims], httpClient *http.Client) (*oidc.Tokens[*oidc.IDTokenClaims], error)

ExchangeTokens exchanges OIDC tokens for refreshed tokens.

func (*ZitiEdgeClient) GetClientTransportPool added in v0.23.23 

func (self *ZitiEdgeClient) GetClientTransportPool() ClientTransportPool

GetClientTransportPool returns the transport pool managing multiple controller endpoints for failover.

func (*ZitiEdgeClient) ListControllers added in v0.23.23 

func (self *ZitiEdgeClient) ListControllers() (*rest_model.ControllersList, error)

ListControllers returns the list of available controllers for high-availability failover.

func (*ZitiEdgeClient) RefreshApiSession added in v0.22.6 

func (self *ZitiEdgeClient) RefreshApiSession(apiSession ApiSession, httpClient *http.Client) (ApiSession, error)

RefreshApiSession refreshes an existing API session (both legacy and OIDC types).

func (*ZitiEdgeClient) SetAllowOidcDynamicallyEnabled added in v0.23.10 

func (self *ZitiEdgeClient) SetAllowOidcDynamicallyEnabled(allow bool)

SetAllowOidcDynamicallyEnabled enables automatic OIDC capability detection on the controller.

func (*ZitiEdgeClient) SetClientTransportPool added in v0.23.23 

func (self *ZitiEdgeClient) SetClientTransportPool(transportPool ClientTransportPool)

SetClientTransportPool sets the transport pool.

func (*ZitiEdgeClient) SetOidcRedirectUri added in v1.3.0 

func (self *ZitiEdgeClient) SetOidcRedirectUri(redirectUri string)

func (*ZitiEdgeClient) SetUseOidc added in v0.22.6 

func (self *ZitiEdgeClient) SetUseOidc(use bool)

SetUseOidc forces OIDC mode (true) or legacy mode (false), overriding automatic detection.

type ZitiEdgeManagement 

type ZitiEdgeManagement struct {
	*rest_management_api_client.ZitiEdgeManagement

	TotpCodeProvider    TotpCodeProvider
	ClientTransportPool ClientTransportPool
	OidcRedirectUri     string
	// contains filtered or unexported fields
}

ZitiEdgeManagement is an alias of the go-swagger generated client that allows this package to add additional functionality to the alias type to implement the AuthEnabledApi interface.

func (*ZitiEdgeManagement) Authenticate 

func (self *ZitiEdgeManagement) Authenticate(credentials Credentials, configTypes []string, httpClient *http.Client) (ApiSession, error)

func (*ZitiEdgeManagement) ControllerSupportsHa added in v1.3.0 

func (self *ZitiEdgeManagement) ControllerSupportsHa() bool

ControllerSupportsHa checks if the controller supports high-availability by inspecting its capabilities.

func (*ZitiEdgeManagement) ControllerSupportsOidc added in v1.3.0 

func (self *ZitiEdgeManagement) ControllerSupportsOidc() bool

ControllerSupportsOidc checks if the controller supports OIDC authentication by inspecting its capabilities.

func (*ZitiEdgeManagement) ExchangeTokens added in v0.22.6 

func (self *ZitiEdgeManagement) ExchangeTokens(curTokens *oidc.Tokens[*oidc.IDTokenClaims], httpClient *http.Client) (*oidc.Tokens[*oidc.IDTokenClaims], error)

ExchangeTokens exchanges OIDC tokens for refreshed tokens.

func (*ZitiEdgeManagement) GetClientTransportPool added in v0.23.23 

func (self *ZitiEdgeManagement) GetClientTransportPool() ClientTransportPool

GetClientTransportPool returns the transport pool managing multiple controller endpoints for failover.

func (*ZitiEdgeManagement) ListControllers added in v0.23.23 

func (self *ZitiEdgeManagement) ListControllers() (*rest_model.ControllersList, error)

ListControllers returns the list of available controllers for high-availability failover.

func (*ZitiEdgeManagement) RefreshApiSession added in v0.22.6 

func (self *ZitiEdgeManagement) RefreshApiSession(apiSession ApiSession, httpClient *http.Client) (ApiSession, error)

RefreshApiSession refreshes an existing API session (both legacy and OIDC types).

func (*ZitiEdgeManagement) SetAllowOidcDynamicallyEnabled added in v0.23.10 

func (self *ZitiEdgeManagement) SetAllowOidcDynamicallyEnabled(allow bool)

SetAllowOidcDynamicallyEnabled enables automatic OIDC capability detection on the controller.

func (*ZitiEdgeManagement) SetClientTransportPool added in v0.23.23 

func (self *ZitiEdgeManagement) SetClientTransportPool(transportPool ClientTransportPool)

SetClientTransportPool sets the transport pool.

func (*ZitiEdgeManagement) SetOidcRedirectUri added in v1.3.0 

func (self *ZitiEdgeManagement) SetOidcRedirectUri(redirectUri string)

func (*ZitiEdgeManagement) SetUseOidc added in v0.22.6 

func (self *ZitiEdgeManagement) SetUseOidc(use bool)

SetUseOidc forces OIDC mode (true) or legacy mode (false), overriding automatic detection.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.