xentara::security::HttpAuthenticator Class Reference

An authenticator for authenticating HTTP requests. More...

#include <xentara/security/HttpAuthenticator.hpp>

Public Member Functions
HTTP Authentication
auto	authenticate (const HttpConfig &config, std::string_view authorizationHeader) const -> utils::eh::expected< Authorization, std::error_code >
	Authenticate an HTTP request.
auto	authenticate (const HttpConfig &config, std::string_view authorizationHeaderValue, NoFieldNameTag tag) const -> utils::eh::expected< Authorization, std::error_code >
	Authenticate an HTTP request using only the header field value.
auto	wwwAuthenticateHeader (const HttpConfig &config, std::error_code error=Error::AccessDenied) const -> std::optional< std::string >
	Gets the “WWW-Authenticate” header that should be be used in HTTP responses.
auto	wwwAuthenticateHeader (const HttpConfig &config, std::error_code error, NoFieldNameTag tag) const -> std::optional< std::string >
	Gets the value for the “WWW-Authenticate” header that should be be used in HTTP responses.
auto	wwwAuthenticateHeader (const HttpConfig &config, NoFieldNameTag tag) const -> std::optional< std::string >
	Gets the value for the “WWW-Authenticate” header that should be be used in HTTP responses if access is denied.
CORS (Cross-Origin Resource Sharing)
auto	checkOrigin (const HttpConfig &config, std::string_view originHeader) const -> utils::eh::expected< std::string, std::error_code >
	Checks whether the origin of an HTTP request is allowed.
auto	checkOrigin (const HttpConfig &config, std::string_view originHeaderValue, NoFieldNameTag tag) const -> utils::eh::expected< std::string, std::error_code >
	Checks whether the origin of an HTTP request is allowed using only the header field value.

Private Member Functions
virtual auto	doAuthenticate (const HttpConfig &config, std::string_view authorizationHeader, bool includesFieldName) const -> utils::eh::expected< Authorization, std::error_code >=0
	Authenticate an HTTP request.
virtual auto	doGetWwwAuthenticateHeader (const HttpConfig &config, std::error_code error, bool includeFieldName) const -> std::optional< std::string >=0
	Gets the “WWW-Authenticate” header that should be be used in HTTP responses.
virtual auto	doCheckOrigin (const HttpConfig &config, std::string_view originHeader, bool includesFieldName) const -> utils::eh::expected< std::string, std::error_code >=0
	Checks the origin.

Related Symbols
(Note that these are not member symbols.)
constexpr NoFieldNameTag	kNoFieldName
	A marker used to select overloads of HttpAuthenticator that to not include the header field name.

Detailed Description

An authenticator for authenticating HTTP requests.

Member Function Documentation

authenticate() [1/2]

auto xentara::security::HttpAuthenticator::authenticate	(	const HttpConfig &	config,
		std::string_view	authorizationHeader
	)		const -> utils::eh::expected< Authorization, std::error_code >

Authenticate an HTTP request.

The client should ensure that exactly one “Authorization” header is present in an HTTP request. If no “Authorization” header is present, or if more than one “Authorization” header is present, then a response based on the error codes Error::MissingAuthorizationHeader and Error::DuplicateAuthorizationHeader, respectively, should be returned. You can use httpResponseCode() and wwwAuthenticateHeader() to get the appropriate HTTP response code and “WWW-Authenticate” header for the response.

Parameters

config	The configuration to use.
authorizationHeader	The “Authorization” header of the HTTP request. The string view must include the whole header field, including the field name, e.g. “Authorization: Bearer Q29uZ3JhdHVsYXRpb25zLCB5b3UgYXJlIGEgbmVyZC4”.

Returns

Returns an authorization object, or an error code on error. If an error is returned, You can use [httpResponseCode()](httpResponseCode(std::error_code)) and wwwAuthenticateHeader() to get the appropriate HTTP response code and “WWW-Authenticate” header for the response.

authenticate() [2/2]

auto xentara::security::HttpAuthenticator::authenticate	(	const HttpConfig &	config,
		std::string_view	authorizationHeaderValue,
		NoFieldNameTag	tag
	)		const -> utils::eh::expected< Authorization, std::error_code >

Authenticate an HTTP request using only the header field value.

The client should ensure that exactly one “Authorization” header is present in an HTTP request. If no “Authorization” header is present, or if more than one “Authorization” header is present, then a response based on the error codes Error::MissingAuthorizationHeader and Error::DuplicateAuthorizationHeader, respectively, should be returned. You can use httpResponseCode() and wwwAuthenticateHeader() to get the appropriate HTTP response code and “WWW-Authenticate” header for the response.

Parameters

config	The configuration to use.
authorizationHeaderValue	The value of the “Authorization” header of the HTTP request. The string view must not include the header field name or the separating colon, only the field value starting with the authentication scheme, e.g. “Bearer Q29uZ3JhdHVsYXRpb25zLCB5b3UgYXJlIGEgbmVyZC4”. The authorization header value is allowed to contain leading whitespace before the scheme name.
tag	Always pass kNoFieldName as this parameter

Returns

Returns an authorization object, or an error code on error. If an error is returned, You can use [httpResponseCode()](httpResponseCode(std::error_code)) and wwwAuthenticateHeader() to get the appropriate HTTP response code and “WWW-Authenticate” header for the response.

checkOrigin() [1/2]

auto xentara::security::HttpAuthenticator::checkOrigin	(	const HttpConfig &	config,
		std::string_view	originHeader
	)		const -> utils::eh::expected< std::string, std::error_code >

Checks whether the origin of an HTTP request is allowed.

If no “Origin” header is present in an HTTP request, then CORS is not being used, and the request should be allowed without calling this function.

The client should ensure that not more than one “Origin” header is present in an HTTP request. If more than one “Origin” header is present, then a response based on the error code Error::DuplicateOriginHeader should be returned. You can use httpResponseCode() to get the appropriate HTTP response code for the response.

If the origin is not allowed, this function returns the error Error::OriginNotAllowed. Normally, the response the request should have the response code “403 Forbidden”. When processing an “OPTION” requests, however, an unknown origin should result in an Ok response that does not contain an “Access-Control-Allow-Origin” header. When processing an “OPTION” request, you can compare the return value of this function to Error::OriginNotAllowed to determine whether an error or an Ok response should be returned:

bool sendErrorResonse = (returnValue != utils::eh::unexpected { Error::OriginNotAllowed });

or:

if (!returnValue)
{
    bool sendErrorResonse = (returnValue.error() != Error::OriginNotAllowed);
}

Parameters

config	The configuration to use.
originHeader	The “Origin” header of the HTTP request. The string view must include the whole header field, including the field name, e.g. “Origin: https://ipc1.local”.

Returns

Returns the correct content for the “Access-Control-Allow-Origin” header of the response, or an error code on error. If an error is returned, You can use httpResponseCode() to get the appropriate HTTP response code for the response.

If the origin is not allowed, then the error code Error::OriginNotAllowed is returned. You can check for this error when processing “OPTION” requests to determine whether to respond with an error or not.

checkOrigin() [2/2]

auto xentara::security::HttpAuthenticator::checkOrigin	(	const HttpConfig &	config,
		std::string_view	originHeaderValue,
		NoFieldNameTag	tag
	)		const -> utils::eh::expected< std::string, std::error_code >

Checks whether the origin of an HTTP request is allowed using only the header field value.

If no “Origin” header is present in an HTTP request, then CORS is not being used, and the request should be allowed without calling this function.

The client should ensure that not more than one “Origin” header is present in an HTTP request. If more than one “Origin” header is present, then a response based on the error code Error::DuplicateOriginHeader should be returned. You can use httpResponseCode() to get the appropriate HTTP response code for the response.

If the origin is not allowed, this function returns the error Error::OriginNotAllowed. Normally, the response the request should have the response code “403 Forbidden”. When processing an “OPTION” requests, however, an unknown origin should result in an Ok response that does not contain an “Access-Control-Allow-Origin” header. When processing an “OPTION” request, you can compare the return value of this function to Error::OriginNotAllowed to determine whether an error or an Ok response should be returned:

bool sendErrorResonse = (returnValue != utils::eh::unexpected { Error::OriginNotAllowed });

or:

if (!returnValue)
{
    bool sendErrorResonse = (returnValue.error() != Error::OriginNotAllowed);
}

Parameters

config	The configuration to use.
originHeaderValue	The value of the “Origin” header of the HTTP request. The string view must not include the header field name or the separating colon, only the field value containing the origin, e.g. “https://ipc1.local”. The origin header value is allowed to contain leading whitespace before the origin list.
tag	Always pass kNoFieldName as this parameter

Returns

Returns the correct content for the “Access-Control-Allow-Origin” header of the response, or an error code on error. If an error is returned, You can use httpResponseCode() to get the appropriate HTTP response code for the response.

If the origin is not allowed, then the error code Error::OriginNotAllowed is returned. You can check for this error when processing “OPTION” requests to determine whether to respond with an error or not.

doAuthenticate()

virtual auto xentara::security::HttpAuthenticator::doAuthenticate ( const HttpConfig &  config, std::string_view  authorizationHeader, bool  includesFieldName  ) const -> utils::eh::expected< Authorization, std::error_code >

privatepure virtual

Authenticate an HTTP request.

doCheckOrigin()

virtual auto xentara::security::HttpAuthenticator::doCheckOrigin ( const HttpConfig &  config, std::string_view  originHeader, bool  includesFieldName  ) const -> utils::eh::expected< std::string, std::error_code >

privatepure virtual

Checks the origin.

doGetWwwAuthenticateHeader()

virtual auto xentara::security::HttpAuthenticator::doGetWwwAuthenticateHeader ( const HttpConfig &  config, std::error_code  error, bool  includeFieldName  ) const -> std::optional< std::string >

privatepure virtual

Gets the “WWW-Authenticate” header that should be be used in HTTP responses.

wwwAuthenticateHeader() [1/3]

auto xentara::security::HttpAuthenticator::wwwAuthenticateHeader	(	const HttpConfig &	config,
		NoFieldNameTag	tag
	)		const -> std::optional<std::string>

Gets the value for the “WWW-Authenticate” header that should be be used in HTTP responses if access is denied.

This is a convenience function that simple calls [wwwAuthenticateHeader(config, Error::AccessDenied, kNoFieldName)](wwwAuthenticateHeader(const HttpConfig &, std::error_code, NoFieldNameTag) const).

Parameters

config	The configuration to use.
tag	Always pass kNoFieldName as this parameter

Returns

Returns the value of the “WWW-Authenticate” header to be returned in the HTTP response. The returned string does not include the header field name or the separating colon, only the field value starting with the authentication scheme, e.g. “Bearer realm="Xentara", error="insufficient_scope"”. If no “WWW-Authenticate” header should be included with the response, std::nullopt is returned.

wwwAuthenticateHeader() [2/3]

auto xentara::security::HttpAuthenticator::wwwAuthenticateHeader	(	const HttpConfig &	config,
		std::error_code	error,
		NoFieldNameTag	tag
	)		const -> std::optional< std::string >

Gets the value for the “WWW-Authenticate” header that should be be used in HTTP responses.

Parameters

config	The configuration to use.
error	The error code. This should be either the error code returned by authenticate(), or Error::AccessDenied if the response is sent as a result of a failed call to a checkAccess() function.
tag	Always pass kNoFieldName as this parameter

Returns

Returns the value of the “WWW-Authenticate” header to be returned in the HTTP response. The returned string does not include the header field name or the separating colon, only the field value starting with the authentication scheme, e.g. “Bearer realm="Xentara"”. If no “WWW-Authenticate” header should be included with the response, std::nullopt is returned.

wwwAuthenticateHeader() [3/3]

auto xentara::security::HttpAuthenticator::wwwAuthenticateHeader	(	const HttpConfig &	config,
		std::error_code	error = Error::AccessDenied
	)		const -> std::optional< std::string >

Gets the “WWW-Authenticate” header that should be be used in HTTP responses.

Parameters

config	The configuration to use.
error	The error code. This should be either the error code returned by authenticate(), or Error::AccessDenied if the response is sent as a result of a failed call to a checkAccess() function.

Returns

Returns the full “WWW-Authenticate” header to be returned in the HTTP response. The returned string includes the header field name, and the separating colon, e.g. “WWW-Authenticate: Bearer realm="Xentara"”. If no “WWW-Authenticate” header should be included with the response, std::nullopt is returned.

Friends And Related Symbol Documentation

kNoFieldName

constexpr NoFieldNameTag kNoFieldName

related

A marker used to select overloads of HttpAuthenticator that to not include the header field name.