Package org.apache.wiki.auth

# Interface AuthenticationManager

All Superinterfaces:
  `Initializable`

All Known Implementing Classes:
  `DefaultAuthenticationManager`

public interface AuthenticationManager extends Initializable
Manages authentication activities for a Engine: user login, logout, and credential refreshes. This class uses JAAS to determine how users log in.

The login procedure is protected in addition by a mechanism which prevents a hacker to try and force-guess passwords by slowing down attempts to log in into the same account. Every login attempt is recorded, and stored for a while (currently ten minutes), and each login attempt during that time incurs a penalty of 2^login attempts milliseconds - that is, 10 login attempts incur a login penalty of 1.024 seconds. The delay is currently capped to 20 seconds.

Since:
  2.3

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`PREFIX_LOGIN_MODULE_OPTIONS`
Prefix for LoginModule options key/value pairs.
`static final String`
`PROP_ALLOW_COOKIE_ASSERTIONS`
If this jspwiki.properties property is `true`, allow cookies to be used to assert identities.
`static final String`
`PROP_ALLOW_COOKIE_AUTH`
If this jspwiki.properties property is `true`, allow cookies to be used for authentication.
`static final String`
`PROP_LOGIN_MODULE`
The `LoginModule` to use for custom authentication.
`static final String`
`PROP_LOGIN_THROTTLING`
Whether logins should be throttled to limit brute-forcing attempts.
`static final String`
`PROP_STOREIPADDRESS`
If this jspwiki.properties property is `true`, logs the IP address of the editor on saving.

## Method Summary

Modifier and Type
Method
Description
`void`
`addWikiEventListener(WikiEventListener listener)`
Registers a WikiEventListener with this instance.
`boolean`
`allowsCookieAssertions()`
Determines whether this Engine allows users to assert identities using cookies instead of passwords.
`boolean`
`allowsCookieAuthentication()`
Determines whether this Engine allows users to authenticate using cookies instead of passwords.
`Set<Principal>`
`doJAASLogin(Class<? extends LoginModule> clazz, CallbackHandler handler, Map<String,String> options)`
Instantiates and executes a single JAAS `LoginModule`, and returns a Set of Principals that results from a successful login.
`default void`
`fireEvent(int type, Principal principal, Object target)`
Fires a WikiSecurityEvent of the provided type, Principal and target Object to all registered listeners.
`default Principal`
`getLoginPrincipal(Set<Principal> principals)`
Returns the first Principal in a set that isn't a `Role` or `GroupPrincipal`.
`boolean`
`isContainerAuthenticated()`
Returns true if this Engine uses container-managed authentication.
`static boolean`
`isRolePrincipal(Principal principal)`
Determines whether the supplied Principal is a "role principal".
`static boolean`
`isUserPrincipal(Principal principal)`
Determines whether the supplied Principal is a "user principal".
`boolean`
`login(javax.servlet.http.HttpServletRequest request)`
Logs in the user by attempting to populate a Session Subject from a web servlet request by examining the request for the presence of container credentials and user cookies.
`boolean`
`login(Session session, javax.servlet.http.HttpServletRequest request, String username, String password)`
Attempts to perform a Session login for the given username/password combination using JSPWiki's custom authentication mode.
`void`
`logout(javax.servlet.http.HttpServletRequest request)`
Logs the user out by retrieving the Session associated with the HttpServletRequest and unbinding all of the Subject's Principals, except for `Role.ALL`, `Role.ANONYMOUS`. is a cheap-and-cheerful way to do it without invoking JAAS LoginModules.
`void`
`removeWikiEventListener(WikiEventListener listener)`
Un-registers a WikiEventListener with this instance.

### Methods inherited from interface org.apache.wiki.api.engine.Initializable

`initialize`

## Field Details

### PROP_STOREIPADDRESS

static final String PROP_STOREIPADDRESS
If this jspwiki.properties property is `true`, logs the IP address of the editor on saving.

See Also:
  - Constant Field Values

### PROP_ALLOW_COOKIE_AUTH

static final String PROP_ALLOW_COOKIE_AUTH
If this jspwiki.properties property is `true`, allow cookies to be used for authentication.

See Also:
  - Constant Field Values

### PROP_LOGIN_THROTTLING

static final String PROP_LOGIN_THROTTLING
Whether logins should be throttled to limit brute-forcing attempts. Defaults to true.

See Also:
  - Constant Field Values

### PREFIX_LOGIN_MODULE_OPTIONS

static final String PREFIX_LOGIN_MODULE_OPTIONS
Prefix for LoginModule options key/value pairs.

See Also:
  - Constant Field Values

### PROP_ALLOW_COOKIE_ASSERTIONS

static final String PROP_ALLOW_COOKIE_ASSERTIONS
If this jspwiki.properties property is `true`, allow cookies to be used to assert identities.

See Also:
  - Constant Field Values

### PROP_LOGIN_MODULE

static final String PROP_LOGIN_MODULE
The `LoginModule` to use for custom authentication.

See Also:
  - Constant Field Values

## Method Details

### isContainerAuthenticated

boolean isContainerAuthenticated()
Returns true if this Engine uses container-managed authentication. This method is used primarily for cosmetic purposes in the JSP tier, and performs no meaningful security function per se. Delegates to `WebContainerAuthorizer.isContainerAuthorized()`, if used as the external authorizer; otherwise, returns `false`.

Returns:
  `true` if the wiki's authentication is managed by the container, `false` otherwise

### login

boolean login(javax.servlet.http.HttpServletRequest request) throws WikiSecurityException

Logs in the user by attempting to populate a Session Subject from a web servlet request by examining the request for the presence of container credentials and user cookies. The processing logic is as follows:

- If the Session had previously been unauthenticated, check to see if user has subsequently authenticated. To be considered "authenticated," the request must supply one of the following (in order of preference): the container `userPrincipal`, container `remoteUser`, or authentication cookie. If the user is authenticated, this method fires event `WikiSecurityEvent.LOGIN_AUTHENTICATED` with two parameters: a Principal representing the login principal, and the current Session. In addition, if the authorizer is of type WebContainerAuthorizer, this method iterates through the container roles returned by `WebContainerAuthorizer.getRoles()`, tests for membership in each one, and adds those that pass to the Subject's principal set.
- If, after checking for authentication, the Session is still Anonymous, this method next checks to see if the user has "asserted" an identity by supplying an assertion cookie. If the user is found to be asserted, this method fires event `WikiSecurityEvent.LOGIN_ASSERTED` with two parameters: `WikiPrincipal(cookievalue)`, and the current Session.
- If, after checking for authenticated and asserted status, the Session is still anonymous, this method fires event `WikiSecurityEvent.LOGIN_ANONYMOUS` with two parameters: `WikiPrincipal(remoteAddress)`, and the current Session

Parameters:
  `request` - servlet request for this user
Returns:
  always returns `true` (because anonymous login, at least, will always succeed)
Throws:
  `WikiSecurityException` - if the user cannot be logged in for any reason
Since:
  2.3

### login

boolean login(Session session, javax.servlet.http.HttpServletRequest request, String username, String password) throws WikiSecurityException
Attempts to perform a Session login for the given username/password combination using JSPWiki's custom authentication mode. In order to log in, the JAAS LoginModule supplied by the Engine property `PROP_LOGIN_MODULE` will be instantiated, and its `LoginModule.initialize(Subject, CallbackHandler, Map, Map)` method will be invoked. By default, the `UserDatabaseLoginModule` class will be used. When the LoginModule's `initialize` method is invoked, an options Map populated by properties keys prefixed by `PREFIX_LOGIN_MODULE_OPTIONS` will be passed as a parameter.

Parameters:
  `session` - the current wiki session; may not be `null`.
  `request` - the user's HTTP request. This parameter may be `null`, but the configured LoginModule will not have access to the HTTP request in this case.
  `username` - The user name. This is a login name, not a WikiName. In most cases they are the same, but in some cases, they might not be.
  `password` - the password
Returns:
  true, if the username/password is valid
Throws:
  `WikiSecurityException` - if the Authorizer or UserManager cannot be obtained

### logout

void logout(javax.servlet.http.HttpServletRequest request)
Logs the user out by retrieving the Session associated with the HttpServletRequest and unbinding all of the Subject's Principals, except for `Role.ALL`, `Role.ANONYMOUS`. is a cheap-and-cheerful way to do it without invoking JAAS LoginModules. The logout operation will also flush the JSESSIONID cookie from the user's browser session, if it was set.

Parameters:
  `request` - the current HTTP request

### allowsCookieAssertions

boolean allowsCookieAssertions()
Determines whether this Engine allows users to assert identities using cookies instead of passwords. This is determined by inspecting the Engine property `PROP_ALLOW_COOKIE_ASSERTIONS`.

Returns:
  `true` if cookies are allowed

### allowsCookieAuthentication

boolean allowsCookieAuthentication()
Determines whether this Engine allows users to authenticate using cookies instead of passwords. This is determined by inspecting the Engine property `PROP_ALLOW_COOKIE_AUTH`.

Returns:
  `true` if cookies are allowed for authentication
Since:
  2.5.62

### doJAASLogin

Set<Principal> doJAASLogin(Class<? extends LoginModule> clazz, CallbackHandler handler, Map<String,String> options) throws WikiSecurityException
Instantiates and executes a single JAAS `LoginModule`, and returns a Set of Principals that results from a successful login. The LoginModule is instantiated, then its `LoginModule.initialize(Subject, CallbackHandler, Map, Map)` method is called. The parameters passed to `initialize` is a dummy Subject, an empty shared-state Map, and an options Map the caller supplies.

Parameters:
  `clazz` - the LoginModule class to instantiate
  `handler` - the callback handler to supply to the LoginModule
  `options` - a Map of key/value strings for initializing the LoginModule
Returns:
  the set of Principals returned by the JAAS method `Subject.getPrincipals()`
Throws:
  `WikiSecurityException` - if the LoginModule could not be instantiated for any reason

### isRolePrincipal

static boolean isRolePrincipal(Principal principal)
Determines whether the supplied Principal is a "role principal".

Parameters:
  `principal` - the principal to test
Returns:
  `true` if the Principal is of type `GroupPrincipal` or `Role`, `false` otherwise.

### isUserPrincipal

static boolean isUserPrincipal(Principal principal)
Determines whether the supplied Principal is a "user principal".

Parameters:
  `principal` - the principal to test
Returns:
  `false` if the Principal is of type `GroupPrincipal` or `Role`, `true` otherwise.

### getLoginPrincipal

default Principal getLoginPrincipal(Set<Principal> principals)
Returns the first Principal in a set that isn't a `Role` or `GroupPrincipal`.

Parameters:
  `principals` - the principal set
Returns:
  the login principal

### addWikiEventListener

void addWikiEventListener(WikiEventListener listener)
Registers a WikiEventListener with this instance. This is a convenience method.

Parameters:
  `listener` - the event listener

### removeWikiEventListener

void removeWikiEventListener(WikiEventListener listener)
Un-registers a WikiEventListener with this instance. This is a convenience method.

Parameters:
  `listener` - the event listener

### fireEvent

default void fireEvent(int type, Principal principal, Object target)
Fires a WikiSecurityEvent of the provided type, Principal and target Object to all registered listeners.

Parameters:
  `type` - the event type to be fired
  `principal` - the subject of the event, which may be `null`
  `target` - the changed Object, which may be `null`
See Also:
  - `WikiSecurityEvent`