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

  Constructors
  Constructor
  Description
  `Directory()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `UserReference`
  `authenticateUserFromArray(Object[] args)`
  Authenticates a user using an open array.
  `UserReference`
  `authenticateUserFromHttpRequest(HttpServletRequest request)`
  Authenticates a user for the purpose of a single sign-on policy.
  `abstract UserReference`
  `authenticateUserFromLoginPassword(String aLogin, String aPassword)`
  Authenticates a user using the login and password specified.
  `UserReference`
  `authenticateUserFromSOAPHeader(Element header)`
  Authenticates a user using a SOAP header.
  `String`
  `displayBuiltInRole(Role aBuiltInRole, Locale aLocale)`
  Returns a label for the specified built-in role.
  `String`
  `displaySpecificRole(Role aSpecificRole, Locale aLocale)`
  Returns a label for this specific role.
  `String`
  `displayUser(UserReference aUserReference, Locale aLocale)`
  Returns a label for the specified user.
  `String`
  `displayUserWithSalutation(UserReference aUserReference, Locale aLocale)`
  Returns a label for the specified user so that it can be used in the user interface.
  `List<UserReference>`
  `getBackedUpUsers(UserReference aUserReference)`
  Returns the users backed up by the specified user.
  `List<UserReference>`
  `getBackingUpUsers(UserReference aUserReference)`
  Returns the users backing up the specified user.
  `abstract List<Profile>`
  `getProfiles(ProfileListContext aProfileContext)`
  Returns all profiles according to the specified context.
  `String`
  `getRoleEmail(Role aRole)`
  Returns the email address of the specified role.
  `URI`
  `getUserAuthenticationURI(Session aSession)`
  Deprecated.
  Since 6.1.3, it is recommended to use the property `ebx.security.loginPage.url` instead.
  `URI`
  `getUserAvatarURI(UserReference aUserReference)`
  Returns the URL to the image associated with the specified user.
  `String`
  `getUserEmail(UserReference aUserReference)`
  Returns the email address of the specified user, `null` if unknown.
  `String`
  `getUserInitials(UserReference aUserReference, Locale aLocale)`
  Returns the initials of the specified user.
  `List<UserReference>`
  `getUsersInRole(Role aRole)`
  Returns all users that belong to the specified role.
  `boolean`
  `hasUsersInRole(Role aRole)`
  Returns `true` if one or more users have the specified role.
  `boolean`
  `isRoleStrictlyIncluded(Role aRole, Role anotherRole)`
  Returns `true` when `aRole` is included in `anotherRole`.
  `abstract boolean`
  `isSpecificRoleDefined(Role aSpecificRole)`
  Returns `true` if the specific role exists in this directory.
  `abstract boolean`
  `isUserDefined(UserReference aUserReference)`
  Returns `true` if the specified user actually exists in this directory.
  `abstract boolean`
  `isUserInRole(UserReference aUser, Role aRole)`
  Returns `true` if the user has the specified role.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## 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:

    - The full authentication process is detailed in the class `UIHttpManagerComponent`.
    - This method can also be directly called by a client web application using `Repository.createSessionFromHttpRequest(HttpServletRequest)`.
    - The default implementation of this method always returns `null`. It must be overridden for single sign-on.
    - This method is able to grant specific privileges to the resulting session by invoking the method `Profile.forUserWithSpecificPrivilege(String, ServiceKey)`.
    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:
      - Overriding the default security header

  - ### 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:
      - `DirectoryHandler.isProfileDefined(Profile)`

  - ### isSpecificRoleDefined

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

  - ### 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:

    - `Profile.OWNER`
    - `Profile.EVERYONE`

    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:
      - `Session.isUserInRole(Profile)`
      - `DirectoryHandler.isUserInRole(UserReference, Role)`

  - ### 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:
      - `DirectoryHandler.isRoleStrictlyIncluded(Role, Role)`

  - ### getProfiles

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

    ##### Postconditions:

    The profiles returned have some restrictions:

    - For defining permissions (see `ProfileListContext.isForDefiningPermission()`), the list must not contain the ADMINISTRATOR built-in role.
    - For owning a dataspace, snapshot, or dataset (see `ProfileListContext.isForSelectingBranchOwner()` and `ProfileListContext.isForSelectingInstanceOwner()`), the list must not contain the built-in role OWNER.
    - For workflows (see `ProfileListContext.isForWorkflow()`, the list must not contain the built-in role OWNER.
    - For defining views (see `ProfileListContext.isForDefiningViews()`, the list must not contain the built-in role OWNER.
    Returns:
      an immutable 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:
      an immutable 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:
      - `DirectoryHandler.displayProfile(Profile, Locale)`

  - ### 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:
      - `DirectoryHandler.displayProfile(Profile, Locale)`

  - ### 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:
      an immutable 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:
      an immutable 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:
      - `DirectoryHandler.displayProfile(Profile, Locale)`

  - ### 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:
      - `UIComponentWriter.addUserAvatar(UserReference)`

  - ### 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:
      - `getUserAvatarURI(UserReference)`