senseauth

Documentation

Overview

Package senseauth implements the api.sense.com OAuth flow.

Sense uses its own sort of OAuth flow here, which is not easily supported by the standard golang.org/x/oauth2 package. Where possible, we make use of types and patterns from the standard package.

To use, first authenticate with Sense:

conf := senseauth.DefaultConfig
tok, err := conf.PasswordCredentialsToken(ctx, username, password)
if err != nil {
	return err
}

Then use the token to create an HTTP client:

client := conf.Client(tok)

There is also a TokenSource implementation that should be otherwise compatible with the types in the oauth2 package.

Index

• Variables
• func NewClientFrom(cli *http.Client, ts oauth2.TokenSource) *http.Client
• func SetDebug(l *log.Logger)
• type Config
  • func (c Config) Client(tok *oauth2.Token) *http.Client
  • func (c Config) ClientFrom(cli *http.Client, tok *oauth2.Token) *http.Client
  • func (c Config) PasswordCredentialsToken(ctx context.Context, creds PasswordCredentials) (tok *oauth2.Token, httpResponse *http.Response, err error)
  • func (c Config) TokenSource(tok *oauth2.Token) *TokenSource
• type MfaFunc
• type PasswordCredentials
• type TokenSource
  • func (t *TokenSource) Token() (*oauth2.Token, error)
  • func (t *TokenSource) TokenContext(ctx context.Context) (*oauth2.Token, error)

Variables

var DefaultConfig = Config{
	BaseURL: defaultApiUrl,
}

DefaultConfig is the default configuration for the Sense OAuth flow.

var ErrMFANeeded = errors.New("senseauth: MFA needed")

ErrMFANeeded indicates that MFA is needed to authenticate but no MFA func was provided.

Functions

func NewClientFrom

func NewClientFrom(cli *http.Client, ts oauth2.TokenSource) *http.Client

NewClientFrom returns an HTTP client, derived from the provided client, that will renew the token when needed. Renewals will use the provided token source in a background context.

func SetDebug

func SetDebug(l *log.Logger)

Types

type Config

type Config struct {
	// HttpClient is the client used for HTTP requests used by this flow.
	// If nil, http.DefaultClient is used.
	HttpClient *http.Client

	// BaseURL is the base URL for the Sense API.  If empty, "https://api.sense.com/apiservice/api/v1" is used.
	BaseURL string

	// InternalSenseClient is used internally.
	InternalSenseClient internalClient
}

Config is the configuration for the Sense OAuth flow.

func (Config) Client

func (c Config) Client(tok *oauth2.Token) *http.Client

Client returns an HTTP client that will renew the token when needed. The provided token must have been generated by the PasswordCredentialsToken method. Renewals will use the HTTP client configured in the Config in a background context. The returned client will otherwise be unassociated with the HTTP client in the Config.

func (Config) ClientFrom

func (c Config) ClientFrom(cli *http.Client, tok *oauth2.Token) *http.Client

ClientFrom returns an HTTP client, derived from the provided client, that will renew the token when needed. The provided token must have been generated by the PasswordCredentialsToken method. Renewals will use the HTTP client configured in the Config in a background context.

func (Config) PasswordCredentialsToken

func (c Config) PasswordCredentialsToken(ctx context.Context, creds PasswordCredentials) (tok *oauth2.Token, httpResponse *http.Response, err error)

PasswordCredentialsToken authenticates with the given email and password, and returns the token. Since Sense provides additional information in the authentication response, the response is returned as well so that the caller can do something with it. The caller does not have to call Close on the response Body. If multi-factor authentication is enabled for the account, and creds.MfaFn is not nil, it will be called to obtain the MFA code. If this returns an error, the authentication will be aborted.

func (Config) TokenSource

func (c Config) TokenSource(tok *oauth2.Token) *TokenSource

TokenSource returns a token source that will renew the token when needed. The provided token must have been generated by the PasswordCredentialsToken method. Renewals will use the HTTP client configured in the Config in a background context.

type MfaFunc

type MfaFunc func(ctx context.Context) (string, error)

type PasswordCredentials

type PasswordCredentials struct {
	Email    string
	Password string
	MfaFn    func(ctx context.Context) (string, error)
}

PasswordCredentials holds the credentials used to authenticate to the Sense API.

MfaFn is an optional function that returns the MFA code. This may be used during authentication if the Sense account requires MFA. It should return the MFA code or an error to indicate no MFA code is available and to abort the authentication. If implementations need to block on something, consider respecting ctx.Done().

type TokenSource

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

TokenSource is a token source that will renew the token when needed. It can be used with standard golang.org/x/oauth2 types.

func (*TokenSource) Token

func (t *TokenSource) Token() (*oauth2.Token, error)

Token returns a token that will renew the token when needed using the background context.

func (*TokenSource) TokenContext

func (t *TokenSource) TokenContext(ctx context.Context) (*oauth2.Token, error)

TokenContext returns a token, renewing it if needed using the provided context.