ztchooks

README

ZTC Hooks

ztchooks provides primitives for serializing and verifying hooks fired from ZeroTier Central

Example

A partial example of how to use this library can be found in the example directory

License

Copyright 2023 ZeroTier, Inc. All rights reserved. Licensed under the Mozilla Public License Version 2.0. See the LICENSE file for the full license text.

Documentation

Overview

Package ztchooks provides primitives for serializing and verifying hooks fired from [ZeroTier Central](https://my.zerotier.com)

Index

• Variables
• func HookTypeToString(hType HookType) string
• func VerifyHookSignature(preSharedKey, sigHeader string, payload []byte, tolerance time.Duration) error
• type HookBase
• type HookType
  • func GetHookType(data []byte) (HookType, error)
  • func HookTypeFromString(hType string) HookType
• type MemberConfigChanged
• type MemberDeleted
• type NetworkConfigChanged
• type NetworkCreated
• type NetworkDeleted
• type NetworkMemberAuth
• type NetworkMemberDeauth
• type NetworkSSOLogin
• type NetworkSSOLoginError
• type NewMemberJoined
• type OrgInviteAccepted
• type OrgInviteRejected
• type OrgInviteSent
• type OrgMemberRemoved

Variables

var (
	ErrInvalidSignatureHeader = errors.New("webhook has no signature header")
	ErrInvalidPreSharedKey    = errors.New("invalid pre shared key")
	ErrInvalidHeader          = errors.New("webhook has invalid header")
	ErrInvalidSignature       = errors.New("webhook has no valid signature")
	ErrTimestampExpired       = errors.New("timestamp has expired")
)

var (
	DefaultTolerance = 5 * time.Minute
)

Functions

func HookTypeToString

func HookTypeToString(hType HookType) string

HookTypeToString is a convenience function to convert from HookType to a string

func VerifyHookSignature

func VerifyHookSignature(preSharedKey, sigHeader string, payload []byte, tolerance time.Duration) error

VerifyHookSignature takes your pre-shared key, the value of the signature header, and the JSON payload and verifies the signature. tolerance determines how large of a time difference to tolerate in order to prevent a replay attack

Types

type HookBase

type HookBase struct {
	// HookID is the internal ZeroTier Central ID of the hook being fired
	HookID string `json:"hook_id"`

	// OrgID is the internal Organization ID the hook belongs to
	OrgID string `json:"org_id"`

	// HookType is the type of hook being fired.
	HookType HookType `json:"hook_type"`
}

HookBase contains the base information present in all webhooks sent by ZeroTier Central

type HookType

type HookType string

const (
	HOOK_TYPE_UNKNOWN       HookType = "UNKNOWN"
	NETWORK_JOIN            HookType = "NETWORK_JOIN"
	NETWORK_AUTH            HookType = "NETWORK_AUTH"
	NETWORK_DEAUTH          HookType = "NETWORK_DEAUTH"
	NETWORK_SSO_LOGIN       HookType = "NETWORK_SSO_LOGIN"
	NETWORK_SSO_LOGIN_ERROR HookType = "NETWORK_SSO_LOGIN_ERROR"
	NETWORK_CREATED         HookType = "NETWORK_CREATED"
	NETWORK_CONFIG_CHANGED  HookType = "NETWORK_CONFIG_CHANGED"
	NETWORK_DELETED         HookType = "NETWORK_DELETED"
	MEMBER_CONFIG_CHANGED   HookType = "MEMBER_CONFIG_CHANGED"
	MEMBER_DELETED          HookType = "MEMBER_DELETED"
	ORG_INVITE_SENT         HookType = "ORG_INVITE_SENT"
	ORG_INVITE_ACCEPTED     HookType = "ORG_INVITE_ACCEPTED"
	ORG_INVITE_REJECTED     HookType = "ORG_INVITE_REJECTED"
	ORG_MEMBER_REMOVED      HookType = "ORG_MEMBER_REMOVED"
)

HooKTypes

func GetHookType

func GetHookType(data []byte) (HookType, error)

GetHookType decodes the `HookBase` portion of the data to determine and return the `HookType`

func HookTypeFromString

func HookTypeFromString(hType string) HookType

HookTypeFromString is a convenience function to convert from a string to a HookType value

type MemberConfigChanged

type MemberConfigChanged struct {
	HookBase

	// NetworkID is the network the member was joined to
	NetworkID string `json:"network_id"`

	// MemberID is the network member that was changed
	MemberID string `json:"member_id"`

	// OldConfig is the network member configuration prior to the change
	OldConfig map[string]any `json:"old_config"`

	// NewConfig is the newly applied member configuration
	NewConfig map[string]any `json:"new_config"`

	// UserID is the ID of the user that modified the network member
	UserID string `json:"user_id"`

	// UserEmail is the email address of the user that modified the network member
	UserEmail string `json:"user_email"`

	// MemberMetadata is any metadata attached to the member object
	MemberMetadata map[string]interface{} `json:"metadata"`
}

MemberConfigChanged is fired when a network member's configuration changes

type MemberDeleted

type MemberDeleted struct {
	HookBase

	// NetworkID is the network the member was joined to
	NetworkID string `json:"network_id"`

	// MemberID is the network member that was deleted
	MemberID string `json:"member_id"`

	// OldConfig is the network member configuration prior to the deletion
	OldConfig map[string]any `json:"old_config"`

	// UserID is the ID of the user that deleted the network member
	UserID string `json:"user_id"`

	// UserEmail is the email address of the user that deleted the network member
	UserEmail string `json:"user_email"`

	// MemberMetadata is any metadata attached to the member object
	MemberMetadata map[string]interface{} `json:"metadata"`
}

type NetworkConfigChanged

type NetworkConfigChanged struct {
	HookBase

	// NetworkID is the network on which the SSO login attempt was performed
	NetworkID string `json:"network_id"`

	// UserID is the user that performed the network configuration change
	UserID string `json:"user_id"`

	// UserEmail is the email address of the user that performed the network configuration change
	UserEmail string `json:"user_email"`

	// OldConfig is the network configuration before the change was applied
	OldConfig map[string]any `json:"old_config"`

	// NewConfig is the new configuration for the network.
	NewConfig map[string]any `json:"new_config"`

	// NetworkMetadata is any metadata attached to the network object
	NetworkMetadata map[string]interface{} `json:"metadata"`
}

NetworkConfigChanged is fired whenever the configuration of a ZeroTier network changes

type NetworkCreated

type NetworkCreated struct {
	HookBase

	// NetworkID is the ID of the newly created network
	NetworkID string `json:"network_id"`

	// NetworkConfig is the initial configuration of the new network
	NetworkConfig map[string]any `json:"network_config"`

	// UserID is the ID of the user creating the network
	UserID string `json:"user_id"`

	// UserEmail is the email address of the user creating the network
	UserEmail string `json:"user_email"`

	// NetworkMetadata is any metadata attached to the network object
	NetworkMetadata map[string]interface{} `json:"metadata"`
}

NetworkCreated is fired whenever an organization member creates a new network

type NetworkDeleted

type NetworkDeleted struct {
	HookBase

	// NetworkID is the network that was deleted
	NetworkID string `json:"network_id"`

	// OldConfig is the network configuration before the network was deleted
	OldConfig map[string]any `json:"old_config"`

	// UserID is the ID of the user that deleted the network
	UserID string `json:"user_id"`

	// UserEmail is the email address of the user that deleted the network
	UserEmail string `json:"user_email"`

	// NetworkMetadata is any metadata attached to the network object
	NetworkMetadata map[string]interface{} `json:"metadata"`
}

NetworkDeleted is fired whenever a network configuration is changed

type NetworkMemberAuth

type NetworkMemberAuth struct {
	HookBase

	// NetworkID is the network that the member was authorized to join
	NetworkID string `json:"network_id"`

	// MemberID is the member authorized to join the network
	MemberID string `json:"member_id"`

	// UserID is the user that performed the authorization
	UserID string `json:"user_id"`

	// UserEmail is the email address of the user performing the authorization
	UserEmail string `json:"user_email"`

	// MemberMetadata is any metadata attached to the member object
	MemberMetadata map[string]interface{} `json:"metadata"`
}

NetworkMemberAuth is fired for `NETWORK_AUTH` events

type NetworkMemberDeauth

type NetworkMemberDeauth struct {
	HookBase

	// NetworkID is the network that new member was deauthorized from
	NetworkID string `json:"network_id"`

	// MemberID is the member deauthorized from accessing the network
	MemberID string `json:"member_id"`

	// UserID is the user that performed the deauthorization
	UserID string `json:"user_id"`

	// UserEmail is the email address of the user performing the deauthorization
	UserEmail string `json:"user_email"`

	// MemberMetadata is any metadata attached to the member object
	MemberMetadata map[string]interface{} `json:"metadata"`
}

NetworkMemberDeauth is fired for `NETWORK_DEAUTH` events

type NetworkSSOLogin

type NetworkSSOLogin struct {
	HookBase

	// NetworkID is the network on which the SSO login was performed
	NetworkID string `json:"network_id"`

	// MemberID is the network member ID on which the SSO login was performed
	MemberID string `json:"member_id"`

	// SSOUserEmail is the email address of the user logging into the network
	SSOUserEmail string `json:"sso_user_email"`

	// NetworkMetadata is any metadata attached to the network object
	NetworkMetadata map[string]interface{} `json:"metadata"`
}

NetworkSSOLogin is fired whenever a user logs into a network via a configured OIDC provider

type NetworkSSOLoginError

type NetworkSSOLoginError struct {
	HookBase

	// NetworkID is the network on which the SSO login attempt was performed
	NetworkID string `json:"network_id"`

	// MemberID is the network member ID on which the SSO login attempt was performed
	MemberID string `json:"member_id"`

	// SSOUserEmail is the email address of the user attempting to login into the network
	SSOUserEmail string `json:"sso_user_email"`

	// Error is a description of the error
	Error string `json:"error"`

	// NetworkMetadata is any metadata attached to the network object
	NetworkMetadata map[string]interface{} `json:"metadata"`
}

NetworkSSOLoginError is fired when there is a failure during the SSO login process

type NewMemberJoined

type NewMemberJoined struct {
	HookBase

	// NetworkID is the network a new member has joined
	NetworkID string `json:"network_id"`

	// MemberID is the member that is attempting to join the network.
	MemberID string `json:"member_id"`
}

NewMemberJoined is fired for `NETWORK_JOIN` hooks. This hook is fired the first time the controller sees a new member attempting to join a ZeroTier network

type OrgInviteAccepted

type OrgInviteAccepted struct {
	HookBase

	// UserID is the user ID accepting the invite
	UserID string `json:"user_id"`

	// UserEmail is the email address of the user accepting the invite
	UserEmail string `json:"user_email"`

	// NetworkIDs transferred to the org in the acceptance process
	NetworkIDs []string `json:"network_ids"`
}

OrgInviteAccepted is fired when a user accepts the invitation to join your organization

type OrgInviteRejected

type OrgInviteRejected struct {
	HookBase

	// UserID is the user ID rejecting the invite
	UserID string `json:"user_id"`

	// UserEmail is the email address of the user rejecting the invite
	UserEmail string `json:"user_email"`
}

OrgInviteRejected is fired when a user rejects the invite to the organization

type OrgInviteSent

type OrgInviteSent struct {
	HookBase

	// UserID is the user sending the invite
	UserID string `json:"user_id"`

	// InviteeEmail is the email address of the invitee
	InviteeEmail string `json:"invitee_email"`
}

OrgInviteSent is fired whenever a new member is invited to join your ZeroTer organization in ZeroTier Central. Because only the org owner can add or remove people from the org, the ID of the person performing the invite is omitted.

type OrgMemberRemoved

type OrgMemberRemoved struct {
	HookBase

	// UserID is the user performing the remove operation
	UserID string `json:"user_id"`

	// RemovedUserID is the ID of the user removed from the org
	RemovedUserID string `json:"removed_user_id"`

	// RemovedUserEmail is the email address of the user removed from the organization
	RemovedUserEmail string `json:"removed_user_email"`
}

OrgMemberRemoved is fired whenever an organization member is removed. Since currently only the org owner can add or remove people from the org, the ID of the person performing the removal is omitted.