DataSource monitoring configuration (part 1)

These DataSource configuration items determine who can monitor and manage a DataSource application through JMX, and what objects can be monitored and managed. They apply to all DataSource applications, such as Liberator, Transformer and Integration Adapters.

You would typically monitor and manage the DataSource application from a monitoring client, such as the Caplin Management Console (CMC). The permissions grant or deny a monitoring user, such as someone logged in to the CMC, permission to invoke specific operations on the application’s MBeans.

In DataSource applications built with the current (version 6.1) releases of the DataSource APIs (Caplin Integration Suite, C DataSource API), all monitoring users can read all MBean attributes, though they can’t write to them.

For more DataSource monitoring configuration items, see DataSource Monitoring Configuration (part 2).

add-monuser

add-monuser specifies the credentials that allow a monitoring client application to log into a DataSource application.

Use in: C, Java

There are three ways to specify the credentials (click on an option to see its description in the table below):

Alternative 1:

add-monuser
   user username
   pass password
   roles rolename1,rolename2, ...
end-monuser

Alternative 2:

add-monuser
   user username
   secure-pass encryptedpassword
   roles rolename1,rolename2, ...
end-monuser

Alternative 3 (only applies to Liberator and Transformer):

add-monuser
   user username
   key-id akeyidentifier
   roles rolename1,rolename2, ...
end-monuser
Option Type Default Description

user

string

[none]

A username that the monitoring client application can use to log in to the DataSource application via JMX. If the user and pass options, or user and secure-pass options, or user and key-id options, are not specified, the DataSource application will accept monitoring login requests from any user.

pass

string

[none]

An unencrypted password that the monitoring client application’s user specified in user must supply when logging in to the DataSource application via JMX. The DataSource application uses this option to verify the user’s password.

You must specify a pass option, or a secure-pass option, or (for Liberator and Transformer only) a key-id option.

secure-pass

string

[none]

A secure encryption of the password that the user of the monitoring client application

(as specified in the user option) supplies when logging in to the DataSource application via JMX. The password the user enters must be encrypted before being passed to the DataSource application. The DataSource application uses this option to verify the user’s encrypted password.

The cryptographic formats supported are APR1 (an MD5-based encoding) and Unix Crypt.

You must specify a secure-pass option, or a pass option, or (for Liberator and Transformer only) a key-id option. The secure-pass option overrides the pass option.

Also see Using the secure-pass option below.

key-id

string

[none]

The identifier of a signature key, as specified in the key-id option of an add-sigkey configuration entry.

This option isn’t available in Java-based DataSource applications.

This option can only be used in Liberator and Transformer configuration, and should be used instead of the pass option or secure-pass option when the monitoring client application is to log in using a KeyMaster user credentials token.

The Liberator or Transformer uses this option to verify the user’s user credentials token - see Using the key-id option below.

roles

string

*

A comma separated list of roles that the user can have (no space separators allowed).

A role defines the JMX MBean oprations in the DataSource application that the user can invoke. Roles are associated with MBeans through add-mon-roles configuration items.

The wildcard role * grants the user permission to invoke any of the operations available on any MBeans; this is the default if no roles are specified.

If a user attempts to invoke an operation without having permission, a SecurityException is thrown back to the monitoring client (in the CMC the Exception is flagged in a pop-up), and, provided the DataSource application’s log-monitor-level configuration item is set to at least INFO, details of the user and operation are logged in the DataSource application’s monitoring log file.

In Liberator, the basic configuration file in the install kit contains the following monitoring client login credentials:

add-monuser
   user admin
   pass admin
end-monuser

Using the secure-pass option in add-monuser

Some examples:

  1. Here’s the configuration for a monitoring user called 'admin', with password 'admin' that’s encrypted using the APR1 algorithm:

    add-monuser
   user admin
   secure-pass $apr1$z71X7C20$3B6zCqZLN.WrBWpObcPaj.
end-monuser

  2. This configuration is for monitoring user 'admin2', with password 'admin' that’s encrypted using the Crypt algorithm:

    add-monuser
   user admin2
   secure-pass hPF1s9piPZULA
end-monuser

Using the key-id option in add-monuser

This option can only be used in Liberator and Transformer configuration,

A monitoring client application can be designed so that it logs in to the Liberator or Transformer through KeyMaster, supplying a digitally signed user credentials token instead of a password (for example, the Caplin Management Console can do this). To allow Liberator/Transformer to handle monitoring login requests that have user credentials tokens, specify its add-monuser configuration with the options user and key-id, rather than user and pass. The value of the key-id option must match the key-id value in an add-sigkey configuration item:

add-sigkey
   key-id akeyidentifier
   timeout 600
   keyfile %r/etc/PublicKey.der
   hashing-algorithm md5
end-sigkey

...
add-monuser
   user username
   key-id akeyidentifier
end-monuser

The add-sigkey item specifies a signature checking key. When the JMX enabled monitoring client application logs in, Liberator/Transformer looks for an add-monuser entry with a matching username and then finds the add-sigkey item that has a key-id value matching the key-id in add-monuser. It uses the keyfile option of the add-sigkey item to locate the file containing the user’s public encryption key. The Liberator’s or Transformer’s auth module can then use this public key to validate the digital signature in the user credentials token.

mon-operation-default

The mon-operation-default configuration item sets the default roles (see the role option of add-monuser) that can invoke all the operations on all of the DataSource application’s MBeans.

Use in: C, Java

Type: string

Default value: [none]

Define the roles as a comma separated list with no spaces between the items; for example:

mon-operation-default adminrole,superadminrole,superuserrole

The settings of mon-operation-default are overridden for particular MBeans by the operation-default and operation options within add-mon-roles configuration items.

add-mon-roles

Each add-mon-roles configuration item refers to an MBean or set of MBeans, and specifies which roles grant permission to invoke specific operations on the MBean(s).

Use in: C, Java

Syntax: An add-mon-roles configuration item must contain a beanname option and at least one instance of operation, or operation-default.

For example:

add-mon-roles
   beanname FXAdapter.example:name=bean1
   operation invokeMe adminrole
end-mon-roles
Option Type Default Description

beanname

string

[none]

The name of an MBean object in the DataSource application, which can be monitored and/or managed. This option can also be a partial name that selects a set of MBeans. For an explanation of the formats allowed, see Beanname specifications and precedence below.

operation

string

[none]

The name of an operation on the MBean or MBeans selected by beanname, followed by a comma separated list of roles (see the role option of add-monuser). This list specifies roles (and hence users) that can potentially invoke the operation for the MBeans specified by beanname, subject to the precedence rules for matching beannames defined in Beanname specifications and precedence below.

Example: operation invokeMe adminrole, superadminrole

An operation option overrides, for that particular operation, any operation-default settings in the same add-mon-roles block. In particular, if a role is listed in operation-default, but not in operation, that role cannot invoke the operation. For more about this, see Operation settings and their defaults below.

operation-default

string

[none]

A comma separated list of roles (see the role option of add-monuser). These roles are by default allowed to invoke all the operations on the MBeans specified by beanname, subject to the precedence rules for matching beannames defined in Beanname specifications and precedence below.

Example: operation-default adminrole, superadminrole

The settings of operation-default are overridden by any operation settings in the same add-mon-roles block; see the description of the operation option.

Beanname specifications and precedence

You can specify the beanname option of the add-mon-roles configuration item in one of four ways that define the precedence when matching MBeans to determine users' access to them.

Beanname format

The general format of the beanname option follows the syntax for MBean Object Names:

<domain-in-dot-notation>:<key-property-list>

where <key-property-list> has the form

property1=value,property2=value,...

In the examples on the rest of this page, we’ve assumed that our MBeans have just one property called name, which is the name of the MBean: name=<bean-name>

An example of a beanname that includes the name property is: FXAdapter.example:name=bean1

Because it has a fully specified domain and a <key-property-list>, this beanname specifies the Object Name of an MBean - the MBean called bean1 in the domain FXAdapter.example

You can also define beannames with only partial domains and/or no <key-property-list>. Such beannames have lower precedence when determining the access permissions that roles have to MBean operations - for more about this, see The four beanname specification types below.

The naming convention used at Caplin is for an MBean’s domain to start with the name of the Integration Adapter, as in FXAdapter.example

For more about the syntax of MBean Object Names, and the conventions for them, see the Java documentation page Java Management Extensions (JMX) - Best Practices.

The four beanname specification types

The four ways to specify beannames, and the precedence levels associated with them are:

Precedence level 4 (highest precedence)

Fully specified domain with <key-property-list>.

add-mon-roles
   beanname  FXAdapter.example:name=bean1
   operation invokeMe adminrole
end-mon-roles

In this example, the MBean called bean1 in the domain FXAdapter.example exactly matches the beanname, so for this Integration Adapter, the role adminrole would be allowed to invoke bean1's invokeMe operation. But if this configuration were applied to a Transformer with an MBean called bean1 but the MBean’s domain is Transformer.example, there would be no match and adminrole would be denied access to that MBean’s invokeMe operation.

Precedence 3

Partially specified domain with <key-property-list>.

add-mon-roles
   beanname  .example:name=bean1
   operation invokeMe adminrole
   end-mon-roles

In this example, any MBean called bean1 whose domain ends in .example matches the beanname. So adminrole would be allowed to invoke the invokeMe operation of FXAdapter.example:name=bean1 and Transformer.example:name=bean1, but would be denied access to this operation in Transformer.example:name=bean2.

Precedence 2

Fully specified domain but no <key-property-list>. For example: .example:name=bean1

add-mon-roles
   beanname  FXAdapter.example:
   operation invokeMe adminrole
end-mon-roles

In this example, any MBean in the domain FXAdapter.example matches the beanname. So adminrole would be allowed to invoke the invokeMe operation on any MBean (that has this operation defined for it) in the FXAdapter.example domain. But if this configuration were applied to a Transformer where the domain is Transformer.example, there would be no match and adminrole would be denied access to the invokeMe operation on any of the MBeans having that operation.

Precedence 1 (lowest precedence)

Partially specified domain and no <key-property-list>.

add-mon-roles
   beanname  .example:
   operation invokeMe adminrole
end-mon-roles

In this example, any MBean whose domain ends in .example matches the beanname. So adminrole would be allowed to invoke the invokeMe operation of any MBean (that has this operation defined for it) in the domains FXAdapter.example and Transformer.example

Applying the precedence rules

If your configuration contains multiple instances of add-mon-roles with beannames of different precedences the permissions are applied to roles in the order of precedence as described above. These permissions are not additive; the permissions for a beanname with higher precedence always overwrite those for a beanname with lower precedence.

For example, consider this configuration:

add-monuser
user admin
secure-pass hPF1s9piPZULA   #"admin"
roles adminrole
end-monuser

add-monuser
user user1
pass Apetj.oXzcOrA          #"password"
roles userrole
end-monuser

add-mon-roles
   # Precedence level 1
   beanname  .server.peerstats:
   operation invokeMe adminrole
end-mon-roles

Here the add-mon-roles configuration entry allows the role adminrole (and hence the user called 'admin') to invoke the invokeMe operation on any MBean that has this operation defined for it and that has a domain ending in .server.peerstats

Now consider what happens when we add another add-mon-roles entry with a higher precedence for the beanname match:

...
add-mon-roles
   # Precedence level 1
   beanname  .server.peerstats:
   operation invokeMe adminrole
end-mon-roles

add-mon-roles
   # Precedence level 4
   beanname  FXAdapter.server.peerstats:name=bean1
   operation invokeMe userrole
end-mon-roles

The second add-mon-roles entry has a beanname with both a fully specified domain and a bean object name, so it has the highest precedence (level 4) and overrides the first add-mon-roles entry (which has the lowest possible precedence level of 1). This new entry allows the role userrole (and hence the user called 'user1') to invoke the invokeMe operation, on the MBean called bean1 in the FXAdapter.server.peerstats domain.

Because the permissions in the add-mon-roles entries are not additive, by default this new entry denies role adminrole (and any other roles) access to any of bean1's operations. So to ensure that role adminrole can access bean1 in domain FXAdapter.server.peerstats, we need to add this role to the second add-mon-roles entry:

...
add-mon-roles
   # Precedence level 1
   beanname  .server.peerstats:
   operation invokeMe adminrole
end-mon-roles

add-mon-roles
   # Precedence level 4
   beanname  FXAdapter.server.peerstats:name=bean1
   operation invokeMe adminrole,userrole
end-mon-roles

We add adminrole to the role list in the operation option, so that this role can access invokeMe.

Operation settings and their defaults

The settings of the mon-operation-default configuration item, and the operation-default and operation options of add-mon-roles override each other in the following manner: mon-operation-default is overridden by operation-default which is overridden by operation

In particular, if a role is listed in an operation-default option for a given beanname but there is also an operation option for the same beanname that doesn’t list the role, that role is denied access to the operation.

Example

First, we define a global default:

mon-operation-default superuserrole,adminrole,userrole

mon-operation-default allows the roles superuserrole, adminrole and userrole to invoke any operations on any MBeans.

Now we modify the permissions for a specific type of MBean by adding an add-mon-roles entry:

mon-operation-default superuserrole,adminrole,userrole

add-mon-roles
   beanname  .server.peerstats:name=bean1
   operation-default superuserrole
end-mon-roles

The operation-default option allows superuserrole to invoke all the operations of bean1 MBeans in domains ending in

.server.peerstats, but no other roles (including adminrole and userrole) can do so.

Finally, we modify the permissions for a specific MBean by adding a second add-mon-roles entry:

mon-operation-default superuserrole,adminrole,userrole

add-mon-roles
   beanname  .server.peerstats:name=bean1
   operation-default superuserrole
end-mon-roles

add-mon-roles
   beanname  FXAdapter.server.open:name=open
   operation-default superuserrole,adminrole,userrole
   operation invokeMe userrole2
end-mon-roles

This second add-mon-roles entry defines operation permissions for the MBean called open in the domain FXAdapter.server.open

  • Because the role userrole is listed in the operation-default option, this role can perform all operations on the MBean, except invokeMe (see third bullet point below).

  • The operation-default option overrides the mon-operation-default entry, so we have to add superuserrole and adminrole to the operation-default to ensure that these roles can continue to invoke operations on the MBean (other than invokeMe).

  • The operation option gives role userrole2 permission to invoke the operation invokeMe on the MBean, but superuserrole, adminrole and userrole are denied access to invokeMe because these roles aren’t listed in the option.

See also: