public abstract class Directory extends Object
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).
For the user interface, the authentication process is the following:
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.
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.
authenticateUserFromLoginPassword
is
called.
For SOAP data services, authentication is described in the data services security section.
How to specify and deploy a specific directory is described in the class DirectoryFactory
.
The default implementation is DirectoryDefault
.
Constructor and Description |
---|
Directory() |
Modifier and Type | Method and 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 a list of all profiles according to the specified context.
|
String |
getRoleEmail(Role aRole)
Returns the email address of the specified role.
|
URI |
getUserAuthenticationURI(Session aSession)
This method allows defining a specific URL to replace the default login page.
|
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 |
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. |
public abstract UserReference authenticateUserFromLoginPassword(String aLogin, String aPassword) throws AuthenticationException
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)
.
null
if login does not exist or password is incorrect.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).public UserReference authenticateUserFromHttpRequest(HttpServletRequest request) throws AuthenticationException
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:
null
, the login/password page is returned
as the HTTP response.Notes:
UIHttpManagerComponent
.
Repository.createSessionFromHttpRequest(HttpServletRequest)
.
null
.
It must be overridden for single sign-on.
Profile.forUserWithSpecificPrivilege(String, ServiceKey)
.
null
if the authentication features are not provided in the request
(in which case a login/password is requested of the user).AuthenticationException
- if authentication cannot complete.public UserReference authenticateUserFromSOAPHeader(Element 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)
.
null
if login does not exist or password is incorrect.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).public UserReference authenticateUserFromArray(Object[] args)
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
.
null
if no user can be authenticated.public abstract boolean isUserDefined(UserReference aUserReference)
true
if the specified user actually exists in this
directory.public abstract boolean isSpecificRoleDefined(Role aSpecificRole)
true
if the specific role exists in this
directory.public abstract boolean isUserInRole(UserReference aUser, Role aRole)
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.
public boolean isRoleStrictlyIncluded(Role aRole, Role anotherRole)
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.
public abstract List<Profile> getProfiles(ProfileListContext aProfileContext)
The profiles returned have some restrictions:
ProfileListContext.isForDefiningPermission()
),
the list must not contain the ADMINISTRATOR built-in role.
ProfileListContext.isForSelectingBranchOwner()
and ProfileListContext.isForSelectingInstanceOwner()
),
the list must not contain the built-in role OWNER.
ProfileListContext.isForWorkflow()
,
the list must not contain the built-in role OWNER.
ProfileListContext.isForDefiningViews()
,
the list must not contain the built-in role OWNER.
List
of profiles
public String getRoleEmail(Role aRole)
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.
public List<UserReference> getUsersInRole(Role aRole)
Default implementation throws an exception: this method must be overridden.
UserReference
, each responding true
to method isUserInRole(UserReference, Role)
.public String getUserEmail(UserReference aUserReference)
null
if unknown.
The default implementation of this method always returns null
.
public String displayUser(UserReference aUserReference, Locale aLocale)
Implementation recommendations:
identifier
of the user.
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).
public String displayUserWithSalutation(UserReference aUserReference, Locale aLocale)
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".
public String displayBuiltInRole(Role aBuiltInRole, Locale aLocale)
The default implementation of this method returns a localized label.
public List<UserReference> getBackedUpUsers(UserReference aUserReference)
The default implementation of this method always returns null
.
UserReference
, each backed up by the
the specified user.public List<UserReference> getBackingUpUsers(UserReference aUserReference)
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
.
UserReference
, each backing-up the
the specified user.public URI getUserAuthenticationURI(Session aSession)
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
.
aSession
- may be null since version 5.7.0,public String displaySpecificRole(Role aSpecificRole, Locale aLocale)
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.
public URI getUserAvatarURI(UserReference aUserReference)
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
.
UIComponentWriter.addUserAvatar(UserReference)
public String getUserInitials(UserReference aUserReference, Locale aLocale)
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.
getUserAvatarURI(UserReference)