Package org.apache.guacamole.net.auth

Interface AuthenticationProvider

All Known Implementing Classes:
AbstractAuthenticationProvider, SimpleAuthenticationProvider
public interface AuthenticationProvider
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.

  • Method Details

    • getIdentifier

      String getIdentifier()
      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.
      Returns:
      The unique identifier assigned to this AuthenticationProvider, which may not be null.

    • getResource

      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().
      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.

    • updateCredentials

      default Credentials updateCredentials(Credentials credentials) throws org.apache.guacamole.GuacamoleException
      Given the set of credentials that a user has submitted during authentication but has not yet been provided to the authenticateUser(org.apache.guacamole.net.auth.Credentials) or updateAuthenticatedUser(org.apache.guacamole.net.auth.AuthenticatedUser, org.apache.guacamole.net.auth.Credentials) functions of installed AuthenticationProviders, returns the set of credentials that should be used instead. The returned credentials may be the original credentials, with or without modifications, or may be an entirely new Credentials object.
      Parameters:
      credentials - The credentials provided by a user during authentication.
      Returns:
      The set of credentials that should be provided to all AuthenticationProviders, including this AuthenticationProvider. This set of credentials may optionally be entirely new or may have been modified.
      Throws:
      org.apache.guacamole.GuacamoleException - If an error occurs while updating the provided credentials.

    • authenticateUser

      AuthenticatedUser authenticateUser(Credentials credentials) throws org.apache.guacamole.GuacamoleException
      Returns an AuthenticatedUser representing the user authenticated by the given credentials, if any.
      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

      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.
      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

      UserContext getUserContext(AuthenticatedUser authenticatedUser) throws org.apache.guacamole.GuacamoleException
      Returns the UserContext of the user authenticated by the given credentials.
      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

      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.
      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

      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.
      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

      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.
      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

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