auth

Documentation

Overview

Package auth contains types and functions to manage authentication credentials for service hosts.

Index

• type Credentials
  • func (c Credentials) ForHost(host svchost.Hostname) (HostCredentials, error)
• type CredentialsSource
  • func CachingCredentialsSource(source CredentialsSource) CredentialsSource
  • func HelperProgramCredentialsSource(executable string, args ...string) CredentialsSource
  • func StaticCredentialsSource(creds map[svchost.Hostname]map[string]interface{}) CredentialsSource
• type HostCredentials
  • func HostCredentialsFromMap(m map[string]interface{}) HostCredentials
• type HostCredentialsToken
  • func (tc HostCredentialsToken) PrepareRequest(req *http.Request)
  • func (tc HostCredentialsToken) Token() string

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.

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.

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)
}

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.

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"

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) Token

func (tc HostCredentialsToken) Token() string

Token returns the authentication token.