credential

Documentation

Overview

Package credential provides the base implementation detail for the go-credentials library.

All of the logic for handling individual credentials is contained within this package. Before a Credential can be created, global application-level settings must be set in a factory.Factory object. Attributes aside from Username and Password are stored in a Profile object.

Index

• Constants
• type Credential
  • func Load(sourceFactory *factory.Factory) (*Credential, error)
  • func LoadFromEnvironment(credentialFactory *factory.Factory) (*Credential, error)
  • func LoadFromIniFile(profileName string, fromFactory *factory.Factory) (*Credential, error)
  • func LoadFromProfile(profileName string, sourceFactory *factory.Factory) (*Credential, error)
  • func New(credentialFactory *factory.Factory, username string, password string) (*Credential, error)
  • func (thisCredential *Credential) DeployEnv() error
  • func (thisCredential *Credential) GetAttribute(key string) (string, error)
  • func (thisCredential *Credential) GetEnvironmentVariables() []string
  • func (thisCredential *Credential) Save() error
  • func (thisCredential *Credential) SetAttribute(key string, value string) error
  • func (thisCredential *Credential) SetProfile(profileName string) error
• Bugs

Constants

const ERR_ATTRIBUTE_NOT_EXIST = "sorry that attribute hasn't been set on this credential"

const ERR_CREDENTIAL_NOT_INITIALIZED = "sorry, this credential has not been initialized"

const ERR_FACTORY_MUST_BE_INITIALIZED = "sorry the factory must be created correctly before proceeding"

const ERR_FACTORY_PRIVATE_ATTEMPT_DEPLOY = "you have attempted to deploy environment variables but your factory is private"

const ERR_JSON_FUNCTIONALITY_NOT_IMPLEMENTED = "sorry, that feature has not been implemented yet"

const ERR_KEY_MUST_MATCH_REGEX = "sorry the key must only include numbers, letters and underscores [0-9A-Za-z_]"

const ERR_USERNAME_OR_PASSWORD_NOT_SET = "sorry you must set a username or password"

Types

type Credential

type Credential struct {
	Username    string `json:"username"`
	Password    string `json:"password"`
	Initialized bool
	Factory     *factory.Factory
	Profile     *profile.Profile
	// contains filtered or unexported fields
}

Credential is the main object used by the go-credential library to manage user credentials. Username and Password are exported by default. The attributes of the Credential are not exported, as they should only be accessed via SetAttribute or GetAttribute.

func Load

func Load(sourceFactory *factory.Factory) (*Credential, error)

Load is the default method of loading existing credentials. First it will attempt to load credentials from the environment, as they take precedence over file-based credentials. If that is not successful, it will attempt to load credentials from the credentials file using the appropriate format set in the sourceFactory. If the file doesn't exist or is in an unexpected format, an error will be thrown.

TODO(7): Implement json format.

func LoadFromEnvironment

func LoadFromEnvironment(credentialFactory *factory.Factory) (*Credential, error)

LoadFromEnvironment is responsible for scanning environment variables and retrieves applicable variables that have the prefix of the application name that has been set in the credentialFactory. Most importantly, it will scan for the keys username or password; if an alternate for either of these have been set, those will be loaded instead. The respective properties Username and Password on the Credential object will be set. The rest of the variables will be stored as attributes and be accessible via GetAttribute. These are loaded into the Profile object and can also be accessed by its relevant functions.

Example 1: Normal Usage

If credentialFactory.ApplicationName has been set to TEST_APP, any environment variables beginning with TEST_APP will be imported into the Credential (and subsequently Profile) object.

Example 2: Alternates Usage

If credentialFactory.Alternates["username"] has been set to ACCESS_TOKEN, then if an environment variable named TEST_APP_ACCESS_TOKEN exists its value will be stored in the resulting Credential object's Username property.

func LoadFromIniFile

func LoadFromIniFile(profileName string, fromFactory *factory.Factory) (*Credential, error)

LoadFromIniFile is responsible for loading a Credential object as in the ini format at ~/.app_name/credentials. username and password are stored under the default heading, and all attributes are stored under the attributes heading

Example Credential File

[default]
username=my_username
password=my_password01

[attributes]
an_attribute=the value of an attribute

BUG(4): Respect alternates when loading from file.

func LoadFromProfile

func LoadFromProfile(profileName string, sourceFactory *factory.Factory) (*Credential, error)

LoadFromProfile specifically loads a Credential object from file. It will first load the relevant Credentials listed under the profileName in the credential file, then it will load the variables from the profile config file into Profile.

func New

func New(credentialFactory *factory.Factory, username string, password string) (*Credential, error)

New creates a new Credential instance. credentialFactory provides global application-level settings for the go-credential library. username and password are the user's base credentials. No other attributes are set during the initial creation of a Credential object, and these are stored in the Profile.

func (*Credential) DeployEnv

func (thisCredential *Credential) DeployEnv() error

DeployEnv is used in cases where your application requires environment variables, but your users configure their credentials via file-based methods. Simply Load the Credential from a file, then DeployEnv will deploy the variables as follows:

• Username: APP_NAME_USERNAME
• Other Attributes: APP_NAME_ATTRIBUTE_NAME

Currently, we do not export the Password property to the environment, but it is in the pipeline to enable this in the future.

TODO(3): Export Password via Boolean

func (*Credential) GetAttribute

func (thisCredential *Credential) GetAttribute(key string) (string, error)

GetAttribute retrieves an attribute that has been stored on the Credential's associated Profile. A key is passed in, and if the key does not have a value stored in the Profile, an error is returned.

func (*Credential) GetEnvironmentVariables

func (thisCredential *Credential) GetEnvironmentVariables() []string

GetEnvironmentVariables retrieves a list of internally managed environment variables that have been set by go-credentials. This value only has a value if DeployEnv has been used.

func (*Credential) Save

func (thisCredential *Credential) Save() error

Save is responsible for saving the credential at ~/.application_name/credentials in the specified output format that has been set on the Credentials' Factory object.

TODO(7): Implement json format.

func (*Credential) SetAttribute

func (thisCredential *Credential) SetAttribute(key string, value string) error

SetAttribute sets an attribute on a Credential object. key must match the regex '(?m)^[0-9A-Za-z_]+$'. There are no restrictions on the value of an attribute, aside from Go-level restrictions on strings. When these values are processed by Save(), they are stored in the config file for the Credential's currently set Profile. If username or password is passed as the attribute key, the set is redirected to the Username or Password property on the Credential object.

func (*Credential) SetProfile

func (thisCredential *Credential) SetProfile(profileName string) error

SetProfile sets the active profile on the Credential object. It does not change the value of the Credential's username or password, and only manages the attached Profile object.

Notes

Bugs

• Respect alternates when saving to file.