Package com.orchestranetworks.service.directory

Class Directory

java.lang.Object
com.orchestranetworks.service.directory.Directory
Direct Known Subclasses:
DirectoryDefault
public abstract class Directory extends Object
Defines the user directory used by EBX® to authenticate users and to define users and their roles.

Important: this abstract class is only for the specific implementation of a directory; any client code accessing the directory should use the DirectoryHandler methods as often as possible, since they perform additional checks (such as allowing the built-in administrator role to be disabled).

Authentication in the user interface

For the user interface, the authentication process is the following:

  1. If both parameters login and password are specified, the method authenticateUserFromLoginPassword is called. If the supplied credentials successfully authenticate the user, the requested URL is served; otherwise, an 'access denied' page is returned. In both cases, the authentication process stops here.
    1. If parameters login and password are both unspecified, the method authenticateUserFromHttpRequest is called (it is up to the specific directory to implement this method, which will parse the URL for user directory-specific tokens). If the method throws an exception, an 'access denied' page is returned. If the method returns null (default implementation), the request is considered to have not specified an authentication, which results in the next step being performed.
    2. The login/password page is returned to the user. When this page is submitted, the method authenticateUserFromLoginPassword is called.

Authentication in data services

For SOAP data services, authentication is described in the data services security section.

Deploying a specific directory

How to specify and deploy a specific directory is described in the class DirectoryFactory.

The default implementation is DirectoryDefault.

  • Constructor Details

    • Directory

      public Directory()

  • Method Details

    • authenticateUserFromLoginPassword

      public abstract UserReference authenticateUserFromLoginPassword(String aLogin, String aPassword) throws AuthenticationException
      Authenticates a user using the login and password specified.

      Note: For the EBX® user interface, the full authentication process is detailed in the class UIHttpManagerComponent. This method can also be called by a client application through Repository.createSessionFromLoginPassword(String, String).

      Returns:
      the user reference corresponding to the specified login/password, or null if login does not exist or password is incorrect.
      Throws:
      AuthenticationException - if authentication fails for a reason that is more specific than an unknown login or an incorrect password (for example, a security violation or a physical access failure).

    • authenticateUserFromHttpRequest

      public UserReference authenticateUserFromHttpRequest(HttpServletRequest request) throws AuthenticationException
      Authenticates a user for the purpose of a single sign-on policy.

      If the implementation of this method does not return null, the user enters the EBX® user interface session directly (without submitting a login and password).

      More precisely, this method is called each time an initial HTTP request is sent to the EBX® user interface:

      • If the method returns null, the login/password page is returned as the HTTP response.
      • If the method returns a user, this user is logged in the EBX® user interface session.
      • If the method throws an exception, an "Access denied" page is returned.

      Notes:

      Returns:
      the user reference retrieved from the specified HTTP request (for example, from its parameters or from its cookies), or null if the authentication features are not provided in the request (in which case a login/password is requested of the user).
      Throws:
      AuthenticationException - if authentication cannot complete.

    • authenticateUserFromSOAPHeader

      public UserReference authenticateUserFromSOAPHeader(Element header)
      Authenticates a user using a SOAP header.

      The default implementation only supports Services Security UsernameToken Profile 1.0: it extracts the login and password and delegates authentication to the method authenticateUserFromLoginPassword(String, String).

      Returns:
      the user reference corresponding to the specified login/password, or null if login does not exist or password is incorrect.
      Throws:
      AuthenticationException - if authentication fails for a reason that is more specific than an unknown login or incorrect password (for example, a security violation or a physical access failure).
      See Also:

    • authenticateUserFromArray

      public UserReference authenticateUserFromArray(Object[] args)
      Authenticates a user using an open array.

      Note: this method is only called through Repository.createSessionFromArray(Object[]), that is, only by a specific client application.

      The default implementation of this method always returns null.

      Returns:
      the user reference corresponding to the specified arguments, or null if no user can be authenticated.

    • isUserDefined

      public abstract boolean isUserDefined(UserReference aUserReference)
      Returns true if the specified user actually exists in this directory.
      See Also:

    • isSpecificRoleDefined

      public abstract boolean isSpecificRoleDefined(Role aSpecificRole)
      Returns true if the specific role exists in this directory.
      See Also:

    • isUserInRole

      public abstract boolean isUserInRole(UserReference aUser, Role aRole)
      Returns true if the user has the specified role.

      The method must return false if the user does not exist.

      The following built-in roles are not passed to this method because their definition does not depend on a specific directory:

      If the specified user has been authenticated and the corresponding Session object is available, it is recommended to invoke Session.isUserInRole(Profile) instead of this method, for performance purposes.

      See Also:

    • isRoleStrictlyIncluded

      public boolean isRoleStrictlyIncluded(Role aRole, Role anotherRole)
      Returns true when aRole is included in anotherRole.

      If true, a user having anotherRole also has the aRole.

      The default implementation of this method returns false. It should be overridden if role inclusion is implemented in the underlying directory.

      See Also:

    • getProfiles

      public abstract List<Profile> getProfiles(ProfileListContext aProfileContext)
      Returns a list of all profiles according to the specified context.
      Postconditions:

      The profiles returned have some restrictions:

      Returns:
      a List of profiles

    • getRoleEmail

      public String getRoleEmail(Role aRole)
      Returns the email address of the specified role.

      The default implementation of this method always returns null.

      If this directory defines an email for a role, the workflow notifications are sent to this email address, instead of sending an individual email to each user in this role.

      Since:
      5.7.0

    • getUsersInRole

      public List<UserReference> getUsersInRole(Role aRole)
      Returns all users that belong to the specified role.

      Default implementation throws an exception: this method must be overridden.

      Returns:
      a List of UserReference, each responding true to method isUserInRole(UserReference, Role).

    • hasUsersInRole

      public boolean hasUsersInRole(Role aRole)
      Returns true if one or more users have the specified role.

      Default implementation is not optimized as it is equivalent to calling:

      !getUsersInRole(aRole).isEmpty()

      This method should be overridden in case of performance issues.

      Since:
      6.0.6

    • getUserEmail

      public String getUserEmail(UserReference aUserReference)
      Returns the email address of the specified user, null if unknown.

      The default implementation of this method always returns null.

    • displayUser

      public String displayUser(UserReference aUserReference, Locale aLocale)
      Returns a label for the specified user.

      Implementation recommendations:

      • Since the returned label is used in lists, for example for setting permissions or ownership, it is recommended for it to contain at least the identifier of the user.
      • Any implementation of this method should handle the case where the user no longer exists in the directory (due to having been removed from the directory). In this case, it is expected for this method to return a particular label indicating that the specified user is unknown.

      The default implementation of this method simply displays the identifier of the user (and mentions that it is "unknown", if the user is not defined).

      See Also:

    • displayUserWithSalutation

      public String displayUserWithSalutation(UserReference aUserReference, Locale aLocale)
      Returns a label for the specified user so that it can be used in the user interface. For example, it is displayed by the EBX® user interface in the user interface header.

      The default implementation of this method invokes the method displayUser(UserReference, Locale).

      A custom implementation could display a salutation with first and last names, for example "Mr. Andrew Smith".

    • displayBuiltInRole

      public String displayBuiltInRole(Role aBuiltInRole, Locale aLocale)
      Returns a label for the specified built-in role.

      The default implementation of this method returns a localized label.

      See Also:

    • getBackedUpUsers

      public List<UserReference> getBackedUpUsers(UserReference aUserReference)
      Returns the users backed up by the specified user. When a user A is a backup of another user B, user A is able to log into the EBX® user interface as user B by using user A's own credentials.

      The default implementation of this method always returns null.

      Returns:
      a List of UserReference, each backed up by the the specified user.

    • getBackingUpUsers

      public List<UserReference> getBackingUpUsers(UserReference aUserReference)
      Returns the users backing up the specified user. It is the reciprocal of the method getBackedUpUsers(UserReference). For a given user who receives emails during workflow executions, each user returned by this method receives carbon copies of the emails.

      The default implementation of this method always returns null.

      Returns:
      a List of UserReference, each backing-up the the specified user.

    • getUserAuthenticationURI

      @Deprecated public URI getUserAuthenticationURI(Session aSession)
      Deprecated.
      Since 6.1.3, it is recommended to use the property ebx.security.loginPage.url instead.
      This method allows defining a specific URL to replace the default login page. Returns null if the default login page is not replaced.

      Returned value must be compatible with "refresh" HTML header tag:

      <meta http-equiv="refresh" content="0; url=DirectoryHandler#getUserAuthenticationURL()" />

      The default implementation of this method always returns null.

      Also, in the custom login page, the action attribute of the HTML form tag should be set to ".../ebx-authentication/login" in order to conform with the base URL as defined in the HTML tag: <base href="http://localhost:8080/ebx-authentication">. For example, the form tag should be: <form action="/ebx-authentication/login" method="post">.

      Parameters:
      aSession - may be null since version 5.7.0,
      Since:
      5.2.0

    • displaySpecificRole

      public String displaySpecificRole(Role aSpecificRole, Locale aLocale)
      Returns a label for this specific role.

      Any implementation of this method should handle the case where the role no longer exists in the directory (due to having been deleted). In this case, this method is expected to return a label indicating that the specified role is unknown.

      The default implementation of this method uses the name of the role.

      See Also:

    • getUserAvatarURI

      public URI getUserAvatarURI(UserReference aUserReference)
      Returns the URL to the image associated with the specified user. If this method returns null, the user's initials are usually used as the user avatar.

      The image must be a square format, there is no size limitation. Accepted image formats are the formats supported by the browser.

      Default implementation returns null.

      Since:
      5.7.0
      See Also:

    • getUserInitials

      public String getUserInitials(UserReference aUserReference, Locale aLocale)
      Returns the initials of the specified user. They are usually displayed if the user has no associated avatar image.

      Default implementation returns null.

      In case a specific directory implementation returns null for both the avatar URI and initials, the first two letters of the displayUser(UserReference, Locale) are used as initials.

      Since:
      5.7.0
      See Also: