Loading...
Searching...
No Matches
HttpServer::AbstractAuthenticator Class Reference

abstract base class for external authentication More...

Inheritance diagram for HttpServer::AbstractAuthenticator:
[legend]

## Public Member Functions

| authenticate (string user, string pass='')
| called to authenticate a user for a connection
| 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 repsonse 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

## Detailed Description

abstract base class for external authentication

This class should be inherited by a class providing real authentication

## Member Function Documentation

## authenticate()

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)

## authenticateByIP()

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 (however this base class method as implemented here will never throw any exceptions

## 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; this hash will have the following keys:
  - `header-info`: a hash of information about the request header with the following keys:
    - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
    - `accept-encoding`: a hash where keys are values from any `"Accept-Encoding"` header and the values are True
    - `body-content-type`: this is the `"Content-Type"` header without any charset declaration
    - `charset:` if there is a charset declaration in the `"Content-Type"` header, the value is returned in this key
    - `client-cert`: if the server is configured to capture remote client certificates, and the client supplied a certificate, this key will be populated with the SSLCertificate for the client
    - `close:` set to True if the connection should be closed after responding, False if not (as derived from the request header)
    - `headers-raw`: a hash of raw request headers without any case conversions or other processing
    - `request-uri`: gives the request URI in an HTTP request
  - `socket:` the bind address used to bind the listener (`"socket-info"` provides more detailed information)
  - `socket-info`: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo())
  - `peer-info`: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo())
  - `url:` a hash of broken-down URL information (as returned from Qore::parse_url())
  - `id:` the unique HTTP connection ID
  - `ssl:` True if the request was encrypted with HTTPS, False if not
  - `listener-id`: the HTTP server listener ID (see HttpServer::getListenerInfo())
  - `user:` the current RBAC username (if any)
  - `root_path:` the root URL path matched if the request was matched by a URL prefix

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

## do401()

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

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

Parameters

  msg | message body to return
  cx | the call context

## 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

## 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)