README
¶
CLI tools
The clitools contains helpers for building TT CLI tools.
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".
Configuration directory and environment loading
UserConfigDir() gives preference to XDG_CONFIG_HOME, letting users in any OS specify a linux-style user config location. If XDG_CONFIG_HOME is empty it behaves just like os.UserConfigDir().
LoadEnv() loads any ".env" (override by setting DOT_ENV) in the current path and "[user config dir]/[app]/config.env" if they exist. This will not override any variables that are set, and the .env file takes precedence over config.env.
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 := "stage"
oidcURL, err := clitools.OIDCConfigURL(clitools.StageOIDCServer, "elephant")
if err != nil {
panic(fmt.Errorf("get realm OIDC config URL: %w", err))
}
println("Sample application that demonstrates logging in to elephant from a CLI tool\n")
app, err := clitools.NewConfigurationHandler[SampleConf](
"clitools", clitools.DefaultApplicationID,
env, oidcURL,
)
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 ¶
- Constants
- func LoadEnv(app string) error
- func OIDCConfigURL(serverURL string, realm string) (string, error)
- func UserConfigDir() (string, error)
- type AccessToken
- type ConfigurationHandler
- func (ac *ConfigurationHandler[T]) GetAccessToken(ctx context.Context, environment string, scopes []string) (_ AccessToken, outErr error)
- func (ac *ConfigurationHandler[T]) GetClientAccessToken(ctx context.Context, environment string, clientID string, clientSecret string, ...) (oauth2.TokenSource, error)
- func (ac *ConfigurationHandler[T]) GetConfiguration() T
- func (ac *ConfigurationHandler[T]) GetOIDCConfig(ctx context.Context, environment string) (*OIDCConfig, error)
- func (ac *ConfigurationHandler[T]) Load() error
- func (ac *ConfigurationHandler[T]) RegisterEnvironment(ctx context.Context, name string, configURL string)
- func (ac *ConfigurationHandler[T]) Save() error
- func (ac *ConfigurationHandler[T]) SetConfiguration(conf T)
- type OIDCConfig
- type OIDCEnvironment
Examples ¶
Constants ¶
const ( StageOIDCServer = "https://login.stage.tt.se" ProdOIDCServer = "https://login.tt.se" )
Standard OIDC configurations endpoints at TT.
const DefaultApplicationID = "elephant-cli"
DefaultApplicationID when authorising CLI applications.
Variables ¶
This section is empty.
Functions ¶
func LoadEnv ¶ added in v0.3.0
LoadEnv loads any ".env" (override by setting DOT_ENV) in the current path and "[user config dir]/[app]/config.env" if they exist.
This will not override any variables that are set, and the .env file takes precedence over config.env.
func OIDCConfigURL ¶ added in v0.4.0
func UserConfigDir ¶ added in v0.3.0
UserConfigDir gives preference to XDG_CONFIG_HOME, letting users in any OS specify a linux-style user config location. If XDG_CONFIG_HOME is empty it behaves just like os.UserConfigDir().
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, environment string, oidcConfigURL 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]) GetClientAccessToken ¶ added in v0.4.0
func (ac *ConfigurationHandler[T]) GetClientAccessToken( ctx context.Context, environment string, clientID string, clientSecret string, scopes []string, ) (oauth2.TokenSource, error)
Convenience function for using the OIDC configuration to get a client credentials token source.
func (*ConfigurationHandler[T]) GetConfiguration ¶
func (ac *ConfigurationHandler[T]) GetConfiguration() T
GetConfiguration returns the application-specific configuration.
func (*ConfigurationHandler[T]) GetOIDCConfig ¶ added in v0.4.0
func (ac *ConfigurationHandler[T]) GetOIDCConfig( ctx context.Context, environment string, ) (*OIDCConfig, error)
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, configURL string, )
RegisterEnvironment can be used to register additional environments.
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"`
}
Source Files