HttpServer::AbstractAuthenticator Class Reference

abstract base class for external authentication More...

#include <HttpServerUtil.qm.dox.h>

Inheritance diagram for HttpServer::AbstractAuthenticator:

Public Member Methods
	authenticate (reference< hash< auto > > cx, string user, string pass='')
	called to authenticate a user for a connection
deprecated	authenticate (string user, string pass='')
	called to authenticate a user for a connection
	authenticateByIP (reference< hash< auto > > cx, string ip, reference< bool > authenticated)
	Called to try to authenticate the connection based on the source IP address.
deprecated	authenticateByIP (string ip, reference< string > user)
	called when the connection requires authentication, but no authentication credentials were supplied, to try to authenticate the connection based on the source IP address
*hash< HttpResponseInfo >	authenticateRequest (HttpListenerInterface listener, hash< auto > hdr, reference< hash< auto > > cx)
	Primary method called to authenticate each request.
hash< HttpResponseInfo >	do401 (string msg='Authentication is required to access this server', *hash< auto > cx)
	returns a 401 response with the given string argument as the message body
	endRequest ()
	Called after a request has been handled to allow the authenticator to remove any thread-local auth information.
hash< auto >	getAuthHeader ()
	returns a hash with one item - WWW-Authenticate header set to correct realm
hash< auto >	getAuthHeader (hash< auto > cx)
	returns a hash with one item - WWW-Authenticate header set to correct realm
string	getRealm ()
	returns the authentication realm as a string
bool	requiresAuthentication ()
	called to check if the connection requires authentication

Private Member Methods
*hash< HttpResponseInfo >	authenticateRequestIntern (HttpListenerInterface listener, hash< auto > hdr, reference< hash< auto > > cx, reference< bool > authenticated)
	Primary method called to authenticate each request.

Detailed Description

abstract base class for external authentication

This class should be inherited by a class providing real authentication

Member Function Documentation

authenticate() [1/2]

HttpServer::AbstractAuthenticator::authenticate	(	reference< hash< auto > >	cx,
		string	user,
		string	pass = ''
	)

called to authenticate a user for a connection

This method will only be called if requiresAuthentication() returns True

Parameters

cx	a reference to the call context hash; set the "user" key to the user name if a user was identified and authorized; see HttpServerUtil Request Context for information about this value
user	the username to authenticate
pass	the password for the user

Exceptions

AUTHENTICATION-ERROR

subclasses should throw this exception if the user cannot be authenticated (must be overridden in child classes; this parent method will never throw any exceptions; all connections are accepted by default)

authenticate() [2/2]

deprecated HttpServer::AbstractAuthenticator::authenticate	(	string	user,
		string	pass = ''
	)

called to authenticate a user for a connection

This method will only be called if requiresAuthentication() returns True

Parameters

user	the username to authenticate
pass	the password for the user

Exceptions

AUTHENTICATION-ERROR

subclasses should throw this exception if the user cannot be authenticated (must be overridden in child classes; this parent method will never throw any exceptions; all connections are accepted by default)

Note

Do not use this method; use authenticate(reference<hash<auto>> cx, string user, string pass) instead

authenticateByIP() [1/2]

HttpServer::AbstractAuthenticator::authenticateByIP	(	reference< hash< auto > >	cx,
		string	ip,
		reference< bool >	authenticated
	)

Called to try to authenticate the connection based on the source IP address.

This method will only be called if requiresAuthentication() returns True and no authentication credentials are supplied with the request

Parameters

cx	a reference to the call context hash; set the "user" key to the user name if a user was identified and authorized; see HttpServerUtil Request Context for information about this value request can be authenticated based on the source IP address
ip	the IP address of the source connection
authenticated	set to True if the connection was authenticated based on the source IP address

authenticateByIP() [2/2]

deprecated HttpServer::AbstractAuthenticator::authenticateByIP	(	string	ip,
		reference< string >	user
	)

called when the connection requires authentication, but no authentication credentials were supplied, to try to authenticate the connection based on the source IP address

This method will only be called if requiresAuthentication() returns True and no authentication credentials are supplied with the request

Parameters

ip	the IP address of the source connection
user	a reference to a string that will be populated with the username to use if the request can be authenticated based on the source IP address (this method returns the string "admin")

Exceptions

AUTHENTICATION-ERROR

subclasses should throw this exception if the user cannot be authenticated

Note

Do not use this method; use authenticateByIP(reference<hash<auto>> cx, reference<string> ip) instead

authenticateRequest()

*hash< HttpResponseInfo > HttpServer::AbstractAuthenticator::authenticateRequest	(	HttpListenerInterface	listener,
		hash< auto >	hdr,
		reference< hash< auto > >	cx
	)

Primary method called to authenticate each request.

Parameters

listener	an HttpListenerInterface object for the listener serving the request for logging purposes
hdr	a hash of request headers
cx	a reference to the call context hash; set the "user" key to the user name if a user was identified and authorized; see HttpServerUtil Request Context for information about this value

Returns

returns NOTHING if there were no errors, otherwise returns a hash with the following keys to indicate an authentication or authorization error:

• "code": the HTTP response code
• "body": the error message body
• "hdr": an optional hash of headers for the error response

authenticateRequestIntern()

*hash< HttpResponseInfo > HttpServer::AbstractAuthenticator::authenticateRequestIntern ( HttpListenerInterface  listener, hash< auto >  hdr, reference< hash< auto > >  cx, reference< bool >  authenticated  )

private

Primary method called to authenticate each request.

Parameters

listener	an HttpListenerInterface object for the listener serving the request for logging purposes
hdr	a hash of request headers
cx	a reference to the call context hash; set the "user" key to the user name if a user was identified and authorized; see HttpServerUtil Request Context for information about this value
authenticated	set to True if the request was authenticated; this output value is ignored if the method returns a response info hash

Returns

returns NOTHING if there were no errors, otherwise a hash can be returned which will be sent to the requester as the response

do401()

hash< HttpResponseInfo > HttpServer::AbstractAuthenticator::do401	(	string	msg = 'Authentication is required to access this server',
		*hash< auto >	cx
	)

returns a 401 response with the given string argument as the message body

Parameters

msg	message body to return
cx	the call context hash; see HttpServerUtil Request Context for information about this value

endRequest()

HttpServer::AbstractAuthenticator::endRequest

(

)

Called after a request has been handled to allow the authenticator to remove any thread-local auth information.

The base class method does nothing

Since

HttpServerUtil 1.2

getAuthHeader() [1/2]

hash< auto > HttpServer::AbstractAuthenticator::getAuthHeader

(

)

returns a hash with one item - WWW-Authenticate header set to correct realm

Note

This version is never called by Qore; it is provided only for backwards compatibility

getAuthHeader() [2/2]

hash< auto > HttpServer::AbstractAuthenticator::getAuthHeader

(

hash< auto >

cx

)

returns a hash with one item - WWW-Authenticate header set to correct realm

Parameters

cx	the call context hash; see HttpServerUtil Request Context for information about this value

getRealm()

string HttpServer::AbstractAuthenticator::getRealm

(

)

returns the authentication realm as a string

Returns

the authentication realm as a string (default: "Default Authentication Realm")

requiresAuthentication()

bool HttpServer::AbstractAuthenticator::requiresAuthentication

(

)

called to check if the connection requires authentication

Returns

True if authentication is enabled, False if not (False is the default value returned)