clitools

package module
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Jan 24, 2025 License: MIT Imports: 17 Imported by: 2

README

CLI tools

The clitools contains helpers for building TT CLI tools. Current functionality includes configuration handling and authenticating against our OIDC provider.

Logging in using the ConfigurationHandler

See the example in the Go docs.

Configuration and tokens will be saved in $XDG_CONFIG_HOME or the appropriate user configuration directory for your platform, for Linux this is "~/.config/[name of application]/". Configuration is stored in "config.json" and the access tokens in "tokens.json".

Documentation

Overview

Example
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/ttab/clitools"
)

func main() {
	// SampleConf - any addional configuration you want to store.
	type SampleConf struct {
		SomeSetting string `json:"some_setting"`
	}

	env := clitools.EnvStage

	println("Sample application that demonstrates logging in to elephant from a CLI tool\n")

	app, err := clitools.NewConfigurationHandler[SampleConf]("clitools", "elephant-cli")
	if err != nil {
		panic(fmt.Errorf("create configuration handler: %w", err))
	}

	token, err := app.GetAccessToken(context.Background(), env, []string{
		"doc_read",
	})
	if err != nil {
		panic(fmt.Errorf("authenticate: %w", err))
	}

	app.SetConfiguration(SampleConf{
		SomeSetting: "that we want to track",
	})

	err = app.Save()
	if err != nil {
		panic(fmt.Errorf("save configuration: %w", err))
	}

	enc := json.NewEncoder(os.Stdout)

	enc.SetIndent("", "  ")

	println("Current token:")
	_ = enc.Encode(token)
}

Index

Examples

Constants

View Source
const (
	EnvLocal = "local"
	EnvStage = "stage"
	EnvProd  = "prod"
)

Default environments. EnvLocal will by default be mapped to the stage OIDC configuration endpoint.

View Source
const (
	StageOIDCConfigURL = "https://login.stage.tt.se/realms/elephant/.well-known/openid-configuration"
	ProdOIDCConfigURL  = "https://login.tt.se/realms/elephant/.well-known/openid-configuration"
)

Standard OIDC configurations endpoints at TT.

View Source
const DefaultApplicationID = "elephant-cli"

DefaultApplicationID when authorising CLI applications.

Variables

This section is empty.

Functions

This section is empty.

Types

type AccessToken

type AccessToken struct {
	Token         string    `json:"token"`
	Expires       time.Time `json:"expires"`
	Scopes        []string  `json:"scopes"`
	GrantedScopes []string  `json:"granted_scopes"`
}

AccessToken that can be used to communicate with our APIs.

type ConfigurationHandler

type ConfigurationHandler[T any] struct {
	// contains filtered or unexported fields
}

func NewConfigurationHandler

func NewConfigurationHandler[T any](name string, clientID string) (*ConfigurationHandler[T], error)

NewConfigurationHandler crates a configuration handler using the application specific configuration T, and loads the current configuration from disk if it's available. Name is used as the directory name for the stored configuration, and clientID must match what has been set up in our OIDC provider.

func (*ConfigurationHandler[T]) GetAccessToken

func (ac *ConfigurationHandler[T]) GetAccessToken(
	ctx context.Context, environment string, scopes []string,
) (_ AccessToken, outErr error)

GetAccessToken either returns an existing non-expired token for the environment that matches the requested scope, or starts the authorization flow to get a new token.

During the authorisation flow we will attempt to automatically open a URL in the users browser.

func (*ConfigurationHandler[T]) GetConfiguration

func (ac *ConfigurationHandler[T]) GetConfiguration() T

GetConfiguration returns the application-specific configuration.

func (*ConfigurationHandler[T]) Load added in v0.2.0

func (ac *ConfigurationHandler[T]) Load() error

Load configuration and tokens from disk.

func (*ConfigurationHandler[T]) RegisterEnvironment

func (ac *ConfigurationHandler[T]) RegisterEnvironment(
	ctx context.Context,
	name string, conf OIDCEnvironment,
) error

RegisterEnvironment can be used to register a non-standard environment.

func (*ConfigurationHandler[T]) Save

func (ac *ConfigurationHandler[T]) Save() error

Save configuration and tokens to disk.

func (*ConfigurationHandler[T]) SetConfiguration

func (ac *ConfigurationHandler[T]) SetConfiguration(conf T)

GetConfiguration updates the application-specific configuration.

type OIDCConfig added in v0.2.0

type OIDCConfig struct {
	Issuer                string `json:"issuer"`
	AuthorizationEndpoint string `json:"authorization_endpoint"`
	TokenEndpoint         string `json:"token_endpoint"`
	IntrospectionEndpoint string `json:"introspection_endpoint"`
	UserinfoEndpoint      string `json:"userinfo_endpoint"`
	EndSessionEndpoint    string `json:"end_session_endpoint"`
}

type OIDCEnvironment added in v0.2.0

type OIDCEnvironment struct {
	Refreshed     time.Time   `json:"refreshed,omitempty,omitzero"`
	OIDCConfigURL string      `json:"oidc_config_url,omitempty"`
	OIDCConfig    *OIDCConfig `json:"oidc_config"`
}

func (*OIDCEnvironment) EnsureOIDCConfig added in v0.2.0

func (ce *OIDCEnvironment) EnsureOIDCConfig(
	ctx context.Context, client *http.Client, maxAge time.Duration,
) (outErr error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL