registry_auth

README

registry_auth

a heavily modified fork of https://github.com/adxgun/registry-auth/

• removed all non-std dependencies
• X.509 certificate is not needed anymore
• provide LoadPrivateKey for loading private key file in PEM format
• auto-generate JWK fingerprint when TokenKeyID is not provided
• provide Handler instead of AuthServer which listen and serve TLS
  • (*Handler).HandleToken for docker-style GET /token with optional HTTP Basic auth
  • (*Handler).HandleOAuth2Token for OAuth2-style POST /token with grant_type=password
• HandlerConfig could configure service allowlist
• Authenticator.Authenticate now has service parameter
• Authorizer.Authorize now has to deal with multiple resource scopes
• AuthorizationRequest now has Context field, which is the HTTP request context
• AuthorizationRequest now has IP field, which parsed from the HTTP request RemoteAddr field and excluded link-local unicast address ranges
• DefaultAuthenticator & DefaultAuthorizor removed
• TokenGenerator interface removed
• jti (JWT ID) claim is optional, and we don't have any tracking mechanism, removed
• server_test.go removed, don't bother maintain it

reference server implementation available at https://github.com/zhangyoufu/registry_auth_server/

References

• Distribution Registry Token Authentication
• RFC 7638 JSON Web Key (JWK) Thumbprint
• RFC 8032 Edwards-Curve Digital Signature Algorithm (EdDSA)

Documentation

Index

• func LoadPrivateKey(path string) (crypto.Signer, error)
• type Authenticator
• type AuthorizationRequest
• type Authorizer
• type Handler
  • func NewHandler(cfg HandlerConfig) (*Handler, error)
  • func (h *Handler) HandleOAuth2Token(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) HandleToken(w http.ResponseWriter, r *http.Request)
• type HandlerConfig
• type ResourceScope
• type Scope

Functions

func LoadPrivateKey

func LoadPrivateKey(path string) (crypto.Signer, error)

Attempt to parse the given private key file.

Types

type Authenticator

type Authenticator interface {
	Authenticate(service, username, password string) error
}

Authenticator should be implemented to perform authentication. An implementation should return a non-nil error when authentication is not successful, otherwise a nil error should be returned

type AuthorizationRequest

type AuthorizationRequest struct {
	// Context provides the HTTP request context.
	Context context.Context

	// IP provides the source IP address from which the authorization request
	// originated. It holds one of the following formats:
	// - An IPv4 address in dotted-decimal notation (e.g., "192.0.2.1").
	// - An IPv6 address, excluding any scope zone identifier (e.g., "2001:db8::1").
	// - An empty string (""), indicating not available/applicable.
	//
	// Link-local unicast addresses (IPv4 169.254.0.0/16 and IPv6 fe80::/64)
	// require a scope zone (interface identifier, e.g., "%eth0") for proper
	// interpretation, as they are only unique within a specific network segment
	// (link). However, some access control engines may not be able to process
	// IP addresses with scope zones.[1] Consequently, to prevent potential
	// misinterpretation or incorrect policy matching, source IP addresses
	// falling within these link-local unicast CIDRs are ignored and stored
	// as an empty string in this field.
	//
	// [1]: https://github.com/ory/ladon/blob/1d16bb356d68220899c40d8b4a81120af55a6482/condition_cidr.go#L33-L51
	IP string

	// Service is usually the FQDN of the registry, aka. the RP (Resource
	// Provider). Corresponds to `aud` (Audience) claim in JWT. This field
	// is guaranteed to be non-empty.
	Service string

	// Authenticated username. Empty for anonymous requests. Corresponds to
	// `sub` (Subject) claim in JWT.
	Username string

	// An array of requested resource scopes. This field is guaranteed to be
	// non-empty for anonymous requests.
	Scope Scope
}

AuthorizationRequest provides necessary data for access control.

type Authorizer

type Authorizer interface {
	Authorize(req *AuthorizationRequest) (Scope, error)
}

Authorizer should be implemented to perform authorization. req.Actions should be checked against the user's authorized action on the repository, this function should return the list of authorized actions and a nil error. an empty list must be returned if requesting user is unauthorized

type Handler

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

func NewHandler

func NewHandler(cfg HandlerConfig) (*Handler, error)

func (*Handler) HandleOAuth2Token

func (h *Handler) HandleOAuth2Token(w http.ResponseWriter, r *http.Request)

func (*Handler) HandleToken

func (h *Handler) HandleToken(w http.ResponseWriter, r *http.Request)

type HandlerConfig

type HandlerConfig struct {
	// Authenticator authenticate access requests. Currently only username/password is supported.
	Authenticator Authenticator

	// Authorizer authorize access requests with fine-grained scope.
	Authorizer Authorizer

	// Services stores a allowlist for service. Every incoming request carries a service field, which is also stored in JWT `aud` (Audience) claim later on. Empty service is never allowed. Leave this field nil means allow any service.
	Services map[string]struct{}

	// TokenSigner sign tokens. Expected to be one of *rsa.PrivateKey, *ecdsa.PrivateKey, ed25519.PrivateKey.
	TokenSigner crypto.Signer

	// TokenKeyID provieds JWT `kid` (KeyID) claim. Empty means generate JWK fingerprint from TokenSigner as TokenKeyID.
	TokenKeyID string

	// TokenIssuer should match what is configured in distribution auth.token.issuer.
	TokenIssuer string

	// TokenExpire determine the valid duration for every new signed JWT.
	TokenExpire time.Duration
}

type ResourceScope

type ResourceScope struct {
	// The type of resource hosted by the service.
	Type string `json:"type"`

	// The name of the resource of the given type hosted by the service.
	Name string `json:"name"`

	// An array of strings which give the actions authorized on this resource.
	Actions []string `json:"actions"`
}

ResourceScope records actions on a named and typed resource.

type Scope

type Scope []*ResourceScope