Documentation
¶
Overview ¶
Package authhttp provides strict HTTP credential extraction, challenges, and authentication-only middleware for net/http.
Index ¶
- func FormatChallenge(challenge authentication.Challenge) (string, error)
- func NewMiddleware(extractor CredentialExtractor, authenticator authentication.Authenticator, ...) (func(http.Handler) http.Handler, error)
- type APIKeyOption
- type BearerOption
- type CredentialExtractor
- type Extractor
- type MiddlewareOption
- type Source
- func APIKeyCookie(idCookie, keyCookie string, options ...APIKeyOption) Source
- func APIKeyHeader(idHeader, keyHeader string, options ...APIKeyOption) Source
- func APIKeyQuery(idParameter, keyParameter string, options ...APIKeyOption) Sourcedeprecated
- func BasicAuthorization() Source
- func BearerAuthorization(options ...BearerOption) Source
- func BearerCookie(name string, options ...BearerOption) Source
- func BearerQuery(name string, options ...BearerOption) Sourcedeprecated
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatChallenge ¶
func FormatChallenge(challenge authentication.Challenge) (string, error)
FormatChallenge serializes a challenge for a WWW-Authenticate field value.
func NewMiddleware ¶
func NewMiddleware(extractor CredentialExtractor, authenticator authentication.Authenticator, options ...MiddlewareOption) (func(http.Handler) http.Handler, error)
NewMiddleware creates fail-closed authentication-only net/http middleware.
Example ¶
package main
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
authentication "github.com/faustbrian/go-authentication"
"github.com/faustbrian/go-authentication/authhttp"
"github.com/faustbrian/go-authentication/bearer"
)
func main() {
extractor, _ := authhttp.NewExtractor(authhttp.BearerAuthorization())
authenticator, _ := bearer.New(bearer.ValidatorFunc(
func(_ context.Context, _ string) (authentication.Principal, error) {
return authentication.NewPrincipal(authentication.PrincipalSpec{
Subject: "service", Method: "bearer",
})
},
))
middleware, _ := authhttp.NewMiddleware(extractor, authenticator)
handler := middleware(http.HandlerFunc(func(_ http.ResponseWriter, request *http.Request) {
principal, _ := authentication.PrincipalFromContext(request.Context())
fmt.Println(principal.Subject())
}))
request := httptest.NewRequest(http.MethodGet, "/", nil)
request.Header.Set("Authorization", "Bearer token")
handler.ServeHTTP(httptest.NewRecorder(), request)
}
Output: service
Types ¶
type APIKeyOption ¶
type APIKeyOption func(*apiKeySource)
APIKeyOption configures an API-key source.
func WithAPIKeyMaxBytes ¶
func WithAPIKeyMaxBytes(maximum int) APIKeyOption
WithAPIKeyMaxBytes sets the inclusive API-key size bound.
type BearerOption ¶
type BearerOption func(*authorizationSource)
BearerOption configures a bearer source.
func WithBearerMaxBytes ¶
func WithBearerMaxBytes(maximum int) BearerOption
WithBearerMaxBytes sets the inclusive bearer-token size bound.
func WithBearerPipe ¶
func WithBearerPipe() BearerOption
WithBearerPipe permits the pipe character in an opaque bearer credential.
RFC 6750 bearer syntax rejects pipes by default. Enable this option only for an existing credential contract that uses a pipe-delimited opaque token.
type CredentialExtractor ¶
type CredentialExtractor interface {
Extract(*http.Request) (authentication.Credential, error)
}
CredentialExtractor extracts one typed credential from an HTTP request.
type Extractor ¶
type Extractor struct {
// contains filtered or unexported fields
}
Extractor rejects ambiguous credentials across all enabled sources.
func NewExtractor ¶
NewExtractor creates an extractor from one or more explicit sources.
func (*Extractor) Extract ¶
func (e *Extractor) Extract(request *http.Request) (authentication.Credential, error)
Extract returns exactly one credential or a classified failure.
type MiddlewareOption ¶
type MiddlewareOption func(*middlewareConfig) error
MiddlewareOption configures HTTP authentication middleware.
func WithChallenges ¶
func WithChallenges(challenges ...authentication.Challenge) MiddlewareOption
WithChallenges configures fallback challenges for authentication failures.
func WithOptionalAnonymous ¶
func WithOptionalAnonymous() MiddlewareOption
WithOptionalAnonymous permits anonymous access only when credentials are absent.
Example ¶
package main
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
authentication "github.com/faustbrian/go-authentication"
"github.com/faustbrian/go-authentication/authhttp"
"github.com/faustbrian/go-authentication/bearer"
)
func main() {
extractor, _ := authhttp.NewExtractor(authhttp.BearerAuthorization())
authenticator, _ := bearer.New(bearer.ValidatorFunc(
func(context.Context, string) (authentication.Principal, error) {
return authentication.Principal{}, authentication.NewFailure(authentication.FailureRejected)
},
))
middleware, _ := authhttp.NewMiddleware(extractor, authenticator, authhttp.WithOptionalAnonymous())
handler := middleware(http.HandlerFunc(func(_ http.ResponseWriter, request *http.Request) {
principal, found := authentication.PrincipalFromContext(request.Context())
fmt.Println(found, principal.IsAnonymous())
}))
handler.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/", nil))
}
Output: true true
type Source ¶
type Source interface {
// contains filtered or unexported methods
}
Source is an explicitly enabled HTTP credential location.
func APIKeyCookie ¶
func APIKeyCookie(idCookie, keyCookie string, options ...APIKeyOption) Source
APIKeyCookie explicitly enables API-key extraction from two cookies.
func APIKeyHeader ¶
func APIKeyHeader(idHeader, keyHeader string, options ...APIKeyOption) Source
APIKeyHeader explicitly enables API-key extraction from two headers.
func APIKeyQuery
deprecated
func APIKeyQuery(idParameter, keyParameter string, options ...APIKeyOption) Source
APIKeyQuery explicitly enables API-key extraction from two query parameters.
Deprecated: credentials in URLs can be retained by logs, proxies, and browser history. Prefer APIKeyHeader for new designs.
func BasicAuthorization ¶
func BasicAuthorization() Source
BasicAuthorization enables Basic extraction from the Authorization header.
func BearerAuthorization ¶
func BearerAuthorization(options ...BearerOption) Source
BearerAuthorization enables bearer extraction from the Authorization header.
func BearerCookie ¶
func BearerCookie(name string, options ...BearerOption) Source
BearerCookie explicitly enables bearer extraction from a cookie.
func BearerQuery
deprecated
func BearerQuery(name string, options ...BearerOption) Source
BearerQuery explicitly enables bearer extraction from a query parameter.
Deprecated: credentials in URLs can be retained by logs, proxies, and browser history. Prefer BearerAuthorization for new designs.
Source Files