org.apache.guacamole.net.auth

Class AbstractAuthenticationProvider

java.lang.Object

org.apache.guacamole.net.auth.AbstractAuthenticationProvider

All Implemented Interfaces:

AuthenticationProvider

Direct Known Subclasses:

SimpleAuthenticationProvider

public abstract class AbstractAuthenticationProvider
extends Object
implements AuthenticationProvider

Base implementation of AuthenticationProvider which provides default implementations of most functions. Implementations must provide their own AuthenticationProvider.getIdentifier(), but otherwise need only override an implemented function if they wish to actually implement the functionality defined for that function by the AuthenticationProvider interface.

Constructor Summary

Constructors

Constructor and Description
AbstractAuthenticationProvider()

Method Summary

Modifier and Type	Method and Description
AuthenticatedUser	authenticateUser(Credentials credentials) Returns an AuthenticatedUser representing the user authenticated by the given credentials, if any.
UserContext	decorate(UserContext context, AuthenticatedUser authenticatedUser, Credentials credentials) Given a UserContext returned from getUserContext() of a different AuthenticationProvider, returns a UserContext instance which decorates (wraps) that UserContext, delegating and overriding implemented functions as necessary.
Object	getResource() Returns an arbitrary REST resource representing this AuthenticationProvider.
UserContext	getUserContext(AuthenticatedUser authenticatedUser) Returns the UserContext of the user authenticated by the given credentials.
UserContext	redecorate(UserContext decorated, UserContext context, AuthenticatedUser authenticatedUser, Credentials credentials) Given a UserContext returned by updateUserContext() of a different AuthenticationProvider, returns a UserContext instance which decorates (wraps) that UserContext, delegating and overriding implemented functions as necessary.
void	shutdown() Frees all resources associated with this AuthenticationProvider.
AuthenticatedUser	updateAuthenticatedUser(AuthenticatedUser authenticatedUser, Credentials credentials) Returns a new or updated AuthenticatedUser for the given credentials already having produced the given AuthenticatedUser.
UserContext	updateUserContext(UserContext context, AuthenticatedUser authenticatedUser, Credentials credentials) Returns a new or updated UserContext for the given AuthenticatedUser already having the given UserContext.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.guacamole.net.auth.AuthenticationProvider

getIdentifier

Constructor Detail

AbstractAuthenticationProvider

public AbstractAuthenticationProvider()

Method Detail

getResource

public Object getResource()
                   throws org.apache.guacamole.GuacamoleException

Returns an arbitrary REST resource representing this AuthenticationProvider. The REST resource returned must be properly annotated with JSR-311 annotations, and may serve as the root resource for any number of subresources. The returned resource is ultimately exposed at ".../api/ext/IDENTIFIER/", where IDENTIFIER is the identifier of this AuthenticationProvider. REST resources returned by this function will be reachable by all users, regardless of whether they have authenticated. REST resources which must only be accessible by authenticated users should instead be returned from UserContext.getResource().

This implementation simply returns null. Implementations that wish to expose REST resources which are not specific to a user's session should override this function.

Specified by:

getResource in interface AuthenticationProvider

Returns:

An arbitrary REST resource, annotated with JSR-311 annotations, or null if no such resource is defined.

Throws:

org.apache.guacamole.GuacamoleException - If the REST resource cannot be returned due to an error.

authenticateUser

public AuthenticatedUser authenticateUser(Credentials credentials)
                                   throws org.apache.guacamole.GuacamoleException

Returns an AuthenticatedUser representing the user authenticated by the given credentials, if any.

This implementation performs no authentication whatsoever, ignoring the provided credentials and simply returning null. Any authentication attempt will thus fall through to other AuthenticationProvider implementations, perhaps within other installed extensions, with this AuthenticationProvider making no claim regarding the user's identity nor whether the user should be allowed or disallowed from accessing Guacamole. Implementations that wish to authenticate users should override this function.

Specified by:

authenticateUser in interface AuthenticationProvider

Parameters:

credentials - The credentials to use for authentication.

Returns:

An AuthenticatedUser representing the user authenticated by the given credentials, if any, or null if the credentials are invalid.

Throws:

org.apache.guacamole.GuacamoleException - If an error occurs while authenticating the user, or if access is temporarily, permanently, or conditionally denied, such as if the supplied credentials are insufficient or invalid.

updateAuthenticatedUser

public AuthenticatedUser updateAuthenticatedUser(AuthenticatedUser authenticatedUser,
                                                 Credentials credentials)
                                          throws org.apache.guacamole.GuacamoleException

Returns a new or updated AuthenticatedUser for the given credentials already having produced the given AuthenticatedUser. Note that because this function will be called for all future requests after initial authentication, including tunnel requests, care must be taken to avoid using functions of HttpServletRequest which invalidate the entire request body, such as getParameter(). Doing otherwise may cause the GuacamoleHTTPTunnelServlet to fail.

This implementation simply returns the provided authenticatedUser without modification. Implementations that wish to update a user's AuthenticatedUser object with respect to new Credentials received in requests which follow the initial, successful authentication attempt should override this function.

Specified by:

updateAuthenticatedUser in interface AuthenticationProvider

Parameters:

authenticatedUser - An AuthenticatedUser object representing the user authenticated by an arbitrary set of credentials. The AuthenticatedUser may come from this AuthenticationProvider or any other installed AuthenticationProvider.

credentials - The credentials to use for authentication.

Returns:

An updated AuthenticatedUser representing the user authenticated by the given credentials, if any, or null if the credentials are invalid.

Throws:

org.apache.guacamole.GuacamoleException - If an error occurs while updating the AuthenticatedUser.

getUserContext

public UserContext getUserContext(AuthenticatedUser authenticatedUser)
                           throws org.apache.guacamole.GuacamoleException

Returns the UserContext of the user authenticated by the given credentials.

This implementation simply returns null, effectively allowing authentication to continue but refusing to provide data for the given user. Implementations that wish to veto the authentication results of other AuthenticationProvider implementations or provide data for authenticated users should override this function.

Specified by:

getUserContext in interface AuthenticationProvider

Parameters:

authenticatedUser - An AuthenticatedUser object representing the user authenticated by an arbitrary set of credentials. The AuthenticatedUser may come from this AuthenticationProvider or any other installed AuthenticationProvider.

Returns:

A UserContext describing the permissions, connection, connection groups, etc. accessible or associated with the given authenticated user, or null if this AuthenticationProvider refuses to provide any such data.

Throws:

org.apache.guacamole.GuacamoleException - If an error occurs while creating the UserContext.

updateUserContext

public UserContext updateUserContext(UserContext context,
                                     AuthenticatedUser authenticatedUser,
                                     Credentials credentials)
                              throws org.apache.guacamole.GuacamoleException

Returns a new or updated UserContext for the given AuthenticatedUser already having the given UserContext. Note that because this function will be called for all future requests after initial authentication, including tunnel requests, care must be taken to avoid using functions of HttpServletRequest which invalidate the entire request body, such as getParameter(). Doing otherwise may cause the GuacamoleHTTPTunnelServlet to fail.

This implementation simply returns the provided context without modification. Implementations that wish to update a user's UserContext object with respect to newly-updated AuthenticatedUser or Credentials (such as those received in requests which follow the initial, successful authentication attempt) should override this function.

Specified by:

updateUserContext in interface AuthenticationProvider

Parameters:

context - The existing UserContext belonging to the user in question.

authenticatedUser - An AuthenticatedUser object representing the user authenticated by an arbitrary set of credentials. The AuthenticatedUser may come from this AuthenticationProvider or any other installed AuthenticationProvider.

credentials - The credentials which were most recently submitted. These are not guaranteed to be the same as the credentials associated with the AuthenticatedUser when they originally authenticated.

Returns:

An updated UserContext describing the permissions, connection, connection groups, etc. accessible or associated with the given authenticated user, or null if this AuthenticationProvider refuses to provide any such data.

Throws:

org.apache.guacamole.GuacamoleException - If an error occurs while updating the UserContext.

decorate

public UserContext decorate(UserContext context,
                            AuthenticatedUser authenticatedUser,
                            Credentials credentials)
                     throws org.apache.guacamole.GuacamoleException

Given a UserContext returned from getUserContext() of a different AuthenticationProvider, returns a UserContext instance which decorates (wraps) that UserContext, delegating and overriding implemented functions as necessary. Each UserContext created via getUserContext() will be passed to the decorate() functions of all other AuthenticationProviders, allowing those AuthenticationProviders to augment (or perhaps even limit) the functionality or data provided.

This implementation simply returns the provided context without performing any decoration. Implementations that wish to augment the functionality or data provided by other AuthenticationProvider implementations should override this function.

Specified by:

decorate in interface AuthenticationProvider

Parameters:

context - An existing UserContext generated by getUserContext() of a different AuthenticationProvider.

authenticatedUser - The AuthenticatedUser object representing the user associated with the given UserContext.

credentials - The credentials which were most recently submitted for the given AuthenticatedUser. These are not guaranteed to be the same as the credentials associated with the AuthenticatedUser object, which are the credentials provided when the user originally authenticated.

Returns:

A decorated (wrapped) UserContext object, or the original, undecorated UserContext.

Throws:

org.apache.guacamole.GuacamoleException - If the UserContext cannot be decorated due to an error.

redecorate

public UserContext redecorate(UserContext decorated,
                              UserContext context,
                              AuthenticatedUser authenticatedUser,
                              Credentials credentials)
                       throws org.apache.guacamole.GuacamoleException

Given a UserContext returned by updateUserContext() of a different AuthenticationProvider, returns a UserContext instance which decorates (wraps) that UserContext, delegating and overriding implemented functions as necessary. Each UserContext created via updateUserContext() will be passed to the decorate() functions of all other AuthenticationProviders, allowing those AuthenticationProviders to augment (or perhaps even limit) the functionality or data provided.

This implementation simply invokes decorate(UserContext,AuthenticatedUser,Credentials) with the provided context, authenticatedUser, and credentials. Implementations which override decorate(UserContext,AuthenticatedUser,Credentials) and which need to update their existing decorated object following possible updates to the UserContext or AuthenticatedUser (rather than generate an entirely new decorated object) should override this function.

Specified by:

redecorate in interface AuthenticationProvider

Parameters:

decorated - The UserContext returned when decorate() was invoked on this AuthenticationProvider for the UserContext which was just updated via a call to updateUserContext().

context - An existing UserContext generated by updateUserContext() of a different AuthenticationProvider.

authenticatedUser - The AuthenticatedUser object representing the user associated with the given UserContext.

credentials - The credentials which were most recently submitted for the given AuthenticatedUser. These are not guaranteed to be the same as the credentials associated with the AuthenticatedUser object, which are the credentials provided when the user originally authenticated.

Returns:

A decorated (wrapped) UserContext object, or the original, undecorated UserContext.

Throws:

org.apache.guacamole.GuacamoleException - If the UserContext cannot be decorated due to an error.

shutdown

public void shutdown()

Frees all resources associated with this AuthenticationProvider. This function will be automatically invoked when the Guacamole server is shutting down.

This implementation does nothing. Implementations that wish to perform cleanup tasks when the AuthenticationProvider is being unloaded should override this function.

Specified by:

shutdown in interface AuthenticationProvider