External Authentication Framework

In the Authentication Handleryou can enable an external authentication service. If you want to use external authentication, you can optionally modify the supplied generic service. The following sections provide the necessary information to do so.

Protocol used for communication between the external authentication server and the decider

If you want to replace the authentication service, you need to understand the protocol that’s used for communication between the vWAF decider and the authentication service.

Data is transferred between the decider and the authentication server in the form of JSON coded values via HTTP POST.

A request looks as follows:

{ 'zone' : 'AUTHENTICATION_ZONE', 'hostname' : 'webserver.com', 'url' : '/path/to/resource.html', 'cookies' : [ ('MYAUTHCOOKIE', '12345678912345'), ...] ... additional data ... }

Along with additional data, the request contains the authentication zone, the host name, the URL from the HTTP request, as well as a list of cookies of the HTTP request.

The authentication service answers as follows.

{ 'auth_zones' : [ 'AUTHENTICATION_ZONE', ...], 'redirect' : 'http://authentication.server.com', }

Both fields are optional here. If existent, auth_zones contains a list of zones for which this session has been authenticated. This list is added in the Authentication Handler (attribute “auth-zone”).

If redirect is stated, the HTTP request is answered by a HTTP redirect 302 to the given URL.

Configuring the standard external authentication server

vWAF provides a generic external authentication service that can hand over vWAF authentication requests to other backends.

Currently only SOAP based backends are supported.

The service is configured by an XML file. You must create this file manually and start the authentication server with this configuration file as the first argument. We recommend to save the configuration file as $ZEUSHOME/stingrayafm/current/etc/authserver.conf.

The configuration file must contain the following node elements:

<authentication-proxy version="1.0"> <authentication-log> .... </authentication-log> <authentication-service> .... </authentication-service> <authentication-backend> ... </authentication-backend> <authentication-cache> ... </authentication-cache> <authentication-request> ... </authentication-request> </authentication-proxy>

Unknown XML elements are ignored.

Configuration file node element <authentication-Log>

This node determines the log level, and the name of the log file to which the authentication server logs its messages.

Example

<authentication-log logfile="/var/log/ external-authentication.log" loglevel="debug"/>

Loglevel can be set to debug, info, error, or null. Setting the loglevel to “null” disables logging.

Configuration file node element <authentication-service>

This node sets the IP address and port number on which the authentication server accepts requests of the vWAF decider. The given data must match the configuration set for the Authentication Handler.

Example

<authentication-service ip="127.0.0.1" port="8089"/>

Configuration file node element <authentication-backend>

This node may occur multiple times. It describes a back-end (web service) and the mapping of authentication requests to this back-end.

Example

<authentication-backend name="AuthenticationBackendFoo" type="SOAP"> <wsdl>Service.wsdl</wsdl> <backend-request-mapping> ... </backend-request-mapping> <backend-response-mapping> . </backend-response-mapping> </authentication-backend>

The attribute name is a unique name, which can later be used to reference the back-end.

The attribute type must be set to SOAP at present. Future versions of the software will also support other back-ends.

The element <wsdl> must specify the name of a file that contains a WSDL description of the web service. vWAF uses this description as the basis for the request mapping.

The elements <backend-request-mapping> and <backend-response-mapping> are the core of the back-end description.

backend-request-mapping:

backend-request-mapping> <method> AccessResource </method> <parameter name="sessionToken" type="string"> request.cookies.MYAUTHCOOKIE </parameter> <parameter name="url" type="string"> request.url </parameter> <parameter name="certificate" type="string"> </parameter> </backend-request-mapping>

The element <method> contains the name of the web service request that’s to be called on the back-end.

Subsequently, the parameters of this call are described. In the given example, these are three parameters with the names sessionToken, url and certificate – each one of the type string. These parameters are set to the data of the HTTP request, in the given example the cookie MYAUTHCOOKIE, the URL and an empty string.

backend-response-mapping:

<backend-response-mapping> <result type="bool"> response.response </result> </backend-response-mapping>

In the given example, the field response from the SOAP response will be analyzed to determine whether authentication was successful.

Optionally, the back-end can provide a method to be notified when an entry in the cache of the Authentication Handler expires: <backend-cache-expire-notification>. (If present, this element must be inserted after the <backend-response-mapping> element.)

<backend-cache-expire-notification> <method> Logout </method> <parameter name="sessionToken" type="string"/> </backend-cache-expire-notification>

Configuration file node element <authentication-cache>

Requests to the back-end can be cached. This is determined by the configuration of the authentication cache.

Example

<authentication-cache name="default"> <session>request.cookies.MYAUTHCOOKIE</session> <timeout>300</timeout> <on-cache-expire-send-notification> <use-backend name="central-auth-service"/> </on-cache-expire-send-notification> <expose-cache-expire-interface ip="0.0.0.0" port="8094" type="SOAP"/> </authentication-cache>

The attribute name is used to reference the cache later on.

The session element describes how the session ID is to be extracted from the HTTP request. In the given example it's the contents of the cookie MYAUTHCOOKIE.

The timeout element defines the cache timeout given in seconds (5 minutes in the given example).

The element on-cache-expire-send-notification is optional. It defines whether a back-end is to be notified when a cache entry expires, and if so, which back-end is to be notified.

The element expose-cache-expire-interface is also optional. It defines the IP address and port number of an interface that provides a method expire with a string argument as sessionid. This makes it possible for external components to invalidate cache entries relating to a given session. Currently only the type SOAP is supported.

Configuration file node element <authentication-request>

This is the core element of the configuration. It selects an <authentication-backend> and an <authentication-cache> from the request data and defines what’s to happen in case of a failed authentication. Usually this element occurs multiple times, once for each authentication zone.

Example

<authentication-request> <match-auth-zone>APPLICATION_1</match-auth-zone> <use-backend name="central-auth-service"/> <use-cache name="default"/> <if-not-authenticated> <action-redirect url="http://authserver/login"/> </if-not-authenticated> </authentication-request>

At the beginning there are some selectors that analyze the request and decide whether this configuration object is responsible for handling the request. The authentication server scans all <authentication-request> one after the other until it finds a configuration object that matches the current HTTP request.

The element <match-auth-zone> checks the name of the authentication zone that was specified for the Authentication Handler. In vWAF, this is the primary distinctive feature used to authenticate a resource. Other possible selection features are <match-auth-hostname> and <match-auth-uri> (both not shown in the given example).

The subsequent element <use-backend> defines which back-end is to be used to handle the request. The given name must be one of the names specified in the <authentication-backend> elements.

The element <use-cache> is optional. It selects one of the caches defined in the <authentication-cache> elements. The element <if-not-authenticated> allows to determine the behavior in case the authentication on the back-end wasn’t successful. In the given example, a redirect to a given URL is configured.

At present, no other actions than redirect are supported.