Deployed dashboards are protected by the authorization and authentication facilities provided by Apama and your application server.
Apama’s dashboard authentication facility prompts users for credentials before allowing any access to deployed dashboards. It gives you the ability to customize authentication by either configuring your application server to use the security realm and authentication service of your choice or by supplying any JAAS-supported authentication module as a plug-in to the data server or display server. See Administering authentication.
Apama’s authorization facility includes access control that gives you the ability to control who can use a given dashboard. The facility also gives you the ability to control who can use dashboards to gain a given type of access to a given DataView definition, or DataView item. And it gives the ability to control who can send events from dashboards using the Send Event command. See Administering authorization.
In addition to authenticating and authorizing users, you need to consider how you will protect data sent to dashboards. This is discussed in Securing communications.
For dashboards deployed as simple web pages, authentication can be performed by your application server.
For dashboards deployed as local applications, or dashboards using an application server, authentication is performed both at the dashboard and by the data server or display server. When a user starts the Dashboard Viewer, a login dialog appears, which prompts the user for a user name and password (as well as for the host and port of the data server or display server to connect to). The information entered is used to authenticate the user against the authentication service of your choice. Authenticated users are allowed to connect to the server. See Authentication for local and application server deployments for more information.
Whenever a dashboard connects to or disconnects from a data server or display server, the server sends a special notification event to all correlators that are connected to it, provided that your project includes the Dashboard Support bundle. Your monitors can make use of these events to implement further authentication-related administration. See Managing Connect and Disconnect Notification in Managing the dashboard data server and display server.
Authentication for local and application server deployments
Both the Dashboard Viewer and data server or display server provide authentication through the Java Authentication and Authorization Service (JAAS). JAAS provides a pluggable framework for user authentication and authorization.
The JRE provides authentication modules for use with common authentication services such as LDAP and Kerberos. It also supports the development of new authentication modules for use with custom or proprietary authentication services. The data server, display server, and Viewer will work with any authentication module that supports JAAS. This openness allows you to integrate dashboards with your existing authentication service.
Important
Default authentication for local deployments uses a no-op implementation that supports the JAAS login module. All user name/password pairs are authenticated. You can customize authentication for local deployments by supplying your own implementation of the interface javax.security.auth.LoginModule.
Dashboard Login Modules Provided by Apama
Apama provides the following JAAS login modules in the package com.apama.dashboard.security:
NoOpLoginModule: Does no username or password validation. This is used by default for the Dashboard Builder, Viewer, data server, and display server.
UserFileLoginModule: Loads user and role definitions from an XML file. See Installing UserFileLoginModule for more information.
LdapLoginModule: Authenticates against an LDAP service.
In addition, the Java Runtime Environment (JRE) includes several JAAS login modules:
JndiLoginModule: The module prompts for a username and password and then verifies the password against the password stored in a directory service configured under JNDI.
KeyStoreLoginModule: Provides a JAAS login module that prompts for a key store alias and populates the subject with the alias’s principal and credentials.
Krb5LoginModule: This login module authenticates users based on Kerberos protocols.
Developing custom login modules
When developing your implementation of LoginModule, note that the data server and display server’s built-in CallbackHandler currently recognizes only the NameCallback and PasswordCallback.
Installing login modules
NoOpLoginModule is used by default for the Dashboard Builder, Viewer, data server, and display server. To change this, you must install the login module or modules that you want to use instead. To install login modules, do both of the following:
Specify the login modules to use in the file JAAS.ini in the lib directory of your Apama installation.
Create a jar file that includes your LoginModule implementation or implementations, and add the jar or its directory to APAMA_DASHBOARD_CLASSPATH (changes to this environment variable are picked up by dashboard processes only at process startup). You can also use the --dashboardExtraJars command line argument to specify this jar file.
If your login module has dependencies on other .jar files, add these .jar files to the manifest of the login module .jar file.
Info
The login module you install can affect the data server or display server authorization behavior. If you install UserFileLoginModule, for example, the default Scenario authority will provide expanded access to users with the apama_admin role. For such users, it will grant view, edit, and delete access to all instances (in addition to granting such access to Scenario-instance owners). See Providing a login module that supports an Event Authority for more information.
If you are installing a login module provided by Apama (see Dashboard Login Modules Provided by Apama), you do not need to create a jar file as described above, as this class is provided with your Apama installation and is included in an existing jar.
JAAS.ini supports the standard JAAS configuration file format. Each entry in the file associates an application with a login module together with a specification of the module’s parameter values. Here is a JAAS.ini that specifies the UserFileLoginModule for the Dashboard Viewer and data server applications:
Do not change the login module associated with the Dashboard Builder.
Installing UserFileLoginModule
In a JAAS.ini file, you specify a module’s parameter values with expressions of the form formal-parameter=actual-parameter. The login module UserFileLoginModule supports the following parameters:
debug: true or false. Enable debug logging.
validateUser: true or false. Set to false to disable password validation. This is for use in web deployments where authentication is provided by your application server; see Providing a login module that supports an Event Authority. In such a case, configure userFile to specify users for your application server. This results in the application server performing authentication and the data server handling authorization, in such a way that the application server and the data server obtain user-credentials information from the same file.
userFile: Fully resolved name of the file with user and role definitions
refreshDelay: Time in milliseconds to check for changes to the definition file (userFile). When it changes it is reloaded. This allows new users to be added.
Info
Installing UserFileLoginModulecan affect the data server’s authorization behavior. In particular, if you install UserFileLoginModule, the default Scenario authority will provide expanded access to users with the apama_admin role. For such users, it will grant view, edit, and delete access to all instances (in addition to granting such access to Scenario-instance owners).
Installing LdapLoginModule
The LdapLoginModule uses the Java Naming and Directory Interface (JNDI) to access naming and directory services. Oracle’s LDAP provider is supported, and hence the InitialContext must be set up based on Oracle’s implementation. The environment settings must be specified in the JAAS.ini file. Here is an example:
Apama’s dashboard authorization facility includes access control that gives you the ability to restrict who can use a given web-based dashboard.
The example above configures the Dashboard Viewer to use LdapLoginModule.
Following are the supported environment settings:
ProviderURL (required): Specifies the LDAP server and port, which are used to set the java.naming.factory.initial property.
Authentication (required): Specifies the authentication mechanism to use. Specify none, simple, or sasl_mech. This value is used to set the java.naming.security.authentication property;
Anonymous (optional; defaults to true): Specifies whether the userPrincipal and userCredential should be used when creating the LdapContext.
DN (required): Specifies the user principal to be used when accessing the directory. This value is used (after patching with the user name) to set the java.naming.security.principal property. The user entered password is used in java.naming.security.credentials.
The % character is replaced by the login name entered by user.
TLS (required): This specifies whether the LDAP server should start the Transport Security Layer extension. Supply true to specify that it should be started; supply false to specify that it should not be started.
Extra (optional): Allows you to specify any extra parameters for setting the environment before creating the LdapContext. The function of these extra parameters is specific to your LDAP server, not the LdapLoginModule. Supply a semicolon-separated list of name/value pairs, where each pair has the following form
You can also control who can send events from dashboards using the Send Event command. See Send event authorization
For web deployments, some aspects of authorization (in particular, dashboard access control) are centered around the concepts of users and roles, which are introduced in Users and roles.
Users and roles
A user is an individual in a company or organization, who proves their identity to the application server by entering a password known only to them.
A role defines a capability to perform an operation or access to some entity on the application server, and might typically be held by a number of users.
Each user has zero or more associated roles.
For web-based deployments, you create users and roles, and associate roles with users by using your application server.
Predefined roles
There are three predefined Apama roles for web-based deployments which should be assigned to users based on their level of responsibility, trust, and technical competence:
apama_customer
apama_author
apama_admin
The restrictions for these roles can be implemented based on your requirements.
Default DataView access control
By default, only the owner of a DataView item can access it, unless the owner is specified as “*”, in which case all users can access it.
Similarly, when a user attempts to access a DataView item by using a dashboard, view access is authorized if and only if one of the following is true:
The user name supplied during application-server or data server login matches the DataView-item owner.
The DataView-item owner is specified as “*”.
Edit, create, and delete access do not apply to DataView items, but see Send Event Authorization.
Customizing DataView access control
You can customize the DataView access control by supplying a Scenario Authority, an implementation of the interface com.apama.security.IScenarioAuthority. This interface defines the methods canView, canEdit, canDelete, and canCreate, which must be implemented to return true or false for a given user and DataView item. See Providing a Scenario Authority.
You might also need to supply a login module, an implementation of javax.security.LoginModule, in order to endow the instance of javax.security.Subject that represents the current end user with the characteristics that the Event Authority requires. See Providing a login module that supports an Event Authority.
Providing a Scenario Authority
You can provide an alternative to the default Scenario Authority by doing one of the following:
Install com.apama.dashboard.security.NoOpScenarioAuthority, which allows full access by any user. This is useful for testing. See Installing a Scenario Authority.
Below is a description of each IScenarioAuthority method that you must define, including the following:
Signature of the method
When the method is called by the data server
What the method should return
When each method is called depends on whether authorization caching is on — see the -r or --cacheUsers option.
This interface defines the following methods:
public boolean canView (
IUserCredentials credentials,
IScenarioInstance instance
);
canView is called the first time (or, if authorization caching is off, every time) in a data server or display server session that the server sends data from the specified scenario instance or DataView item to an end user with the specified credentials. Your implementation should return true if the user with the specified credentials is authorized to view the specified instance or item; it should return false otherwise.
Note that if caching is off, canView is called very frequently, as specified by the update rate for the data server (see the description of the -u or --updateRate option). If your implementation renders calls to canView expensive, the performance of your dashboard will be significantly affected.
public boolean canEdit (
IUserCredentials credentials,
IScenarioInstance instance
);
canEdit is called the first time (or, if caching is off, every time) a dashboard attempts to edit an instance. Your implementation should return true if the user with the specified credentials is authorized to edit the specified instance; it should return false otherwise. Does not apply to DataView items, but see Send event authorization.
public boolean canDelete (
IUserCredentials credentials,
IScenarioInstance instance
);
canDelete is called the first time (or, if caching is off, every time) a dashboard attempts to delete an instance. Your implementation should return true if the user with the specified credentials is authorized to delete the specified instance; it should return false otherwise. Does not apply to DataView items, but see Send event authorization.
public boolean canCreate (
IUserCredentials credentials,
IScenarioDefinition scenario
);
canCreate is called the first time (or, if caching is off, every time) a dashboard attempts to create a Scenario. Your implementation should return true if the user with the specified credentials is authorized to create an instance of the specified Scenario; it should return false otherwise. Does not apply to DataView items, but see Send event authorization.
Using UserCredential Accessor Methods
Your implementation of IScenarioAuthority will typically use the following public assessor methods of com.apama.dashboard.security.IUserCredentials:
public String getUsername()
public String getPassword()
public Subject getSubject()
Your implementation may also use the following methods of com.apama.services.scenario.IScenarioInstance:
public String getOwner()
public Object getValue(String parameterName)
Compiling Your Scenario Authority
When you compile your implementation of IScenarioAuthority, be sure to put the following jar files on your classpath:
ap-dashboard-client.jar
ap-client.jar
These jar files are in the lib directory of your Apama installation.
Installing a Scenario Authority
To install your authorization customization, do both of the following:
Replace “com.apama.dashboard.security.DefaultScenarioAuthority” with the fully qualified name of your class in the file EXTENSIONS.ini, which is in the lib directory of your Apama installation.
Create a jar file that contains your IScenarioAuthority implementation, and add the jar or its directory to APAMA_DASHBOARD_CLASSPATH (changes to this environment variable are picked up by dashboard processes only at process startup). You can also use the --dashboardExtraJars jarFiles command line argument to specify this jar file.
If your scenario authority has dependencies on other .jar files, add these .jar files to the manifest of the scenario authority .jar file.
If you are installing NoOpScenarioAuthority, you do not need to create a jar file as described above, as this class is provided with your Apama installation and is included in an existing jar.
The EXTENSIONS.ini specifies the scenario authority to use. This file identifies all the user supplied extension classes (including functions and commands). Here is a sample EXTENSIONS.ini:
function com.apama.dashboard.sample.SampleFunctionLibrary
command com.apama.dashboard.sample.SampleCommandLibrary
scenarioAuthority com.apama.dashboard.sample.SampleScenarioAuthority
This file installs a function library, a command library, and a Scenario authority.
If multiple authorities are specified, a user must be authorized by each.
By default, any user is authorized to send any event. However you can create a custom event authority that determines whether a given user is authorized to send a given event. An event authority is a Java class that implements the canSend method of the interface com.apama.dashboard.security.IEventAuthority:
If canSend() returns true the user is allowed to send the event. If it returns false the user is not allowed to send the event and the attempt to send the event is treated as a command failure. Dashboard object property settings determine if this error is displayed to the user.
Using UserCredential accessor methods
Your implementation of IEventAuthority will typically use the following public assessor methods of com.apama.dashboard.security.UserCredentials:
public String getUsername()
public String getPassword()
public Subject getSubject()
Compiling your Event Authority
When you compile your implementation of IEventAuthority, be sure to put the following jar files on your classpath:
ap-dashboard-client.jar
ap-client.jar
These jar files are in the lib directory of your Apama installation.
Installing your Event Authority
To install your authorization customization, do both of the following:
Replace com.apama.dashboard.security.NoOpEventAuthority with the fully qualified name of your class in the file EXTENSIONS.ini, which is in the lib directory of your Apama installation.
create a jar file that contains your IEventAuthority implementation, and place it in the directory %APAMA_WORK%\dashboards_deploy\lib. If you have other custom classes (for example, a custom login module — see Developing custom login modules), you can include them in the same .jar file or in a different .jar file.
If your event authority has dependencies on other .jar files, add these .jar files to the manifest of the event authority .jar file.
Two event authorities are provided with your installation:
com.apama.dashboard.security.NoOpEventAuthority: Permits all users to send any event.
com.apama.dashboard.security.DenyAllEventAuthority: Denies all users rights to send any event.
NoOpEventAuthority is the default event authority. Use a custom event authority when deploying your dashboards.
If you are installing DenyAllEventAuthority, you do not need to create a jar file as described above, as this class is provided with your Apama installation and is included in an existing jar.
Here is a portion of EXTENSIONS.ini as shipped:
# List of event authorities. An event authority is called to determine# if a user has rights to send an event to a correlator. Each must implement# the interface:## com.apama.dashboard.security.IEventAuthority## Multiple authorities can be specified. They will be called in the order# listed.## Format:## eventAuthority <classname>## NoOpEventAuthority - Allows all users to send eventseventAuthority com.apama.dashboard.security.NoOpEventAuthority# DenyAllEventAuthority - Allows no users to send events# eventAuthority com.apama.dashboard.security.DenyAllEventAuthority# eventAuthority <your_class_name_here>
Providing a login module that supports an Event Authority
When you implement an Event Authority, the methods that you implement have a UserCredentials argument. Typical implementations retrieve an instance of javax.security.auth.Subject from the UserCredentials object, and use the Subject’s characteristics to determine whether to return true or false (that is, whether to grant or deny access).
The characteristics of a particular Subject (for example its associated roles, as returned by Subject.getPrinciples) are established by a JAAS login module that is called by the data server or display server. It is this module’s responsibility to establish those characteristics on which the Event Authority will rely.
For local deployments, this login module is responsible for authenticating the current end user (see Authentication for local and application server deployments) as well as for setting the characteristics of the Subject. For web deployments, this login module is responsible only for setting the characteristics of the Subject (since authentication is performed by application server.
For both web and local deployments, the default data server and display server login module is NoOpLoginModule, which does not set any characteristics of the Subject. With this module, the Subject passed into IScenarioAuthority methods has no associated roles.
Typical implementations of LoginModule store the Subject passed into LoginModule.initialize as local state, and set the Subject’s characteristics in LoginModule.commit.
Note that UserFileLoginModule supports Scenario Authorities by setting Subject roles at the time of authentication. To use UserFileLoginModule in order to support Scenario Authorities for web-based deployments (where authentication is performed by the application server), set validateUser to false when you install UserFileLoginModule; see Installing UserFileLoginModule.
For web-based deployments, the data server and display server receive only user names (and not passwords) from the application server. This means that you cannot use a JAAS login module that requires both user names and passwords in order to authenticate users and retrieve their roles. To perform role based authorization for web-based deployments, use a JAAS login module that can retrieve the roles for a user by using only the user name.
Securing communications
For local application deployments, where dashboards communicate directly with the data server, your options for securing dashboard communications include:
Enabling secure sockets (SSL) in the data server.
Utilizing a secure channel (SSH) for all dashboard communication.
Utilizing a virtual public network (VPN) for all dashboard access.
For thin-client deployments, where dashboards communicate through an application server, your options include the following:
Enabling HTTPS in the application server.
Utilizing a virtual public network (VPN) for all dashboard access.
As with all encryption technology, there is a cost in performing the encryption and decryption of data. For applications with a very high frequency of data changes, you should account for this cost when you determine how frequently a dashboard can be updated (see the description of the -u or --update option).
