tlsclient

Documentation

Overview

Package tlsclient with a TLS client helper supporting certificate, JWT or Basic authentication

Index

• Constants
• type JwtAuthLogin
• type JwtAuthResponse
• type TLSClient
  • func NewTLSClient(hostPort string, caCert *x509.Certificate) *TLSClient
  • func (cl *TLSClient) Certificate() *tls.Certificate
  • func (cl *TLSClient) Close()
  • func (cl *TLSClient) ConnectNoAuth()
  • func (cl *TLSClient) ConnectWithBasicAuth(userID string, passwd string)
  • func (cl *TLSClient) ConnectWithClientCert(clientCert *tls.Certificate) (err error)
  • func (cl *TLSClient) ConnectWithJWTLogin(loginID string, secret string, authLoginURL string) (accessToken string, err error)
  • func (cl *TLSClient) ConnectWithJwtAccessToken(loginID string, accessToken string)
  • func (cl *TLSClient) Delete(path string, msg interface{}) ([]byte, error)
  • func (cl *TLSClient) Get(path string) ([]byte, error)
  • func (cl *TLSClient) Invoke(method string, url string, msg interface{}) ([]byte, error)
  • func (cl *TLSClient) Patch(path string, msg interface{}) ([]byte, error)
  • func (cl *TLSClient) Post(path string, msg interface{}) ([]byte, error)
  • func (cl *TLSClient) Put(path string, msg interface{}) ([]byte, error)
  • func (cl *TLSClient) RefreshJWTTokenIfExpired() error
  • func (cl *TLSClient) RefreshJWTTokens(refreshURL string) (refreshTokens *JwtAuthResponse, err error)

Constants

const (
	AuthMethodBasic    = "basic"  // basic auth for backwards compatibility when connecting to non HiveOT servers
	AuthMethodNone     = ""       // disable authentication, for testing
	AuthMethodJwt      = "jwt"    // JSON web token for use with HiveOT server (default)
	AuthMethodJwtToken = "access" // JWT access token provided by 3rd party
)

Authentication methods for use with ConnectWithLoginID Use AuthMethodDefault unless there is a good reason not to

const (
	// ParamOffset offset in case of multiple requests
	ParamOffset = "offset"
	// ParamLimit contains maximum number of results
	ParamLimit = "limit"
	// ParamQuery contains a query
	ParamQuery = "queryparams"
	// ParamUpdatedSince contains a ISO8601 datetime
	ParamUpdatedSince = "updatedSince"
	// ParamThings contains a list of Thing IDs to query for
	ParamThings = "things"
)

standardized query parameter names for querying servers

const (
	// DefaultJWTLoginPath for obtaining access & refresh tokens
	DefaultJWTLoginPath = "/auth/login"
	// DefaultJWTRefreshPath for refreshing tokens with the auth service
	DefaultJWTRefreshPath = "/auth/refresh"
	// DefaultJWTConfigPath for storing client configuration on the auth service
	DefaultJWTConfigPath = "/auth/config"
)

The default paths for user authentication and configuration

Types

type JwtAuthLogin

type JwtAuthLogin struct {
	LoginID    string `json:"login"` // typically the email
	Password   string `json:"password"`
	RememberMe bool   `json:"rememberMe"` // store refresh token in cookie
}

JwtAuthLogin defines the login request message to sent when using JWT authentication

type JwtAuthResponse

type JwtAuthResponse struct {
	AccessToken  string `json:"accessToken"`
	RefreshToken string `json:"refreshToken"`
	RefreshURL   string `json:"refreshURL"`
}

JwtAuthResponse defines the login or refresh response

type TLSClient

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

TLSClient is a simple TLS Client with authentication using certificates or JWT authentication with login/pw

func NewTLSClient

func NewTLSClient(hostPort string, caCert *x509.Certificate) *TLSClient

NewTLSClient creates a new TLS Client instance. Use connect/Close to open and close connections

hostPort is the server hostname or IP address and port to connect to
caCert with the x509 CA certificate, nil if not available

returns TLS client for submitting requests

func (*TLSClient) Certificate

func (cl *TLSClient) Certificate() *tls.Certificate

Certificate returns the client auth certificate or nil if none is used

func (*TLSClient) Close

func (cl *TLSClient) Close()

Close the connection with the server

func (*TLSClient) ConnectNoAuth

func (cl *TLSClient) ConnectNoAuth()

ConnectNoAuth creates a connection with the server without client authentication Only requests that do not require authentication will succeed

func (*TLSClient) ConnectWithBasicAuth

func (cl *TLSClient) ConnectWithBasicAuth(userID string, passwd string)

ConnectWithBasicAuth creates a server connection using the configured authentication Intended to connect to services that do not support JWT authentication

func (*TLSClient) ConnectWithClientCert

func (cl *TLSClient) ConnectWithClientCert(clientCert *tls.Certificate) (err error)

ConnectWithClientCert creates a connection with the server using a client certificate for mutual authentication. The provided certificate must be signed by the server's CA.

clientCert client tls certificate containing x509 cert and private key

Returns nil if successful, or an error if connection failed

func (*TLSClient) ConnectWithJWTLogin

func (cl *TLSClient) ConnectWithJWTLogin(loginID string, secret string, authLoginURL string) (accessToken string, err error)

ConnectWithJWTLogin requests JWT tokens using loginID/password If a CA certificate is not available then insecure-skip-verify is used to allow connection to an unverified server (leap of faith).

This uses JWT authentication using the POST /login path with a Json encoded JwtAuthLogin message as body.

The server returns a JwtAuthResponse message with an access/refresh token pair and a refresh URL. The access token is used as bearer token in the Authentication header for followup requests.

loginID username or application ID to identify as.
secret to authenticate with.
authLoginURL optional full address of the authentication server login, "" to authenticate using the application server /login

Returns nil if successful or an error if setting up of authentication failed.

func (*TLSClient) ConnectWithJwtAccessToken

func (cl *TLSClient) ConnectWithJwtAccessToken(loginID string, accessToken string)

ConnectWithJwtAccessToken Sets login ID and secret for JWT authentication using an access token obtained elsewhere. This uses the provided access token as bearer token in the authorization header

func (*TLSClient) Delete

func (cl *TLSClient) Delete(path string, msg interface{}) ([]byte, error)

Delete sends a delete message with json payload

path to invoke
msg message object to include. This will be marshalled to json

func (*TLSClient) Get

func (cl *TLSClient) Get(path string) ([]byte, error)

Get is a convenience function to send a request

path to invoke

func (*TLSClient) Invoke

func (cl *TLSClient) Invoke(method string, url string, msg interface{}) ([]byte, error)

Invoke a HTTPS method and read response If Basic or JWT authentication is enabled then add the auth info to the headers

method: GET, PUT, POST, ...
url: full URL to invoke
msg message object to include. Non strings will be marshalled to json

func (*TLSClient) Patch

func (cl *TLSClient) Patch(path string, msg interface{}) ([]byte, error)

Patch sends a patch message with json payload

path to invoke
msg message object to include. Non strings will be marshalled to json

func (*TLSClient) Post

func (cl *TLSClient) Post(path string, msg interface{}) ([]byte, error)

Post a message with json payload

path to invoke
msg message object to include. Non strings will be marshalled to json

func (*TLSClient) Put

func (cl *TLSClient) Put(path string, msg interface{}) ([]byte, error)

Put a message with json payload

path to invoke
msg message object to include. Non strings will be marshalled to json

func (*TLSClient) RefreshJWTTokenIfExpired

func (cl *TLSClient) RefreshJWTTokenIfExpired() error

RefreshJWTTokenIfExpired checks if the JWT access token is expired. If so, then refresh it. If the refresh token does not exist or the access token is not a JWT token then return without further action. If no refresh token exists or refresh fails then return an error. This means that a new login is required.

func (*TLSClient) RefreshJWTTokens

func (cl *TLSClient) RefreshJWTTokens(refreshURL string) (refreshTokens *JwtAuthResponse, err error)

RefreshJWTTokens refreshes the JWT access and bearer token

refreshURL to use. "" for using the application server and default refresh path

This returns a struct with new access and refresh token