org.apache.guacamole.net.auth.AuthenticationProvider Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of guacamole-ext Show documentation
Show all versions of guacamole-ext Show documentation
The Java API for extending the main Guacamole web application. This
is not needed for authoring a new Guacamole-based web application.
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.guacamole.net.auth;
import org.apache.guacamole.GuacamoleException;
/**
* Provides means of authorizing users and for accessing and managing data
* associated with those users. Access to such data is limited according to the
* AuthenticationProvider implementation.
*/
public interface AuthenticationProvider {
/**
* Returns the identifier which uniquely and consistently identifies this
* AuthenticationProvider implementation. This identifier may not be null
* and must be unique across all AuthenticationProviders loaded by the
* Guacamole web application.
*
* @return
* The unique identifier assigned to this AuthenticationProvider, which
* may not be null.
*/
String getIdentifier();
/**
* 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().
*
* @return
* An arbitrary REST resource, annotated with JSR-311 annotations, or
* null if no such resource is defined.
*
* @throws GuacamoleException
* If the REST resource cannot be returned due to an error.
*/
Object getResource() throws GuacamoleException;
/**
* Returns an AuthenticatedUser representing the user authenticated by the
* given credentials, if any.
*
* @param credentials
* The credentials to use for authentication.
*
* @return
* An AuthenticatedUser representing the user authenticated by the
* given credentials, if any, or null if the credentials are invalid.
*
* @throws 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.
*/
AuthenticatedUser authenticateUser(Credentials credentials)
throws 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.
*
* @param credentials
* The credentials to use for authentication.
*
* @param 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.
*
* @return
* An updated AuthenticatedUser representing the user authenticated by
* the given credentials, if any, or null if the credentials are
* invalid.
*
* @throws GuacamoleException
* If an error occurs while updating the AuthenticatedUser.
*/
AuthenticatedUser updateAuthenticatedUser(AuthenticatedUser authenticatedUser,
Credentials credentials) throws GuacamoleException;
/**
* Returns the UserContext of the user authenticated by the given
* credentials.
*
* @param 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.
*
* @return
* 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 GuacamoleException
* If an error occurs while creating the UserContext.
*/
UserContext getUserContext(AuthenticatedUser authenticatedUser)
throws 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.
*
* @param context
* The existing UserContext belonging to the user in question.
*
* @param 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.
*
* @param 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.
*
* @return
* 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 GuacamoleException
* If an error occurs while updating the UserContext.
*/
UserContext updateUserContext(UserContext context,
AuthenticatedUser authenticatedUser,
Credentials credentials) throws 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.
*
* @param context
* An existing UserContext generated by getUserContext() of a different
* AuthenticationProvider.
*
* @param authenticatedUser
* The AuthenticatedUser object representing the user associated with
* the given UserContext.
*
* @param 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.
*
* @return
* A decorated (wrapped) UserContext object, or the original,
* undecorated UserContext.
*
* @throws GuacamoleException
* If the UserContext cannot be decorated due to an error.
*/
UserContext decorate(UserContext context,
AuthenticatedUser authenticatedUser,
Credentials credentials) throws 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.
*
* @param decorated
* The UserContext returned when decorate() was invoked on this
* AuthenticationProvider for the UserContext which was just updated
* via a call to updateUserContext().
*
* @param context
* An existing UserContext generated by updateUserContext() of a
* different AuthenticationProvider.
*
* @param authenticatedUser
* The AuthenticatedUser object representing the user associated with
* the given UserContext.
*
* @param 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.
*
* @return
* A decorated (wrapped) UserContext object, or the original,
* undecorated UserContext.
*
* @throws GuacamoleException
* If the UserContext cannot be decorated due to an error.
*/
UserContext redecorate(UserContext decorated, UserContext context,
AuthenticatedUser authenticatedUser,
Credentials credentials) throws GuacamoleException;
/**
* Frees all resources associated with this AuthenticationProvider. This
* function will be automatically invoked when the Guacamole server is
* shutting down.
*/
void shutdown();
}