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
- Variables
- func ParseChallenge(input string, enc ...StringEncoder) error
- func ParseChallenges(input string, enc ...StringEncoder) error
- type BearerError
- func (be *BearerError) Error() string
- func (be *BearerError) String(enc ...StringEncoder) string
- func (be *BearerError) Unwrap() error
- func (be *BearerError) WithACRValues(acr string) *BearerError
- func (be *BearerError) WithAuthorizationDetails(authorizationDetails []rar.AuthorizationDetail) *BearerError
- func (be *BearerError) WithMaxAge(d time.Duration) *BearerError
- func (be *BearerError) WithScope(scope []string) *BearerError
- type BearerErrorType
- type Challenge
- type Challenges
- type StringEncoder
Constants ¶
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 ¶
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 ¶
Challenge is returned with 401 (Unauthorized) status code to inform the client about the authentication methods usable to access the resource.
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.