shellicator

README

shellicator

A simple library to get oauth2 tokens for shell commands.

This library opens a local http server to receive a callback from an oauth2 provider and stores the received token locally. It prints out the URL of the provider and if configured, opens a browser pointing to the oauth2 authcode URL.

For a working example: Example

Releases

Release 1.0.0

• Initial release

Release 2.0.0

• Device Grant Flow added

Minimal Example

Usage:

package main
import (
	"context"
	"errors"
	"fmt"
	"io/ioutil"
	"log"
	"os"

	"github.com/go-sharp/shellicator"
	"github.com/go-sharp/shellicator/providers"
)

func main() {
    // You can use any oauth2.Config you like. Important use scopes that
    // tells the provider to return a refresh token.
    // WithProvider is the only required option.
	auth := shellicator.NewAuthenticator(shellicator.WithProvider("google",
		providers.NewGoogleProvider(os.Getenv("SHELLICATOR_CLIENT_ID"),
            os.Getenv("SHELLICATOR_CLIENT_SECRET"))))

    // Now you can request a token. Per default this method will print out
    // an URL to the oauth2 provider. You can use options to open a browser
    // automatically. This call blocks until a answer is received (Default Timeout 5min).
    // The authentication is successfully if no error is returned.
    if err := auth.Authenticate("google"); err != nil {
			log.Fatal(err)
    }

    // Now you can get a client that uses the received token
    // and automatically refresh it if necessary.
    client, _ = auth.NewClient(context.Background(), "google")
    // Do something with the client

    // Or you get the received token with this call.
    token, _ = auth.GetToken("google")
    // Use the token
}

Per default tokens are stored in the volatile MemoryStorage. If persistence is required, use the FileStorage or implement your own Storager.

Documentation

Overview

Package shellicator is a simple library to get oauth2 tokens for shell commands.

This library opens a local http server to receive a callback from an oauth2 provider and stores the received token locally. It prints out the URL of the provider and if configured, opens a browser pointing to the oauth2 authcode URL.

Index

• type AuthOptions
  • func WithCallbackTemplate(html string) AuthOptions
  • func WithPorts(ports ...int) AuthOptions
  • func WithProvider(key string, prov Provider) AuthOptions
  • func WithStore(store Storager) AuthOptions
  • func WithTimeout(d time.Duration) AuthOptions
  • func WithUseDeviceGrant(key string, useDeviceGrant bool) AuthOptions
  • func WithUseOpenBrowserFeature(openBrowser bool) AuthOptions
  • func WithUsePrinter(printer func(ctx PrinterCtx)) AuthOptions
• type Authenticator
  • func NewAuthenticator(opts ...AuthOptions) Authenticator
  • func (a Authenticator) Authenticate(key string) error
  • func (a Authenticator) GetToken(key string) (*oauth2.Token, error)
  • func (a Authenticator) NewClient(ctx context.Context, key string) (*http.Client, error)
• type FileStorage
  • func (f FileStorage) RetrieveToken(key string) (*oauth2.Token, error)
  • func (f FileStorage) StoreToken(key string, token *oauth2.Token) error
• type MemoryStorage
  • func (m MemoryStorage) RetrieveToken(key string) (*oauth2.Token, error)
  • func (m MemoryStorage) StoreToken(key string, token *oauth2.Token) error
• type PrinterCtx
  • func (p PrinterCtx) IsDeviceGrant() bool
  • func (p PrinterCtx) VerificationURL() string
• type Provider
• type Storager

Types

type AuthOptions

type AuthOptions func(*Authenticator)

AuthOptions sets options for the Authenticator.

func WithCallbackTemplate

func WithCallbackTemplate(html string) AuthOptions

WithCallbackTemplate configures the authenticator to use the specified html for the callback page.

func WithPorts

func WithPorts(ports ...int) AuthOptions

WithPorts configures the Authenticator to use the specified ports. Default: 42000 - 42009

func WithProvider

func WithProvider(key string, prov Provider) AuthOptions

WithProvider configures an oauth provider with the specified key. RedirectURI will be overwritten and must not be set.

func WithStore

func WithStore(store Storager) AuthOptions

WithStore configures the authenticator to use the provided storager to save and restore tokens.

func WithTimeout

func WithTimeout(d time.Duration) AuthOptions

WithTimeout configures the timeout for the Authenticator. If timeout reached the Authenticator closes the local server and returns an error. Default: 5 minutes.

func WithUseDeviceGrant

func WithUseDeviceGrant(key string, useDeviceGrant bool) AuthOptions

WithUseDeviceGrant configures the authenticator to use the device grant flow.

func WithUseOpenBrowserFeature

func WithUseOpenBrowserFeature(openBrowser bool) AuthOptions

WithUseOpenBrowserFeature configures if a browser should automatically openend and navigate to the oauth AuthCodeURL. Default: false.

func WithUsePrinter

func WithUsePrinter(printer func(ctx PrinterCtx)) AuthOptions

WithUsePrinter configures to use the supplied function to print out the oauth AuthCodeURL. The function receives the AuthCodeURL of the chosen oauth provider.

type Authenticator

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

Authenticator handles oauth tokens for a command line application.

func NewAuthenticator

func NewAuthenticator(opts ...AuthOptions) Authenticator

NewAuthenticator returns a new Authenticator.

func (Authenticator) Authenticate

func (a Authenticator) Authenticate(key string) error

Authenticate opens a browser windows and navigates to the configured oauth provider (if configured). Otherwise it prints only the URL to the oauth provider.

func (Authenticator) GetToken

func (a Authenticator) GetToken(key string) (*oauth2.Token, error)

GetToken gets a stored oauth token.

func (Authenticator) NewClient

func (a Authenticator) NewClient(ctx context.Context, key string) (*http.Client, error)

NewClient returns a new http client with a stored oauth token. If no valid token was found, an ErrTokenNotFound error is returned.

type FileStorage

type FileStorage struct {
	Path string
	Name string
}

FileStorage saves and retrieves token from the file system.

func (FileStorage) RetrieveToken

func (f FileStorage) RetrieveToken(key string) (*oauth2.Token, error)

RetrieveToken retrieves a token from the file store.

func (FileStorage) StoreToken

func (f FileStorage) StoreToken(key string, token *oauth2.Token) error

StoreToken stores a token in the file store.

type MemoryStorage

type MemoryStorage map[string]*oauth2.Token

MemoryStorage implements an in-memory Storager.

func (MemoryStorage) RetrieveToken

func (m MemoryStorage) RetrieveToken(key string) (*oauth2.Token, error)

RetrieveToken retrieves a token from the in-memory store.

func (MemoryStorage) StoreToken

func (m MemoryStorage) StoreToken(key string, token *oauth2.Token) error

StoreToken stores a token in the in-memory store.

type PrinterCtx

type PrinterCtx struct {
	URL      string
	UserCode string
}

PrinterCtx passed to the printer function.

func (PrinterCtx) IsDeviceGrant

func (p PrinterCtx) IsDeviceGrant() bool

IsDeviceGrant returns true if device grant flow is used

func (PrinterCtx) VerificationURL

func (p PrinterCtx) VerificationURL() string

VerificationURL returns the verification url and can be used to generate a QR code.

type Provider

type Provider interface {
	OAuth2Config() oauth2.Config
	DeviceAuthURL() string
}

Provider is an interface that holds the configuration for the shellicator.

type Storager

type Storager interface {
	RetrieveToken(key string) (*oauth2.Token, error)
	StoreToken(key string, token *oauth2.Token) error
}

Storager persists tokens for later use.