Documentation ¶
Index ¶
- Constants
- Variables
- func GetSubjectName(subject Subject) string
- type AccessToken
- type AccessTokenIssuer
- type Authenticator
- type Authorizer
- type LoggerTokenService
- type OAuth2Request
- type OAuth2Response
- type PasswordAuthenticator
- type RefreshTokenAuthenticator
- type RefreshTokenIssuer
- type Resource
- type Scope
- type Scopes
- type Subject
- type SubjectID
- type TokenIssuer
- type TokenRequest
- type TokenResponse
- type TokenServer
- type TokenService
- type TokenServiceImpl
Constants ¶
const ( GrantTypeRefreshToken = "refresh_token" GrantTypePassword = "password" AccessTypeOnline = "online" AccessTypeOffline = "offline" )
const ( // SubjectName is an attribute key for Subject providing an alternate name. SubjectName = "name" // SubjectType is an arbitrary classification of a Subject that an Authorizer can base authorization decisions on. // For example: users may have their own personal workspace to push to, machine users (commonly known as service account) may not. // SubjectType can also serve as a component for a composite key that uniquely identifies a Subject. SubjectType = "type" )
Attribute keys
Variables ¶
var ErrAuthenticationFailed = errors.New("authentication failed")
ErrAuthenticationFailed is returned when authentication fails.
This error should only be returned if credential verification fails. Any other error (eg. connection problems) should be returned directly.
ErrUnauthorized is returned when a client did not provide any credentials and the authorization server does not support anonymous access. TODO: this could be moved to another component to make anonymous access check global.
Functions ¶
func GetSubjectName ¶
GetSubjectName helps determining a human-readable name for a Subject. It returns the attribute stored under the key "name" (SubjectName), if any. Otherwise it returns Subject.ID.
A common use case for a friendly name is allowing an Authorizer to grant push access to a personal namespace.
Types ¶
type AccessToken ¶
AccessToken is a credential issued to a registry client described in the AccessToken Authentication Specification.
type AccessTokenIssuer ¶
type AccessTokenIssuer interface {
IssueAccessToken(ctx context.Context, service string, subject Subject, grantedScopes []Scope) (AccessToken, error)
}
AccessTokenIssuer issues a token described in the Token Authentication Specification.
type Authenticator ¶
type Authenticator struct { PasswordAuthenticator RefreshTokenAuthenticator }
Authenticator is a facade combining different type of authenticators.
type Authorizer ¶
type Authorizer interface {
Authorize(ctx context.Context, subject Subject, requestedScopes []Scope) ([]Scope, error)
}
Authorizer authorizes an access request to a list of resources (scopes) and returns the list of granted scopes.
type LoggerTokenService ¶
type LoggerTokenService struct { Service TokenService Logger *slog.Logger }
LoggerTokenService acts as a middleware for a TokenService and logs every request.
func (LoggerTokenService) OAuth2Handler ¶
func (s LoggerTokenService) OAuth2Handler(ctx context.Context, r OAuth2Request) (OAuth2Response, error)
OAuth2Handler implements TokenService and logs every request.
func (LoggerTokenService) TokenHandler ¶
func (s LoggerTokenService) TokenHandler(ctx context.Context, r TokenRequest) (TokenResponse, error)
TokenHandler implements TokenService and logs every request.
type OAuth2Request ¶
type OAuth2Request struct { GrantType string Service string ClientID string AccessType string Scopes Scopes Username string Password string RefreshToken string }
OAuth2Request implements the token request defined in the Docker Registry v2 OAuth2 authentication specification.
type OAuth2Response ¶
type OAuth2Response struct { Token string `json:"access_token"` Scope string `json:"scope,omitempty"` ExpiresIn int `json:"expires_in,omitempty"` IssuedAt string `json:"issued_at,omitempty"` RefreshToken string `json:"refresh_token,omitempty"` }
OAuth2Response implements the token response defined in the Docker Registry v2 OAuth2 authentication specification.
type PasswordAuthenticator ¶
type PasswordAuthenticator interface {
AuthenticatePassword(ctx context.Context, username string, password string) (Subject, error)
}
PasswordAuthenticator authenticates a subject using the "password" grant or basic auth.
It returns an ErrAuthenticationFailed error in case credentials are invalid.
type RefreshTokenAuthenticator ¶
type RefreshTokenAuthenticator interface {
AuthenticateRefreshToken(ctx context.Context, service string, refreshToken string) (Subject, error)
}
RefreshTokenAuthenticator authenticates a refresh token.
type RefreshTokenIssuer ¶
type RefreshTokenIssuer interface {
IssueRefreshToken(ctx context.Context, service string, subject Subject) (string, error)
}
RefreshTokenIssuer issues a token that a client can use to issue a new token for a subject without presenting credentials again. TODO: add service as a parameter.
type Resource ¶
type Resource struct { Type string `json:"type"` Class string `json:"class"` Name string `json:"name"` }
Resource describes a resource by type and name.
type Scope ¶
Scope describes an access request to a specific resource.
func ParseScope ¶
ParseScope parses a scope string into a formal structure according to the Token Scope documentation.
General scope format: resourceType[(resourceClass)]:resourceName:action[,action...]
ParseScope returns an error if the scope format is invalid.
func ParseScopes ¶
ParseScopes calls ParseScope for each scope in the list. If any of the scopes is invalid, ParseScopes returns an empty slice and an error.
type Subject ¶
type Subject interface { // ID returns the identifier of the Subject. ID() SubjectID // Attribute returns an attribute value and a boolean flag that shows whether the value exists or not. Attribute(key string) (string, bool) // Attributes are arbitrary key-value pairs that helps an Authorizer to make authorization decisions. // // Attributes MAY return a copy of it's internal map to avoid modifications. // As a result, it MAY be a relatively expensive operation and SHOULD only be used when necessary. // Prefer using Attribute instead. Attributes() map[string]string }
Subject contains information about the authenticated subject. For most (authorization) use cases, the information provided by Subject should be enough. However, custom implementations may provide additional behavior to help authorization decisions. That being said, it's up to the integrator to make sure all authenticators are compatible with such implementations.
type SubjectID ¶
type SubjectID string
SubjectID is the primary identifier of a Subject (a username or an arbitrary ID (eg. UUID)), but it is not necessarily globally unique: authenticators can federate between various providers and/or subject types (eg. human vs machine users). Therefore, SubjectID alone SHOULD NOT be used as a reference to the Subject if uniqueness cannot be guaranteed across the federated providers. The amount of information necessary to compose a key is an implementation/configuration detail, but the ID, the type of subject (if any) and the provider (if any) are generally enough to compose a globally (ie. across all providers) unique key.
SubjectID appears in the "sub" claim of JWTs issued as access tokens.
type TokenIssuer ¶
type TokenIssuer struct { AccessTokenIssuer RefreshTokenIssuer }
TokenIssuer is a facade combining different type of token issuers.
type TokenRequest ¶
type TokenRequest struct { Service string ClientID string Offline bool Scopes Scopes Anonymous bool Username string Password string }
TokenRequest implements the token request defined in the Docker Registry v2 authentication specification.
func (TokenRequest) Validate ¶
func (r TokenRequest) Validate() error
type TokenResponse ¶
type TokenResponse struct { Token string `json:"access_token"` RefreshToken string `json:"refresh_token,omitempty"` ExpiresIn int `json:"expires_in,omitempty"` }
TokenResponse implements the token response defined in the Docker Registry v2 authentication specification.
type TokenServer ¶
type TokenServer struct { Service TokenService Logger *slog.Logger }
TokenServer implements the Docker Registry v2 authentication specification.
func (TokenServer) OAuth2Handler ¶
func (s TokenServer) OAuth2Handler(w http.ResponseWriter, r *http.Request)
OAuth2Handler implements the Docker Registry v2 OAuth2 authentication specification.
func (TokenServer) TokenHandler ¶
func (s TokenServer) TokenHandler(w http.ResponseWriter, r *http.Request)
TokenHandler implements the Docker Registry v2 authentication specification.
type TokenService ¶
type TokenService interface { // TokenHandler implements the [Docker Registry v2 authentication] specification. // // [Docker Registry v2 authentication]: https://github.com/distribution/distribution/blob/main/docs/spec/auth/token.md TokenHandler(ctx context.Context, r TokenRequest) (TokenResponse, error) // OAuth2Handler implements the [Docker Registry v2 OAuth2 authentication] specification. // // [Docker Registry v2 OAuth2 authentication]: https://github.com/distribution/distribution/blob/main/docs/spec/auth/oauth.md OAuth2Handler(ctx context.Context, r OAuth2Request) (OAuth2Response, error) }
TokenService implements both the Docker Registry v2 authentication and the Docker Registry v2 OAuth2 authentication specification.
type TokenServiceImpl ¶
type TokenServiceImpl struct { Authenticator Authenticator Authorizer Authorizer TokenIssuer TokenIssuer }
TokenServer implements the Docker Registry v2 authentication specification.
func (TokenServiceImpl) OAuth2Handler ¶
func (s TokenServiceImpl) OAuth2Handler(ctx context.Context, r OAuth2Request) (OAuth2Response, error)
func (TokenServiceImpl) TokenHandler ¶
func (s TokenServiceImpl) TokenHandler(ctx context.Context, r TokenRequest) (TokenResponse, error)
TokenHandler implements the Docker Registry v2 authentication specification.