If you need to, you can tell the PortalProtect Dispatcher to support HTTP basic authentication, meaning it will process HTTP Authorization: Basic xxxxxxx HTTP request header.

Note that you should only do this for SSL connections, make sure to force clients to use SSL, e.g. by setting sslRequired=true. Also note that HTTP basic authentication is not very secure, since the userid and password are only base64 encoding, making it trivial for eavesdroppers to obtain the password.

Note that when using this with a browser, you will not be able to logoff effectively, since the browser will keep sending the HTTP Request header without prompting the user, so you need to close the browser. This is one of the main reasons you should avoid using basic authentication if possible, but it might be useful for having applications as clients instead of normal browsers.

When Does Portalprotect Authenticate the User

If basicAuthenticationEnabled=true and if the request from the client contains an Authorization: Basic HTTP header, and if the current session does not contain an authenticated user, then PortalProtect will use the userid/password to attempt to authenticate the user before processing the request. Once the session contains an authenticated user, no matter how he authenticated (basic auth or otherwise) the PP dispatcher will simply ignore the Authorization header.

How Are Authentication Errors Handled

By default, PortalProtect will redirect to the URL defined in urlAccessFailedRedirect but that behaviour can be changed using authentication error rules.

These rules function much like redirect/forward rules, and allow pattern matching on request URL / HTTP headers  and can determine that certain requests should be redirect to another error page, or a “HTTP 401 Authentication required” response can be sent back instead perhaps depending on user-agent.

It can be useful for agents such as SVN clients to force HTTP 401 error response instead of redirecting them to a login/error page in case authentication fails.

Such rules are defined by using the basicauthrule.* configuration entries

Example:

<property name="basicauthrule.1" value="ignorecase;401;user-agent=*SVN*" description=""/>
<property name="basicauthrule.2" value="https://somewhere.com/error;url=/somewhere/*" description=""/>

In this example, if the request matches the first rule (the user-agent HTTP header matching the string “*SVN*” then an HTTP 401 response code is returned. If the request instead matches the URL /somewhere/* the error URL the client is redirected to is https://somewhere.com/error

If none of the rules match, the URL defined in the configuration urlAccessFailedRedirect will be used.

This URL will then be appended 3 parameters, originalUrl which is the URL of the request, errorcode which is the errorcode returned from the authentication plugin exception, and errortext which is the errortext returned from the authentication plugin. It is then up to the application behind the URL how to handle the error, it might provide another means of logging in.

You must take care that the error URLs you redirect to are on an alternateserver definition where basic authentication is disabled, if not, and if the client still sends the Authorization: Basic HTTP header, the PP dispatcher will attempt to authenticate the new request, which will then fail causing a redirect loop to occur.

How Portalprotect Decides When to Require Authentication

By default, PortalProtect will not prompt browser/client for basic authentication, as long as the servers which the client attempts to send requests to are not protected, i.e. if they allow anonymous access. If the current request is not allowed, and if basicAuthenticationEnabled=true then PP Dispatcher will either redirect the user to an error URL where he can authenticate using other means, or send an HTTP 401 response, with the “WWW-Authenticate: Basic” HTTP response header. This will ask the client to provide basic auth credentials.

The way to determine to redirect or to send 401 auth required when a user does not have access to an URL is similar to the way authentication errors are handled – you can define rules that look at specific request URL or HTTP headers and determine the behaviour based on that. This can be quite useful if you want to redirect users within a browser to another URL, but you want to force prompting for basic auth to non-browser clients.

The same rules that define how errors are handled (redirect, or reprompt are the ones that decide if we should prompt or redirect).

Such rules are defined by using the basicauthrule.* configuration entries

Example:

<property name="basicauthrule.1" value="ignorecase;401;user-agent=*SVN*" description=""/>
<property name="basicauthrule.2" value="https://somewhere.com/error;url=/somewhere/*" description=""/>

The default behaviour if no rules are matching, is not to prompt the user, but to redirect to the urlAuthRequired URL.

This means that to get PP Dispatcher to prompt for basic authentication, you need a basicauthrule telling it to do so.

Between Ceptor Dispatcher and Application Server

By default, PortalProtect creates an Authorization: Basic xxxxxxxxyyyyyyyyyzzzzzzz HTTP header containing the session ID and the password “password” when sending a request to an application server behind the dispatcher.

This is done, to ease integration with various applicationserver security plugins, allowing the plugins to trigger on what the webserver believes to be HTTP basic authentication, but which is in reality just the PP Dispatcher sending the session ID to the backend application server.

The applicationserver security plugin can then use the information within the session to populate the JEE subject, or the Windows Identity depending on application server technology and capabilities.

If you need to, you can tell the PP Dispatcher to send the real users userid and password instead of the session ID in the authentication header. What actually happens depends on the authentication plugin and authentication method used. If using userid/password, and if the authentication plugin makes the password available in the PP session, both the userid and credentials will be sent to the application server.

Some authentication methods do not have a password available, such as NemID, and in these cases, a blank password will be sent instead to the application server.

You can also choose to tell the PP dispatcher not to generate its own authorization header, in that case it will only send the session ID to the application server. This also allows you to pass authorization headers and HTTP 401 responses transparently through the dispatcher between the browser/client and the application server.

By default, the option addauthorizationheader=true is enabled, along with addedAuthorizationHeaderContainsSessionID=true which causes the dispatcher to send the Authorization header with the session ID to the application server.

If you set addauthorizationheader=false, the header from the browser will be sent through, assuming you have not enabled the dispatcher to process basic authentication by setting basicAuthenticationEnabled=true. If you also set alternateserver.xxxx.ignore401=true then the dispatcher will ignore the 401 response from the browser and not attempt to redirect to a login page as it usually does, but pass on the unmodified response to the client.

Setting addauthorizationheader=true and addedAuthorizationHeaderContainsSessionID=false causes the dispatcher to add the userid/password of the currently authenticated user in the Authorization HTTP header if the user is logged in, and nothing if he is not logged in.

By default, PortalProtect will add the Authorization Header to all URLs – some applications might have performance issues if they do not cache the authentication, so you can limit the URLs that PortalProtect adds the authorization header to by setting restrictAuthorizationHeaderToUrls to an URL pattern which the URL must match. Wildcard characters ? and * are supported, | can be used to separate patterns, and ^ can be used as the first character to negate the expression.

Example:

/secure/*|/*.jsp
 ^*.gif|*.css|*.js|*.png|*.jpg|*.htm*

The first pattern will match the URLs secure/* or *.jsp, and the second will match anything but *.gif, *css etc.

restrictAuthorizationHeaderToUrls can also be specified per alternateserver.

NOTE: By default, the dispatcher is connected to the session controller as a restricted client, meaning the session will be cleaned of certain sensitive content, such as password before being sent to the dispatcher – to allow the dispatcher access to the password so it can pass it on to the application servers, you need to set hidePasswordFromDispatcher=false in the Session Controller.

The options for addauthorizationheader and addedAuthorizationHeaderContainsSessionID can be set separately for each configured alternateserver, meaning you can mix and match the settings depending on specific application needs.