com.ebasetech.xi.api

Interface SecurityManager

public interface SecurityManager

SecurityManager provides a centralized interface for all security related services. It contains methods to logon or logoff a user or to check security privileges and credentials.

The SecurityManager is accessed using EbaseSystem.getSecurityManager().

Since:

V4.4

Method Summary

Modifier and Type	Method and Description
boolean	checkCredentialValue(java.lang.String credentialName, java.lang.String credentialValue) Returns true if the user credential identified by credentialName exists with the value credentialValue, otherwise returns false.
java.lang.String	getCredential(java.lang.String credentialName) Returns the credential value for the user credential identified by credentialName, or null if the credential does not exist or no user is logged on.
java.lang.String[]	getRoles() Returns an array of role names for the logged on user
java.lang.String	getUserName() Returns the user name when a user is logged on or null when no user is logged on.
boolean	hasRole(java.lang.String roleName) Returns true when a user is logged on and the user has the role identified by roleName, otherwise returns false.
boolean	isAuthorized(java.lang.String type, java.lang.String name, java.lang.String function) Returns true when a user is logged on and the user has the authorization identified by type, name and function;otherwise returns false.
boolean	isDesignerUser() Returns true when a form has been submitted from the designer, otherwise returns false.
boolean	isUserLoggedOn() Returns true when a user is logged on to the current session, otherwise returns false.
boolean	isUserLoggedOn(java.lang.String userId) Returns true if the named user is currently logged on to the server, otherwise returns false.
void	logoff() Logs a user off the system, this is the reverse of method logon(String[][]).
void	logon(java.lang.String[][] inParameters) Logs a user onto the system by calling the default System Logon Service identified by the web service name ebaseLogonService.
void	logon(java.lang.String webServiceName, java.lang.String[][] inParameters) Logs a user onto the system by calling the specific System Logon Service identified by parameter webServiceName.
void	updateLoggedOnUser(java.lang.String userId, java.lang.String[][] inParameters) If the user identified by userId is currently logged on, the default System Logon Service is invoked and all sessions where the user is logged on are updated; if the user is not currently logged on no action is taken.
void	updateLoggedOnUser(java.lang.String webServiceName, java.lang.String userId, java.lang.String[][] inParameters) If the user identified by userId is currently logged on, the specific System Logon Service identified by parameter webServiceName is invoked and all sessions where the user is logged on are updated; if the user is not currently logged on no action is taken.

Method Detail

getUserName

java.lang.String getUserName()

Returns the user name when a user is logged on or null when no user is logged on.

Since:

V4.4

See Also:

logon(String[][])

isUserLoggedOn

boolean isUserLoggedOn()

Returns true when a user is logged on to the current session, otherwise returns false.

Since:

V4.4

See Also:

logon(String[][])

isUserLoggedOn

boolean isUserLoggedOn(java.lang.String userId)

Returns true if the named user is currently logged on to the server, otherwise returns false.

Since:

V5.3

hasRole

boolean hasRole(java.lang.String roleName)

Returns true when a user is logged on and the user has the role identified by roleName, otherwise returns false. User roles are established by the System Logon Service when the user logs on.

Further documentation.

Since:

V4.4

See Also:

logon(String[][])

getRoles

java.lang.String[] getRoles()

Returns an array of role names for the logged on user

Since:

V5.2.1

isAuthorized

boolean isAuthorized(java.lang.String type,
                     java.lang.String name,
                     java.lang.String function)

Returns true when a user is logged on and the user has the authorization identified by type, name and function;otherwise returns false.

Authorizations are only applicable when the built in Ebase Xi Security system is being used; when security is configured externally e.g. in an LDAP system such as Active Directory, authorizations cannot be used. Authorizations represent an alternative to roles, see hasRole(String). User authorizations are established by the System Logon Service when the user logs on.

Further documentation.

Since:

V4.4

See Also:

logon(String[][])

getCredential

java.lang.String getCredential(java.lang.String credentialName)

Returns the credential value for the user credential identified by credentialName, or null if the credential does not exist or no user is logged on. User credentials are established by the System Logon Service when the user logs on.

Further documentation.

Since:

V4.4

See Also:

checkCredentialValue(String, String), logon(String[][])

checkCredentialValue

boolean checkCredentialValue(java.lang.String credentialName,
                             java.lang.String credentialValue)

Returns true if the user credential identified by credentialName exists with the value credentialValue, otherwise returns false. User credentials are established by the System Logon Service when the user logs on.

Further documentation.

Since:

V4.4

See Also:

getCredential(String), logon(String[][])

logoff

void logoff()

Logs a user off the system, this is the reverse of method logon(String[][]). Method isUserLoggedOn() returns false after this method is invoked. Note that the user's session is not terminated by calling this method.

Since:

V4.4

logon

void logon(java.lang.String[][] inParameters)
    throws com.ebasetech.xi.exceptions.LogonException

Logs a user onto the system by calling the default System Logon Service identified by the web service name ebaseLogonService. Any roles and credentials associated with the user are also loaded as implemented by the Logon Service logic.

If the logon fails for any reason or returns a null userid, a LogonException is thrown. A LogonException contains the error code and error description returned from the Logon Service. These are available as methods LogonException.getErrorCode() and LogonException.getMessage() respectively.

When the logon is successful, method isUserLoggedOn() returns true, the user name can be obtained using method getUserName() and the other methods in this interface can be used to access the user's security roles and credentials as loaded by the Logon Service.

Further documentation.

Javascript example:

 try {
   system.securityManager.logon( [ 
          ["Script", fields.USER.value], 
          ["Script", fields.PASSWORD.value] 
           ] );
 }
 catch (e) {
   event.owner.addErrorMessage(e.javaException.message);
 }
 

Parameters:

inParameters - an array of arrays containing up to 3 pairs of parameters, where each pair contains 2 strings corresponding to the parameter source type and parameter value.

Throws:

com.ebasetech.xi.exceptions.LogonException - if any error occurs. This exception contains methods to obtain the detailed error code and error description returned from the Logon Service.

Since:

V4.4

logon

void logon(java.lang.String webServiceName,
           java.lang.String[][] inParameters)
    throws com.ebasetech.xi.exceptions.LogonException

Logs a user onto the system by calling the specific System Logon Service identified by parameter webServiceName. Any roles and credentials associated with the user are also loaded as implemented by the Logon Service logic.

If the logon fails for any reason or returns a null userid, a LogonException is thrown. A LogonException contains the error code and error description returned from the Logon Service. These are available as methods LogonException.getErrorCode() and LogonException.getMessage() respectively.

When the logon is successful, method isUserLoggedOn() returns true, the user name can be obtained using method getUserName() and the other methods in this interface can be used to access the user's security roles and credentials as loaded by the Logon Service.

Further documentation.

Javascript example:

 try {
   system.securityManager.logon( "testLogonService", [ 
          ["Script", fields.USER.value], 
          ["Script", fields.PASSWORD.value] 
           ] );
 }
 catch (e) {
   event.owner.addErrorMessage(e.javaException.message);
 }
 

Parameters:

webServiceName - the web service name for the Logon Service to be invoked

inParameters - an array of arrays containing up to 3 pairs of parameters, where each pair contains 2 strings corresponding to the parameter source type and parameter value.

Throws:

com.ebasetech.xi.exceptions.LogonException - if any error occurs. This exception contains methods to obtain the detailed error code and error description returned from the Logon Service.

Since:

V5.0

isDesignerUser

boolean isDesignerUser()

Returns true when a form has been submitted from the designer, otherwise returns false.

When a form is submitted from the designer, the designer user's security (userid plus authorizations) is transferred to the runtime environment. Such forms always return true to method isUserLoggedOn().

Since:

V4.4

updateLoggedOnUser

void updateLoggedOnUser(java.lang.String webServiceName,
                        java.lang.String userId,
                        java.lang.String[][] inParameters)
                 throws com.ebasetech.xi.exceptions.LogonException

If the user identified by userId is currently logged on, the specific System Logon Service identified by parameter webServiceName is invoked and all sessions where the user is logged on are updated; if the user is not currently logged on no action is taken.

This function is intended to be used to update roles and/or credentials of logged on users without the need for the user to re-logon. It cannot be used to logoff a user or to change their userid. Also there is no point in repeating userid/password validation in the Logon Service as no action can be taken as a result.

Further documentation.

Javascript example:

 try {
   system.securityManager.logon( "testLogonService", fields.USER.value, [ 
          ["Update", fields.USER.value] 
         ] );
 }
 catch (e) {
   event.owner.addErrorMessage(e.javaException.message);
 }
 

Parameters:

webServiceName - the web service name for the Logon Service to be invoked

userId - the user id whose sessions are to be updated

inParameters - an array of arrays containing up to 3 pairs of parameters, where each pair contains 2 strings corresponding to the parameter source type and parameter value.

Throws:

com.ebasetech.xi.exceptions.LogonException - if any error occurs. This exception contains methods to obtain the detailed error code and error description returned from the Logon Service.

Since:

V5.3

updateLoggedOnUser

void updateLoggedOnUser(java.lang.String userId,
                        java.lang.String[][] inParameters)
                 throws com.ebasetech.xi.exceptions.LogonException

If the user identified by userId is currently logged on, the default System Logon Service is invoked and all sessions where the user is logged on are updated; if the user is not currently logged on no action is taken.

This function is intended to be used to update roles and/or credentials of logged on users without the need for the user to re-logon. It cannot be used to logoff a user or to change their userid. Also there is no point in repeating userid/password validation in the Logon Service as no action can be taken as a result.

Further documentation.

Javascript example:

 try {
   system.securityManager.updateLoggedOnUser( fields.USER.value, [ 
          ["Update", fields.USER.value] 
         ] );
 }
 catch (e) {
   event.owner.addErrorMessage(e.javaException.message);
 }
 

Parameters:

userId - the user id whose sessions are to be updated

inParameters - an array of arrays containing up to 3 pairs of parameters, where each pair contains 2 strings corresponding to the parameter source type and parameter value.

Throws:

com.ebasetech.xi.exceptions.LogonException - if any error occurs. This exception contains methods to obtain the detailed error code and error description returned from the Logon Service.

Since:

V5.3