Documentation
¶
Overview ¶
Package auth contains types and functions to manage authentication credentials for service hosts.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Credentials ¶
type Credentials []CredentialsSource
Credentials is a list of CredentialsSource objects that can be tried in turn until one returns credentials for a host, or one returns an error.
A Credentials is itself a CredentialsSource, wrapping its members. In principle one CredentialsSource can be nested inside another, though there is no good reason to do so.
The write operations on a Credentials are tried only on the first object, under the assumption that it is the primary store.
func (Credentials) ForHost ¶
func (c Credentials) ForHost(host svchost.Hostname) (HostCredentials, error)
ForHost iterates over the contained CredentialsSource objects and tries to obtain credentials for the given host from each one in turn.
If any source returns either a non-nil HostCredentials or a non-nil error then this result is returned. Otherwise, the result is nil, nil.
func (Credentials) ForgetForHost ¶
func (c Credentials) ForgetForHost(host svchost.Hostname) error
ForgetForHost passes the given arguments to the same operation on the first CredentialsSource in the receiver.
func (Credentials) StoreForHost ¶
func (c Credentials) StoreForHost(host svchost.Hostname, credentials HostCredentialsWritable) error
StoreForHost passes the given arguments to the same operation on the first CredentialsSource in the receiver.
type CredentialsSource ¶
type CredentialsSource interface {
// ForHost returns a non-nil HostCredentials if the source has credentials
// available for the host, and a nil HostCredentials if it does not.
//
// If an error is returned, progress through a list of CredentialsSources
// is halted and the error is returned to the user.
ForHost(host svchost.Hostname) (HostCredentials, error)
// StoreForHost takes a HostCredentialsWritable and saves it as the
// credentials for the given host.
//
// If credentials are already stored for the given host, it will try to
// replace those credentials but may produce an error if such replacement
// is not possible.
StoreForHost(host svchost.Hostname, credentials HostCredentialsWritable) error
// ForgetForHost discards any stored credentials for the given host. It
// does nothing and returns successfully if no credentials are saved
// for that host.
ForgetForHost(host svchost.Hostname) error
}
A CredentialsSource is an object that may be able to provide credentials for a given host.
Credentials lookups are not guaranteed to be concurrency-safe. Callers using these facilities in concurrent code must use external concurrency primitives to prevent race conditions.
var NoCredentials CredentialsSource = Credentials{}
NoCredentials is an empty CredentialsSource that always returns nil when asked for credentials.
func CachingCredentialsSource ¶
func CachingCredentialsSource(source CredentialsSource) CredentialsSource
CachingCredentialsSource creates a new credentials source that wraps another and caches its results in memory, on a per-hostname basis.
No means is provided for expiration of cached credentials, so a caching credentials source should have a limited lifetime (one Terraform operation, for example) to ensure that time-limited credentials don't expire before their cache entries do.
func HelperProgramCredentialsSource ¶
func HelperProgramCredentialsSource(executable string, args ...string) CredentialsSource
HelperProgramCredentialsSource returns a CredentialsSource that runs the given program with the given arguments in order to obtain credentials.
The given executable path must be an absolute path; it is the caller's responsibility to validate and process a relative path or other input provided by an end-user. If the given path is not absolute, this function will panic.
When credentials are requested, the program will be run in a child process with the given arguments along with two additional arguments added to the end of the list: the literal string "get", followed by the requested hostname in ASCII compatibility form (punycode form).
func StaticCredentialsSource ¶
func StaticCredentialsSource(creds map[svchost.Hostname]map[string]interface{}) CredentialsSource
StaticCredentialsSource is a credentials source that retrieves credentials from the provided map. It returns nil if a requested hostname is not present in the map.
The caller should not modify the given map after passing it to this function.
type HostCredentials ¶
type HostCredentials interface {
// PrepareRequest modifies the given request in-place to apply the
// receiving credentials. The usual behavior of this method is to
// add some sort of Authorization header to the request.
PrepareRequest(req *http.Request)
// Token returns the authentication token.
Token() string
}
HostCredentials represents a single set of credentials for a particular host.
func HostCredentialsFromMap ¶
func HostCredentialsFromMap(m map[string]interface{}) HostCredentials
HostCredentialsFromMap converts a map of key-value pairs from a credentials definition provided by the user (e.g. in a config file, or via a credentials helper) into a HostCredentials object if possible, or returns nil if no credentials could be extracted from the map.
This function ignores map keys it is unfamiliar with, to allow for future expansion of the credentials map format for new credential types.
func HostCredentialsFromObject ¶
func HostCredentialsFromObject(obj cty.Value) HostCredentials
HostCredentialsFromObject converts a cty.Value of an object type into a HostCredentials object if possible, or returns nil if no credentials could be extracted from the map.
This function ignores object attributes it is unfamiliar with, to allow for future expansion of the credentials object structure for new credential types.
If the given value is not of an object type, this function will panic.
type HostCredentialsToken ¶
type HostCredentialsToken string
HostCredentialsToken is a HostCredentials implementation that represents a single "bearer token", to be sent to the server via an Authorization header with the auth type set to "Bearer".
To save a token as the credentials for a host, convert the token string to this type and use the result as a HostCredentialsWritable implementation.
func (HostCredentialsToken) PrepareRequest ¶
func (tc HostCredentialsToken) PrepareRequest(req *http.Request)
PrepareRequest alters the given HTTP request by setting its Authorization header to the string "Bearer " followed by the encapsulated authentication token.
func (HostCredentialsToken) ToStore ¶
func (tc HostCredentialsToken) ToStore() cty.Value
ToStore returns a credentials object with a single attribute "token" whose value is the token string.
func (HostCredentialsToken) Token ¶
func (tc HostCredentialsToken) Token() string
Token returns the authentication token.
type HostCredentialsWritable ¶
type HostCredentialsWritable interface {
HostCredentials
// ToStore returns a cty.Value, always of an object type,
// representing data that can be serialized to represent this object
// in persistent storage.
//
// The resulting value may uses only cty values that can be accepted
// by the cty JSON encoder, though the caller may elect to instead store
// it in some other format that has a JSON-compatible type system.
ToStore() cty.Value
}
HostCredentialsWritable is an extension of HostCredentials for credentials objects that can be serialized as a JSON-compatible object value for storage.
Source Files