const (
// Known resource types.
TypeRepository = "repository"
TypeRegistry = "registry"
// Known action types.
ActionPull = "pull"
ActionPush = "push"
)
CatalogScope defines the resource scope used to allow listing all the items in a registry.
var CatalogScope = ResourceScope{ ResourceType: TypeRegistry, Resource: "catalog", Action: "*", }
var ErrHelperNotFound = errors.New("helper not found")
var ErrNoAuth = fmt.Errorf("no authorization token available to add to request")
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(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(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.
AuthConfig represents access to system level (e.g. config-file or command-execution based) configuration information.
It's OK to call EntryForRegistry concurrently.
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)
}
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
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
}
func ExecHelper(helperName string, serverURL string) (ConfigEntry, error)
ExecHelper executes an external program to get the credentials from a native store. It implements HelperRunner.
ConfigFile holds auth information for OCI registries as read from a configuration file. It implements Config.
type ConfigFile struct {
// contains filtered or unexported fields
}
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(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 (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.
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.
type HelperRunner = func(helperName string, serverURL string) (ConfigEntry, error)
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.
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.
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
}
func RequestInfoFromContext(ctx context.Context) RequestInfo
RequestInfoFromContext returns any request information associated with the context by ContextWithRequestInfo.
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.
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
}
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 (rs1 ResourceScope) Equal(rs2 ResourceScope) bool
Scope holds a set of ResourceScope values. The zero value represents the empty set.
type Scope struct {
// contains filtered or unexported fields
}
func NewScope(rss ...ResourceScope) Scope
NewScope returns a Scope value that holds the set of everything in rss.
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(ctx context.Context) Scope
ScopeFromContext returns any scope associated with the context by ContextWithScope.
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 (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 (s1 Scope) Contains(s2 Scope) bool
Contains reports whether s1 is a (non-strict) superset of s2.
func (s1 Scope) Equal(s2 Scope) bool
func (s Scope) Holds(r ResourceScope) bool
func (s Scope) IsEmpty() bool
IsEmpty reports whether the scope holds the empty set.
func (s Scope) IsUnlimited() bool
IsUnlimited reports whether s is unlimited in scope.
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 (s Scope) Len() int
Len returns the number of ResourceScopes in the scope set. It panics if the scope is unlimited.
func (s Scope) String() string
String returns the string representation of the scope, as suitable for passing to the token refresh "scopes" attribute.
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 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
}