wwwauthenticate

package
v0.0.0-...-55f89e3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 16, 2025 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package wwwauthenticate provides tooling for creating and parsing WWW-Authenticate headers according to the RFC9110 and the extensions defined by the Bearer scheme in RFC6750.

Index

Constants

View Source
const TokenParameterName = ":TOKEN68:"

The value for the Token of this particular Authorization.

Using a delimiter for the name is a nice trick to avoid accidental parameter overwrites when parsing headers. It's impossible for an authentication parameter to have a delimiter in the key as per grammar defined in the "Field Value Components" section in RFC 7230.

Variables

View Source
var (
	ErrInvalidFormat = errors.New("invalid format")
)

Functions

func ParseChallenge

func ParseChallenge(input string, enc ...StringEncoder) error

ParseChallenge parses a single authentication challenge from the WWW-Authenticate header. It returns nil if if the WWW-Authenticate header is empty, ErrInvalidFormat if the parsing fails, or a single authentication Challenge.

You can either parse the error into a Challenge:

err := w3auth.ParseChallenge(`Bearer error="invalid_token", realm="simple", error_description="Something went wrong"`)
challengeErr := new(w3auth.Challenge)
errors.As(err, &challengeErr)

Or convert it to a specific challenge type:

err := w3auth.ParseChallenge(`Bearer error="invalid_token", realm="simple", error_description="Something went wrong"`)
bearerErr := new(w3auth.BearerError)
errors.As(err, &bearerErr)

func ParseChallenges

func ParseChallenges(input string, enc ...StringEncoder) error

ParseChallenges parses all challenges from the WWW-Authenticate header. It returns nil if if the WWW-Authenticate header is empty, ErrInvalidFormat if the parsing fails, or Challenges which is a list of authentication challenges.

You can parse the error back into a Challenges:

err := w3auth.ParseChallenges(`Bearer error="invalid_token", realm="simple", error_description="Something went wrong"`)
challengesErr := new(w3auth.Challenges)
errors.As(err, &challengesErr)

Or convert it to a specific challenge type which will match on the first error of the desired type (and return `false` otherwise):

err := w3auth.ParseChallenges(`Bearer error="invalid_token", realm="simple", error_description="Something went wrong"`)
bearerErr := new(w3auth.BearerError)
errors.As(err, &bearerErr)

Types

type BearerError

type BearerError struct {
	// Error provides the client with the reason why the access request was declined.
	Reason BearerErrorType

	// ErrorURI attribute is an absolute URI identifying a human-readable web page
	// explaining the error.
	ErrorURI *string

	// ErrorDescription attribute provides developers with a human-readable
	// explanation of the error that is not meant to be displayed to end-users.
	ErrorDescription *string

	// Realm  attribute MAY be included to indicate the scope of
	// protection in the manner described in HTTP/1.1 [RFC2617].  The
	// "realm" attribute MUST NOT appear more than once.
	//
	// [RFC2617]: https://datatracker.ietf.org/doc/html/rfc2617
	Realm *string

	// Scope attribute is defined in Section 3.3 of [RFC6749]. The
	// "scope" attribute is a space-delimited list of case-sensitive scope
	// values indicating the required scope of the access token for
	// accessing the requested resource. "scope" values are implementation
	// defined; there is no centralized registry for them; allowed values
	// are defined by the authorization server.  The order of "scope" values
	// is not significant.  In some cases, the "scope" value will be used
	// when requesting a new access token with sufficient scope of access to
	// utilize the protected resource.  Use of the "scope" attribute is
	// OPTIONAL.  The "scope" attribute MUST NOT appear more than once.  The
	// "scope" value is intended for programmatic use and is not meant to be
	// displayed to end-users.
	//
	// If the protected resource request included an access token and failed
	// authentication, the resource server SHOULD include the "error"
	// attribute to provide the client with the reason why the access
	// request was declined.  The parameter value is described in
	// Section 3.1.  In addition, the resource server MAY include the
	// "error_description" attribute to provide developers a human-readable
	// explanation that is not meant to be displayed to end-users.  It also
	// MAY include the "error_uri" attribute with an absolute URI
	// identifying a human-readable web page explaining the error.  The
	// "error", "error_description", and "error_uri" attributes MUST NOT
	// appear more than once.
	//
	// Values for the "scope" attribute (specified in Appendix A.4 of
	// [RFC6749]) MUST NOT include characters outside the set %x21 / %x23-5B
	// / %x5D-7E for representing scope values and %x20 for delimiters
	// between scope values.  Values for the "error" and "error_description"
	// attributes (specified in Appendixes A.7 and A.8 of [RFC6749]) MUST
	// NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
	// Values for the "error_uri" attribute (specified in Appendix A.9 of
	// [RFC6749]) MUST conform to the URI-reference syntax and thus MUST NOT
	// include characters outside the set %x21 / %x23-5B / %x5D-7E.
	//
	// [RFC6749]: https://datatracker.ietf.org/doc/html/rfc6749
	Scope []string

	// ACRValues is a space-separated string listing the authentication context class reference
	// values in order of preference. The protected resource requires one of these
	// values for the authentication event associated with the access token. As defined
	// in Section 1.2 of [OIDC], the authentication context conveys information about
	// how authentication takes place (e.g., what authentication method(s) or assurance
	// level to meet).
	//
	// [OIDC]: https://openid.net/specs/openid-connect-core-1_0.html
	ACRValues *string

	// MaxAge value indicates the allowable elapsed time since the last active
	// authentication event associated with the access token. An active authentication
	// event entails a user interacting with the authorization server in response to an
	// authentication prompt. Note that, while the auth-param value can be conveyed as
	// a token or quoted-string (see Section 11.2 of [RFC9110]), it has to represent a
	// non-negative integer.
	//
	// [RFC9110]: https://www.rfc-editor.org/info/rfc9110
	MaxAge *time.Duration

	// AuthorizationDetails specifies the authorization requirements for a certain type of resource.
	// The type of resource or access requirement is determined by the type field of
	// the [rar.AuthorizationDetail].
	//
	// [RFC9396]: https://datatracker.ietf.org/doc/html/rfc9396
	AuthorizationDetails []rar.AuthorizationDetail
}

func ErrInsufficientUserAuthentication

func ErrInsufficientUserAuthentication(description string) *BearerError

ErrInsufficientUserAuthentication is WWWAuthenticate error for when the user is authenticated but the authentication doesn't meet the required level of authentication.

func (*BearerError) Error

func (be *BearerError) Error() string

func (*BearerError) String

func (be *BearerError) String(enc ...StringEncoder) string

String returns the string representation of the BearerError that can be used in the WWW-Authenticate header.

func (*BearerError) Unwrap

func (be *BearerError) Unwrap() error

func (*BearerError) WithACRValues

func (be *BearerError) WithACRValues(acr string) *BearerError

WithACRValues sets the `acr_values`.

func (*BearerError) WithAuthorizationDetails

func (be *BearerError) WithAuthorizationDetails(authorizationDetails []rar.AuthorizationDetail) *BearerError

WithAuthorizationDetails sets the `authorization_details`.

func (*BearerError) WithMaxAge

func (be *BearerError) WithMaxAge(d time.Duration) *BearerError

WithMaxAge sets the `max_age`.

func (*BearerError) WithScope

func (be *BearerError) WithScope(scope []string) *BearerError

WithScope sets the `scope`.

type BearerErrorType

type BearerErrorType string

BearerErrorType is a type of the Bearer authentication error as defined in section 3.1 of The OAuth 2.0 Authorization Framework RFC6750 and further extended by OAuth 2.0 Step Up Authentication Challenge Protocol RFC9470.

const (
	// The request is missing a required parameter, includes an
	// unsupported parameter or parameter value, repeats the same
	// parameter, uses more than one method for including an access
	// token, or is otherwise malformed.  The resource server SHOULD
	// respond with the HTTP 400 (Bad Request) status code.
	InvalidRequestError BearerErrorType = "invalid_request"

	// The access token provided is expired, revoked, malformed, or
	// invalid for other reasons.  The resource SHOULD respond with
	// the HTTP 401 (Unauthorized) status code.  The client MAY
	// request a new access token and retry the protected resource
	// request.
	InvalidTokenError BearerErrorType = "invalid_token"

	// The request requires higher privileges than provided by the
	// access token.  The resource server SHOULD respond with the HTTP
	// 403 (Forbidden) status code and MAY include the "scope"
	// attribute with the scope necessary to access the protected
	// resource.
	InsufficientScopeError BearerErrorType = "insufficient_scope"

	// The authentication event associated with the access token
	// presented with the request does not meet the authentication
	// requirements of the protected resource.
	InsufficientUserAuthenticationError BearerErrorType = "insufficient_user_authentication"
)

The [BearerError.Reason] is one of these errors.

type Challenge

type Challenge struct {
	Scheme string
	Fields map[string]string
}

Challenge is returned with 401 (Unauthorized) status code to inform the client about the authentication methods usable to access the resource.

func (*Challenge) As

func (ch *Challenge) As(target any) bool

func (Challenge) Error

func (wa Challenge) Error() string

func (Challenge) String

func (wa Challenge) String(enc ...StringEncoder) string

String converts the WWWAuthenticate data into properly formatted header value for the WWW-Authenticate header.

type Challenges

type Challenges []error

func (*Challenges) As

func (ch *Challenges) As(target any) bool

func (Challenges) Error

func (ch Challenges) Error() string

func (Challenges) String

func (ch Challenges) String() string

type StringEncoder

type StringEncoder interface {
	// contains filtered or unexported methods
}

func WithQueryEncoding

func WithQueryEncoding() StringEncoder

WithQueryEncoding encodes WWW-Authenticate param values using URL query escaping. This is a non-standard format but needed for backwards compatibility.

NOTE: WithQueryEncoding internally uses url.PathEscape and url.PathUnescape to ensure that spaces are percent-encoded instead of converted to `+` which introduces ambiguity and isn't handled the same way by e.g. swift or javascript.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL