ociauth

Documentation

Index

• Constants
• Variables
• func ContextWithRequestInfo(ctx context.Context, info RequestInfo) context.Context
• func ContextWithScope(ctx context.Context, s Scope) context.Context
• func NewStdTransport(p StdTransportParams) http.RoundTripper
• type Config
• type ConfigEntry
  • func ExecHelper(helperName string, serverURL string) (ConfigEntry, error)
• type ConfigFile
  • func Load(runner HelperRunner) (*ConfigFile, error)
  • func LoadWithEnv(runner HelperRunner, env []string) (*ConfigFile, error)
  • func (c *ConfigFile) EntryForRegistry(registryHostname string) (ConfigEntry, error)
• type HelperRunner
  • func ExecHelperWithEnv(env []string) HelperRunner
• type RequestInfo
  • func RequestInfoFromContext(ctx context.Context) RequestInfo
• type ResourceScope
  • func (rs1 ResourceScope) Compare(rs2 ResourceScope) int
  • func (rs1 ResourceScope) Equal(rs2 ResourceScope) bool
• type Scope
  • func NewScope(rss ...ResourceScope) Scope
  • func ParseScope(s string) Scope
  • func ScopeFromContext(ctx context.Context) Scope
  • func UnlimitedScope() Scope
  • func (s Scope) Canonical() Scope
  • func (s1 Scope) Contains(s2 Scope) bool
  • func (s1 Scope) Equal(s2 Scope) bool
  • func (s Scope) Holds(r ResourceScope) bool
  • func (s Scope) IsEmpty() bool
  • func (s Scope) IsUnlimited() bool
  • func (s Scope) Iter() func(yield func(ResourceScope) bool)
  • func (s Scope) Len() int
  • func (s Scope) String() string
  • func (s1 Scope) Union(s2 Scope) Scope
• type StdTransportParams

Constants

const (
	// Known resource types.
	TypeRepository = "repository"
	TypeRegistry   = "registry"

	// Known action types.
	ActionPull = "pull"
	ActionPush = "push"
)

Variables

var CatalogScope = ResourceScope{
	ResourceType: TypeRegistry,
	Resource:     "catalog",
	Action:       "*",
}

CatalogScope defines the resource scope used to allow listing all the items in a registry.

var ErrHelperNotFound = errors.New("helper not found")

var ErrNoAuth = fmt.Errorf("no authorization token available to add to request")

Functions

func ContextWithRequestInfo

func ContextWithRequestInfo(ctx context.Context, info RequestInfo) context.Context

ContextWithRequestInfo returns ctx annotated with the given request informaton. When ociclient receives a request with this attached, it will respect info.RequiredScope to determine what auth tokens to reuse. When it acquires a new token, it will ask for the union of info.RequiredScope ScopeFromContext.

func ContextWithScope

func ContextWithScope(ctx context.Context, s Scope) context.Context

ContextWithScope returns ctx annotated with the given scope. When the ociauth transport receives a request with a scope in the context, it will treat it as "desired authorization scope"; new authorization tokens will be acquired with that scope as well as any scope required by the operation.

func NewStdTransport

func NewStdTransport(p StdTransportParams) http.RoundTripper

NewStdTransport returns an http.RoundTripper implementation that acquires authorization tokens using the flows implemented by the usual docker clients. Note that this is _not_ documented as part of any official OCI spec.

See https://distribution.github.io/distribution/spec/auth/token/ for an overview.

The RoundTrip method acquires authorization before invoking the request. request. It may invoke the request more than once, and can use http.Request.GetBody to reset the request body if it gets consumed.

It ensures that the authorization token used will have at least the capability to execute operations in the required scope associated with the request context (see ContextWithRequestInfo). Any other auth scope inside the context (see ContextWithScope) may also be taken into account when acquiring new tokens.

Types

type Config

type Config interface {
	// EntryForRegistry returns auth information for the given host.
	// If there's no information available, it should return the zero ConfigEntry
	// and nil.
	EntryForRegistry(host string) (ConfigEntry, error)
}

AuthConfig represents access to system level (e.g. config-file or command-execution based) configuration information.

It's OK to call EntryForRegistry concurrently.

type ConfigEntry

type ConfigEntry struct {
	// RefreshToken holds a token that can be used to obtain an access token.
	RefreshToken string
	// AccessToken holds a bearer token to be sent to a registry.
	AccessToken string
	// Username holds the username for use with basic auth.
	Username string
	// Password holds the password for use with Username.
	Password string
}

ConfigEntry holds auth information for a registry. It mirrors the information obtainable from the .docker/config.json file and from the docker credential helper protocol

func ExecHelper

func ExecHelper(helperName string, serverURL string) (ConfigEntry, error)

ExecHelper executes an external program to get the credentials from a native store. It implements HelperRunner.

type ConfigFile

type ConfigFile struct {
	// contains filtered or unexported fields
}

ConfigFile holds auth information for OCI registries as read from a configuration file. It implements Config.

func Load

func Load(runner HelperRunner) (*ConfigFile, error)

Load loads the auth configuration from the first location it can find. It uses runner to run any external helper commands; if runner is nil, ExecHelper will be used.

In order it tries: - $DOCKER_CONFIG/config.json - ~/.docker/config.json - $XDG_RUNTIME_DIR/containers/auth.json

func LoadWithEnv

func LoadWithEnv(runner HelperRunner, env []string) (*ConfigFile, error)

LoadWithEnv is like Load but takes environment variables in the form returned by os.Environ instead of calling os.Getenv. If env is nil, the current process's environment will be used.

func (*ConfigFile) EntryForRegistry

func (c *ConfigFile) EntryForRegistry(registryHostname string) (ConfigEntry, error)

EntryForRegistry implements [Authorizer.InfoForRegistry]. If no registry is found, it returns the zero ConfigEntry and a nil error.

type HelperRunner

type HelperRunner = func(helperName string, serverURL string) (ConfigEntry, error)

HelperRunner is the function used to execute auth "helper" commands. It's passed the helper name as specified in the configuration file, without the "docker-credential-helper-" prefix.

If the credentials are not found, it should return the zero AuthInfo and no error.

If the helper doesn't exist, it should return an ErrHelperNotFound error.

func ExecHelperWithEnv

func ExecHelperWithEnv(env []string) HelperRunner

ExecHelperWithEnv returns a HelperRunner that behaves like ExecHelper except that, if env is non-nil, it will be used as the set of environment variables to pass to the executed helper command. If env is nil, the current process's environment will be used.

type RequestInfo

type RequestInfo struct {
	// RequiredScope holds the authorization scope that's required
	// by the request. The ociauth logic will reuse any available
	// auth token that has this scope. When acquiring a new token,
	// it will add any scope found in [ScopeFromContext] too.
	RequiredScope Scope
}

RequestInfo provides information about the OCI request that is currently being made. It is expected to be attached to an HTTP request context. The [ociclient] package will add this to all requests that is makes.

func RequestInfoFromContext

func RequestInfoFromContext(ctx context.Context) RequestInfo

RequestInfoFromContext returns any request information associated with the context by ContextWithRequestInfo.

type ResourceScope

type ResourceScope struct {
	// ResourceType holds the type of resource the scope refers to.
	// Known values for this include TypeRegistry and TypeRepository.
	// When a scope does not conform to the standard resourceType:resource:actions
	// syntax, ResourceType will hold the entire scope.
	ResourceType string

	// Resource names the resource the scope pertains to.
	// For resource type TypeRepository, this will be the name of the repository.
	Resource string

	// Action names an action that can be performed on the resource.
	// This is usually ActionPush or ActionPull.
	Action string
}

ResourceScope defines a component of an authorization scope associated with a single resource and action only. See Scope for a way of combining multiple ResourceScopes into a single value.

func (ResourceScope) Compare

func (rs1 ResourceScope) Compare(rs2 ResourceScope) int

Compare returns -1, 0 or 1 depending on whether rs1 compares less than, equal, or greater than, rs2.

In most to least precedence, the fields are compared in the order ResourceType, Resource, Action.

func (ResourceScope) Equal

func (rs1 ResourceScope) Equal(rs2 ResourceScope) bool

type Scope

type Scope struct {
	// contains filtered or unexported fields
}

Scope holds a set of ResourceScope values. The zero value represents the empty set.

func NewScope

func NewScope(rss ...ResourceScope) Scope

NewScope returns a Scope value that holds the set of everything in rss.

func ParseScope

func ParseScope(s string) Scope

ParseScope parses a scope as defined in the Docker distribution spec.

For scopes that don't fit that syntax, it returns a Scope with the ResourceType field set to the whole string.

func ScopeFromContext

func ScopeFromContext(ctx context.Context) Scope

ScopeFromContext returns any scope associated with the context by ContextWithScope.

func UnlimitedScope

func UnlimitedScope() Scope

UnlimitedScope returns a scope that contains all other scopes. This is not representable in the docker scope syntax, but it's useful to represent the scope of tokens that can be used for arbitrary access.

func (Scope) Canonical

func (s Scope) Canonical() Scope

Canonical returns s with the same contents but with its string form made canonical (the default is to mirror exactly the string that it was created with).

func (Scope) Contains

func (s1 Scope) Contains(s2 Scope) bool

Contains reports whether s1 is a (non-strict) superset of s2.

func (Scope) Equal

func (s1 Scope) Equal(s2 Scope) bool

func (Scope) Holds

func (s Scope) Holds(r ResourceScope) bool

func (Scope) IsEmpty

func (s Scope) IsEmpty() bool

IsEmpty reports whether the scope holds the empty set.

func (Scope) IsUnlimited

func (s Scope) IsUnlimited() bool

IsUnlimited reports whether s is unlimited in scope.

func (Scope) Iter

func (s Scope) Iter() func(yield func(ResourceScope) bool)

Iter returns an iterator over all the individual scopes that are part of s. The items will be produced according to [Scope.Compare] ordering.

The unlimited scope does not yield any scopes.

func (Scope) Len

func (s Scope) Len() int

Len returns the number of ResourceScopes in the scope set. It panics if the scope is unlimited.

func (Scope) String

func (s Scope) String() string

String returns the string representation of the scope, as suitable for passing to the token refresh "scopes" attribute.

func (Scope) Union

func (s1 Scope) Union(s2 Scope) Scope

Union returns a scope consisting of all the resource scopes from both s1 and s2. If the result is the same as s1, its string representation will also be the same as s1.

type StdTransportParams

type StdTransportParams struct {
	// Config represents the underlying configuration file information.
	// It is consulted for authorization information on the hosts
	// to which the HTTP requests are made.
	Config Config

	// HTTPClient is used to make the underlying HTTP requests.
	// If it's nil, [http.DefaultTransport] will be used.
	Transport http.RoundTripper
}