Authentication - AuthenticationHandler
The AuthenticationHandler interface defines the service API which may be implemented by authentication handlers registered as OSGi services.
AuthenticationHandler services have a single required service registration property which is used to identify requests to which the AuthenticationHandler service is applicable:
| Property | Description |
|---|---|
path |
One or more (array or vector) string values indicating the request URLs to which the AuthenticationHandler is applicable. |
authtype |
The authentication type implemented by this handler. This is a string value property and should be the same as will be used as the authentication type of the AuthenticationInfo object provided by the extractCredentials method. If this property is set, the requestCredentials method of the authentication handler is only called if the sling:authRequestLogin request parameter is either not set or is set to the same value as the authtype of the handler. This property is optional. If not set, the requestCredentials method is always called regardless of the value of the sling:authRequestLogin request parameter. |
Each path may be an absolute URL, an URL with just the host/port and path or just a plain absolute path:
| URL part | Scheme | Host/Port | Path |
|---|---|---|---|
| Absolute URL | must match | must match | request URL path is prefixed with the path |
| Host/Port with Path | ignored | must match | request URL path is prefixed with the path |
| Path | ignored | ignored | request URL path is prefixed with the path |
When looking for an AuthenticationHandler the authentication handler is selected whose path is the longest match on the request URL. If the service is registered with Scheme and Host/Port, these must exactly match for the service to be eligible. If multiple AuthenticationHandler services are registered with the same length matching path, the handler with the higher service ranking is selected1.
The value of path service registration property value triggering the call to any of the AuthenticationHandler methods is available as the path request attribute (for the time of the method call only). If the service is registered with multiple path values, the value of the path request attribute may be used to implement specific handling.
Implementations provided by Sling¶
Sample implementations¶
HTTP Basic Authentication Handler¶
extractCredentials-- Get user name and password from theAuthorizationHTTP headerrequestCredentials-- Send a 401/UNAUTHORIZED status withWWW-Authenticateresponse header setting the RealmdropCredentials-- Send a 401/UNAUTHORIZED status withWWW-Authenticateresponse header setting the Realm
Interestingly the dropCredentials method is implemented in the same way as the requestCredentials method. The reason for this is, that HTTP Basic authentication does not have a notion of login and logout. Rather the request is accompanied with an Authorization header or not. The contents of this header is usually cached by the client browser. So logout is actually simulated by sending a 401/UNAUTHORIZED status thus causing the client browser to clear the cache and ask for user name and password.
Form Based Authentication Handler¶
extractCredentials-- Get user name and password with the help of a special cookie (note, that of course the cookie should not contain this data, but refer to it in an internal store of the authentication handler). If the cookie is not set, check for specific login parameters to setup the cookie.requestCredentials-- Send the login form for the user to provide the login parameters.dropCredentials-- Clear the authentication cookie and internal store.
-
Service ranking is defined by the OSGi Core Specification as follows: If multiple qualifying service interfaces exist, a service with the highest
service.rankingnumber, or when equal to the lowestservice.id, determines which service object is returned by the Framework. ↩