> Extensible Permissions
> The extensible permissions feature uses the Java virtual machine (JVM) and the Java Access Control Interface (JACI) to allow you to run your own Java-based permissions module in the EMS server.
> Your Permissions Module runs in the JVM within the EMS server, and connects to tibemsd using the JACI interface. Like the LoginModule, the Permissions Module provides an extra layer of security to your EMS application. It does not supersede standard EMS procedures for granting permissions. Instead, the module augments the existing process.
> When a user attempts to perform an action, such as subscribing to a topic or publishing a message, the EMS server checks the acl.conf file, the Permissions Module, and cached results from previous Permissions Module queries, for authorization. This process is described in detail in How Permissions are Granted.
> Cached Permissions
> In order to speed the authorization process, the EMS server caches responses received from the Permissions Module in two pools, the allow cache and the deny cache. Before invoking the Permissions Module, the server first checks these caches for a cache entry matching the user’s request.
> What is Cached
> Each cache entry consists of a username and action, and the authorization result response from the Permissions Module:

> ● | The username is specific; the cached permission applies only to this user.

> ● | The action is also specific. Only one action is included in each cache entry. Actions that require authorization are the same as those listed in the acl.conf file.

> ● | The destination can include wildcards. That is, a single cache entry can determine the user’s authorization to perform the action on multiple destinations.

> If the response from the Permissions Module authorized the action, the permission is cached in the allow cache. If the action was denied, it is cached in the deny cache.
> How Long Permissions are Cached
> Permissions Module results also include timeouts, which determine how long the cache entry is kept in the cache before it expires. When a timeout has expired, the entry is removed from the cache. Because these timeouts are assigned by the Permissions Module, you can control how often the Permissions Module is called, and therefore how much load it puts on the EMS server.

> | Long timeouts on permissions cache entries can increase performance, but they also lower the system’s responsiveness to changes in permissions. Consider timeout lengths carefully when writing your Permissions Module.

> Administering the Cache
> You can view and reset cache statistics, as well as clear all cache entries. These commands are available in the administration tool:

> ● | jaci showstats on page 125

> ● | jaci resetstats on page 125

> ● | jaci clear on page 125

> How Permissions are Granted
> When an EMS client attempts to perform an action that requires permissions, the EMS server looks in each of the following locations in turn:

> 1. | First, the server checks the acl.conf for authorization. This is the standard EMS mechanism for granting permissions, as is documented in Chapter 8, Authentication and Permissions.

> 2. | Next, the server checks the Permissions Module allow cache for authorization. If an entry matching the username, action, and destination exists in the cache, the request is allowed.

> Because destinations with wildcards can exist in the cache, an entry can have a wildcard destination that contains the requested destination. If that entry specifies the same username and action, the request is allowed. For more information on this topic, see Implications of Wildcards on Permissions below.

> 3. | The server then checks the deny cache for a matching entry. If an entry exists in the deny cache, the request is denied.

> As in the allow cache, wildcards used in destinations can result in a cache entry with a destination that contains the requested destination. If that entry matches the username and action, the request is denied. For more information on this topic, see Implications of Wildcards on Permissions below.

> 4. | Finally, if there are no matching entries in either cache, the server passes the username, action type, and destination to the Permissions Module, which returns an allow or deny authorization response. The response is also saved to the cache for the timeout specified in the response.

> If the Permissions Module does not respond to the request within the timeout specified by the jaci_timeout parameter in the tibemsd.conf file, the server denies authorization by default.
> Actions that require permissions are the same as those listed in the acl.conf file, and include operations such as subscribe to a topic and publishing to a queue. Permissions are described in acl.conf on page 212. Figure 17 shows the decision tree the server follows when granting or denying permissions.
> Figure 17 The Permissions Decision Tree

> | In general, permissions are checked when a client initiates an operation. In the case of a browsing request, it’s useful to note that the server reviews permissions only at certain points during the browsing operation. The server checks for browsing permission when a client starts to browse a queue and whenever the client needs to refresh its list of browse-able messages. The client receives the list of messages from the server when it first begins browsing. The server refreshes the list and rechecks permissions whenever the client browses to the end of the current list.

> Durable Subscribers
> When a durable subscriber is disconnected from the EMS server, the server continues to accumulate messages for the client. However, while the client is disconnected, there is no user associated with the durable subscriber. Because of this, the server cannot immediately check permissions for a message that is received when the client is not connected.
> When a user later reconnects to the server and resubscribes to the durable subscription, the server checks permissions for the subscribe operation itself, but all messages in the backlog are delivered to the consumer without additional permission checks.
> Special Circumstances
> There are some special circumstances under which the request, although it is not exactly matched in the acl.conf file, will be denied without reference to either the permissions cache or the Permissions Module. Any request will be denied if, in the acl.conf

> ● | The username exists but is not associated with any destinations.

> ● | The username exists and is associated with destinations, but not with the specific destination in the request.

> ● | The username is part of a group, but the group is not associated with any destinations.

> ● | The username is part of a group and the group is associated with destinations, but not with the specific destination in the request.

> In general entries in the acl.conf file supersede entries in the Permissions Module, allowing you to optimize permission checks in well-defined static cases. When the acl.conf does not mention the user, the Permissions Module is fully responsible for permissions.
> Implications of Wildcards on Permissions
> A permission result from the Permissions Module can allow or deny the user authorization to perform the action on a range of destinations by including wildcards in the destination name. For example, even though the application attempts to have user mwalton publish on topic foo.bar.1, the Permissions Module can grant permission to user mwalton to publish messages to the topic foo.bar.*. For as long as this authorization is cached, mwalton can also publish to the topics foo.bar.baz and foo.bar.boo, because foo.bar.* contains both those topics.
> As long as a permission to perform an action on a destination is cached in the allow cache, the user will be authorized to perform that action, even if the permission is revoked in the external system used by the Permissions Module. This permission also extends to any destination contained by the authorized destination through the use of wildcards. The EMS server checks the allow cache for permissions before checking the deny cache and before sending an uncached permission request to the Permissions Module. In other words, the authorization status cannot be changed until the timeout on the cache entry expires and it is removed from the cache.
> Similarly, an entry in the deny cache remains there until the timeout has expired and the entry is removed. Only then does the EMS server send the request to the Permissions Module, so that a change in status can take effect.
> Overlapping wildcards can make this situation even more complex. For example, consider these three destinations:
> foo.*.baz
> foo.bar.*
> foo.>
> It might seem that, if foo.*.baz were in a cache, then foo.bar.* would match it and permissions for that destination would come from the cache. In fact, however, permissions could not be determined by the cache entry, because foo.bar.* intersects but is not a subset of foo.*.baz. That is, not every destination that matches foo.bar.* will also match foo.*.baz. The destination foo.bar.boo, for example, would be granted permissions by foo.bar.*, but not by foo.*.baz.
> Since not all destinations that foo.bar.* matches will also match foo.*.baz, we say that foo.*.baz intersects foo.bar.*. The cache entry can determine a permission if the requested destination is a subset of the cache entry, but not if it is merely an intersection. In this case, permissions cannot be determined by the cache.
> The destination foo.>, on the other hand, contains as subsets both foo.bar.* and foo.*.baz, because any destination name that matches either foo.bar.* or foo.*.baz will also match foo.>. If foo.> is in the cache, permissions will be determined by the cache.
> Enabling Extensible Permissions
> Extensible permissions are enabled in the EMS server, through parameters in the tibemsd.conf configuration file. The required parameters are:

> ● | authorization—enables authorization.

> ● | jaci_class—specifies the class that implements the Permissions Module.

> ● | jaci_classpath—specifies the JAR files and dependent classes used by the Permissions Module.

> The Permissions Module will be used to grant permissions only to those destinations that are defined as secure in the topics.conf and queues.conf configuration files. If there are no topics or queues that include the secure property, then the Permissions Module will never be called because the server does not check permissions at all.
> Because the Permissions Module runs in the Java virtual machine, you must also enable the JVM in the EMS server. See Enabling the JVM for more information.
> Writing a Permissions Module
> The Permissions Module is a custom module that runs inside the EMS server within a JVM. The Permissions Module is written using JACI, a set of APIs developed by TIBCO Software Inc. that you can use to create a Java module that will authorize EMS client requests. JACI provides the interface between your code and the EMS server. JACI is a standard component of EMS, and JACI classes and interfaces are documented in com.tibco.tibems.tibemsd.security.
> Requirements
> In order to implement extensible permissions, you must write a Permissions Module implementing the JACI interface. There are some requirements for a Permissions Module that will run in the EMS server:

> ● | The Permissions Module must implement the JACI Authorizer interface, which accepts information about the operation to be authorized.

> ● | The Permissions Module must return a permission result, by way of the AuthorizationResult class. Permission results contain:

> − | An allowed parameter, where true means that the request is allowed and false means the request is denied.

> − | A timeout, which determines how long the permission result will be cached. Results can be cached for a time of up to 24 hours, or not at all.

> − | The destination on which the user is authorized to perform the action. The destination returned can be more inclusive than the request. For example, if the user requested to subscribe to the topic foo.bar, the permission result can allow the user to subscribe to foo.*. If a destination is not included in the permission result, then the allow or deny response is limited to the originally requested destination.

> − | The action type that the permission result replies to. For example, authorization to publish to the destination, or authorization to receive messages from a queue. Permissions can be granted to multiple action types, for example permission to publish and subscribe on foo.>. Note that the EMS server creates one cache entry for each action specified in the result.

> ● | The Permissions Module must be thread-safe. That is, the Permissions Module must be able to function both in a multi-threaded environment and in a single-threaded environment.

> ● | The Permissions Module, like the LoginModule, should not employ long operations, and should return values quickly. As these modules become part of the EMS server’s message handling process, slow operations can have a severe effect on performance.

> Documentation of JACI classes and interfaces is available through com.tibco.tibems.tibemsd.security.

Copyright © TIBCO Software Inc. All Rights Reserved.