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 Description boolean
checkCredentialValue(java.lang.String credentialName, java.lang.String credentialValue)
Returnstrue
if the user credential identified bycredentialName
exists with the valuecredentialValue
, otherwise returnsfalse
.java.lang.String
getCredential(java.lang.String credentialName)
Returns the credential value for the user credential identified bycredentialName
, ornull
if the credential does not exist or no user is logged on.java.util.Map<java.lang.String,java.lang.Object>
getCredentials()
Returns all of the User credentials that are established by the System Logon Service when the user logs on.JWTManager
getJwtManager()
KeyManager
getKeyManager()
Used either generate a HMAC hashed based
or lookup aSecretKey
/PublicKey
from a system keystore or from a remote JSON Web Key (JWK) SetPrivateKey
java.lang.String[]
getRoles()
Returns an array of role names for the logged on userjava.lang.String
getUserName()
Returns the user name when a user is logged on ornull
when no user is logged on.boolean
hasRole(java.lang.String roleName)
Returnstrue
when a user is logged on and the user has the role identified byroleName
, otherwise returnsfalse
.boolean
isAuthorized(java.lang.String type, java.lang.String name, java.lang.String function)
Returnstrue
when a user is logged on and the user has the authorization identified bytype
,name
andfunction
;otherwise returnsfalse
.boolean
isDesignerUser()
Returnstrue
when a form has been submitted from the designer, otherwise returnsfalse
.boolean
isGatewayRequest()
Returns true if the incoming Http Request contains the Gateway Authentication Token, otherwise falseboolean
isUserLoggedOn()
Returnstrue
when a user is logged on to the current session, otherwise returnsfalse
.boolean
isUserLoggedOn(java.lang.String userId)
Returnstrue
if the named user is currently logged on to the server, otherwise returnsfalse
.void
logoff()
Logs a user off the system, this is the reverse of methodlogon(String[][])
.void
logon(java.lang.String[][] inParameters)
Logs a user onto the system by calling the default System Logon Service identified in the Server Admin App > Security > User Authentication.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.boolean
logonGatewayAuthentication(java.lang.String gatewayServerName)
Logon using the Gateway Authentication Token.void
logonOpenIdConnect(java.lang.String openIdConnectName)
Logon using OpenID Connect.void
logonOpenIdConnect(java.lang.String openIdConnectName, java.lang.String scope)
Logon using OpenID Connect.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 Details
-
getUserName
java.lang.String getUserName()Returns the user name when a user is logged on ornull
when no user is logged on.- Since:
- V4.4
- See Also:
logon(String[][])
-
isUserLoggedOn
boolean isUserLoggedOn()Returnstrue
when a user is logged on to the current session, otherwise returnsfalse
.- Since:
- V4.4
- See Also:
logon(String[][])
-
isUserLoggedOn
boolean isUserLoggedOn(java.lang.String userId)Returnstrue
if the named user is currently logged on to the server, otherwise returnsfalse
.- Since:
- V5.3
-
hasRole
boolean hasRole(java.lang.String roleName)Returnstrue
when a user is logged on and the user has the role identified byroleName
, otherwise returnsfalse
. User roles are established by the System Logon Service when the user logs on.- 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)Returnstrue
when a user is logged on and the user has the authorization identified bytype
,name
andfunction
;otherwise returnsfalse
.This method is only applicable when authorizations have been added by a Logon Service or when the supplied Ebase Security system is used to define users, roles and authorizations. Authorizations represent an alternative to roles and offer more granularity, see
hasRole(String)
.- 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 bycredentialName
, ornull
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.- Since:
- V4.4
- See Also:
checkCredentialValue(String, String)
,logon(String[][])
-
getCredentials
java.util.Map<java.lang.String,java.lang.Object> getCredentials()Returns all of the User credentials that are established by the System Logon Service when the user logs on.- Since:
- V5.7
- See Also:
checkCredentialValue(String, String)
,logon(String[][])
-
checkCredentialValue
boolean checkCredentialValue(java.lang.String credentialName, java.lang.String credentialValue)Returnstrue
if the user credential identified bycredentialName
exists with the valuecredentialValue
, otherwise returnsfalse
. User credentials are established by the System Logon Service when the user logs on.- Since:
- V4.4
- See Also:
getCredential(String)
,logon(String[][])
-
logoff
void logoff()Logs a user off the system, this is the reverse of methodlogon(String[][])
. MethodisUserLoggedOn()
returnsfalse
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.LogonExceptionLogs a user onto the system by calling the default System Logon Service identified in the Server Admin App > Security > User Authentication. 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. ALogonException
contains the error code and error description returned from the Logon Service. These are available as methodsLogonException.getErrorCode()
andLogonException.getMessage()
respectively.When the logon is successful, method
isUserLoggedOn()
returnstrue
, the user name can be obtained using methodgetUserName()
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.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.LogonExceptionLogs 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. ALogonException
contains the error code and error description returned from the Logon Service. These are available as methodsLogonException.getErrorCode()
andLogonException.getMessage()
respectively.When the logon is successful, method
isUserLoggedOn()
returnstrue
, the user name can be obtained using methodgetUserName()
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.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 invokedinParameters
- 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()Returnstrue
when a form has been submitted from the designer, otherwise returnsfalse
.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 methodisUserLoggedOn()
.- Since:
- V4.4
-
updateLoggedOnUser
void updateLoggedOnUser(java.lang.String webServiceName, java.lang.String userId, java.lang.String[][] inParameters) throws com.ebasetech.xi.exceptions.LogonExceptionIf 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.
Javascript example:
try { system.securityManager.updateLoggedOnUser( "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 invokeduserId
- the user id whose sessions are to be updatedinParameters
- 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.LogonExceptionIf 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.
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 updatedinParameters
- 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
-
logonOpenIdConnect
void logonOpenIdConnect(java.lang.String openIdConnectName) throws com.ebasetech.xi.exceptions.LogonExceptionLogon using OpenID Connect. The scope will be used from the OAuth configuration, see OpenID Connect Documentation. OpenID Connect is an extension of OAuth 2.0 Authorization. As part of the specification, the access tokens include an JWT id token. This token is used to determine whether the user is authenticated and holds data about the user that can be extracted.Javascript example:
try { system.securityManager.logonOpenIdConnect("MyAuth"); } catch (e) { event.owner.addErrorMessage(e.javaException.message); }
- Parameters:
openIdConnectName
- the OpenID Connect configured on the server admin- Throws:
com.ebasetech.xi.exceptions.LogonException
- if any error occurs. This exception contains error description returned from the OpenIdConnect authorization.- Since:
- V5.7
-
logonOpenIdConnect
void logonOpenIdConnect(java.lang.String openIdConnectName, java.lang.String scope) throws com.ebasetech.xi.exceptions.LogonExceptionLogon using OpenID Connect. The scope must include openid. see OpenID Connect Documentation. OpenID Connect is an extension of OAuth 2.0 Authorization. As part of the specification, the access tokens include an JWT id token. This token is used to determine whether the user is authenticated and holds data about the user that can be extracted.Javascript example:
try { system.securityManager.logonOpenIdConnect("MyAuth", "openid mail"); } catch (e) { event.owner.addErrorMessage(e.javaException.message); }
- Parameters:
openIdConnectName
- the OpenID Connect configured on the server adminscope
- the OpenID Connect scope, this must contain openid- Throws:
com.ebasetech.xi.exceptions.LogonException
- if any error occurs. This exception contains error description returned from the OpenIdConnect authorization.- Since:
- V5.7
-
logonGatewayAuthentication
boolean logonGatewayAuthentication(java.lang.String gatewayServerName) throws com.ebasetech.xi.exceptions.LogonExceptionLogon using the Gateway Authentication Token. The authorization token is an encrypted Gateway Authentication Token and it is used to determine whether the request is from a specified Gateway Server identified by the Server Admin App > Security > User Authentication. The token contains encrypted information holds data about the user that is extracted to populate the security userid, roles, user credentials and authorizations.Javascript example:
try { system.securityManager.logonGatewayAuthentication("MyRemoteGatewayServer"); } catch (e) { event.owner.addErrorMessage(e.javaException.message); }
- Parameters:
gatewayServerName
- to identify the configuration of remote Gateway Server- Throws:
com.ebasetech.xi.exceptions.LogonException
- if any error occurs. This exception contains an error description if an error occurs authenticating the Gateway Authentication Token.- Since:
- V5.7
-
isGatewayRequest
boolean isGatewayRequest()Returns true if the incoming Http Request contains the Gateway Authentication Token, otherwise false- Since:
- V5.7
-
getKeyManager
KeyManager getKeyManager()Used either generate a HMAC hashed based
or lookup aSecretKey
/PublicKey
from a system keystore or from a remote JSON Web Key (JWK) SetPrivateKey
Javascript example:
var SECRET_KEY = "ytZj2pZxdp26CF4t@sekPr#C?!VJpD!!"; //generate AES
SecretKey
var key = system.securityManager.getKeyManager().generateAESSecretKey(SECRET_KEY);- Returns:
- KeyManager
- Since:
- V5.8
-
getJwtManager
JWTManager getJwtManager()Returns a JWTManager that is used to generate or parsing JSON Web Tokens (
), JSON Signature Tokens (JWT
) or JSON Web Encryption (JWS
)JWE
Javascript example:
var SECRET_KEY = ....; //generates a Hashed Secret key using HMAC with SHA-256 var jwt = system.securityManager.jwtManager.parseToken(oauth, tokenString); ...
- Returns:
- KeyManager
- Since:
- V5.8
-