Thursday, 28 August 2014

WildFly 8 Security Realms - LDAP Caching

Another feature added to WildFly 8 that you may not be aware of unless you have gone looking for it is the ability to define caches on security realms where LDAP is being used for authentication or group loading.  This was added under WFLY-1523.

If you are familiar with the caching already in place for JAAS based security domains please be aware that the approach taken for the security realms is very different, for JAAS the key to the cache is essentially using the users supplied username and password and the cached value is the entire interaction with LDAP including all of the groups recursively found.  Within the security realms the caching is much more fine grained and it is the results for individual queries which are cached independently rather than the overall result cached as one.  This will be explained further in this post, for now this essentially means that it is possible that the results from queries for one user can be re-used for another user - this would occur where iteratively querying the group membership information of groups.

Base Configuration

Before describing how to enable caching it makes sense to start with an existing security realm already configured to authenticate users against LDAP and load their group membership information from LDAP, the following is one such possible configuration: -

    "core-service" : {
        "management" : {
            "security-realm" : {
                "LDAPRealm" : {
                    "authentication" : {"ldap" : {
                        "allow-empty-passwords" : false,
                        "base-dn" : "...",
                        "connection" : "MyLdapConnection",
                        "recursive" : false,
                        "user-dn" : "dn",
                        "username-attribute" : "uid",
                        "cache" : null
                    "authorization" : {"ldap" : {
                        "connection" : "MyLdapConnection",
                        "group-search" : {"group-to-principal" : {
                            "base-dn" : "...",
                            "group-dn-attribute" : "dn",
                            "group-name" : "SIMPLE",
                            "group-name-attribute" : "uid",
                            "iterative" : true,
                          "principal-attribute" : "uniqueMember",
                            "search-by" : "DISTINGUISHED_NAME",
                            "cache" : null
                        "username-to-dn" : {"username-filter" : {
                            "attribute" : "uid",
                            "base-dn" : "...",
                            "force" : false,
                            "recursive" : false,
                            "user-dn-attribute" : "dn",
                            "cache" : null

This example has been cleaned up slightly but the main point to note is that this configuration has three key areas.

  • Authentication
If you are already using LDAP with security realms this should be the most familiar, effectively during authentication we discover the users distinguished name using this definition and attempt to connect to LDAP using their supplied credential to verify they are who they claim to be.
  • A username-to-dn definition in group search
When it comes to group searching we may rely on the availability of the users distinguished name, this block is not used in all situations but essentially it is a second attempt to discover a users distinguished name, this is more likely to be required if a second form of authentication was supported e.g. local authentication.
  • A group-to-principal group search

Then finally there is the group search definition, in this case it is an iterative search - what that means is that first all of the groups will be identified that the user is directly a member of - after that a search will be performed for each of those groups to identify the groups that those groups are a member of, this process continues until either a cyclic reference is detected or the final groups are not members of any further groups.

Before moving onto the next section please note in the above example there are three points that have a sub resource of "cache" : null , it is at each of these points that a cache can be defined to cache the LDAP interaction for that portion of the model.

The Caches

When enabling a cache it is possible to chose from one of two eviction strategies, the first being by access time and the second by search time.  If you choose by access time then the item in the cache will be evicted from the cache after a certain time period has elapsed since it was last used, if you choose by search time it will be evicted after the configured time has elapsed since the item was added to the cache regardless of if it has been accessed later.

In addition to choosing the eviction strategy the following attributes can also be set on a cache: -

  • eviction-time
This one should be fairly self explanatory and is the time in seconds used for evictions depending on the chosen strategy. 
  • cache-failures
This one is more important for the cache used in the authentication section and controls if the results of failed LDAP searches are cached to prevent the LDAP server from being hit again - this risk here is that without the next attribute a remote user could fill up the cache by trying many different users that do not exist.
  • max-cache-size
In addition to the time based strategy it is also possible to define a maximum size for the cache, if the maximum size of the cache is reached the oldest item in the cache will be evicted to make room for a new item being added - this is the final level of protection to prevent a cache that is caching failures from using up all of the available heap space to cache those failures.

Enabling The Cache 

So that is the description of the different configuration choices you can make, the following is the CLI command you can use to add a cache for the authentication related LDAP access: -

./core-service=management/security-realm=LDAPRealm/authentication=ldap/cache=by-access-time:add(eviction-time=300, cache-failures=true, max-cache-size=100)
This command enabled a cache that caches by access time with items automatically evicted after 5 minutes unless the maximum capacity of 100 items is reached - in addition to that failures are cached so the LDAP server will not be hit repeatedly for authentication attempts where a user is using an invalid user ID.

If the eviction by search time strategy was preferred this could have been achieved just as easily by using the following command: -
./core-service=management/security-realm=LDAPRealm/authentication=ldap/cache=by-search-time:add(eviction-time=300, cache-failures=true, max-cache-size=100)
I am not going to go through all of the other places in the model where caches can be enable but for the remaining two areas the command would be the same with just a modification to the address.

Cache Operations

Once caching is enabled the caches run fairly independently, however there are a couple of additional tasks you may want to perform yourself.  These examples are using the cache I defined above, however with address modifications they are applicable to the additional caches that can be defined.

Inspect The Cache Size

If you want to see how many entries are cached the following command can be executed to include runtime attributes: -

    "outcome" => "success",
    "result" => {
        "cache-failures" => true,
        "cache-size" => 1,
        "eviction-time" => 300,
        "max-cache-size" => 100
This was executed after I authenticated as one user so you can see one entry is in the cache.

Test The Cache Contents

If you want to check if the cache contains a reference to a specific user a command can be executed as follows: -
    "outcome" => "success",
    "result" => true
In this case TestUserOne is the user that I authenticated as.

Flushing The Cache

Finally it is possible to flush items from the cache, either the whole cache can be flushed or individual items can be flushed e.g.
In this case the specific entry was flushed, had the name parameter been omitted from the operation the whole cache would have been flushed.

XML Configuration

That concludes this blog post, to complete this example here is the resulting XML for my security realm definition with the cache now defined: - 

<security-realm name="LDAPRealm">
        <ldap connection="MyLdapConnection" 
            <cache type="by-access-time" eviction-time="300" 
                   cache-failures="true" max-cache-size="100"/>
            <username-filter attribute="uid"/>
        <ldap connection="MyLdapConnection">
               <username-filter attribute="uid"
                    base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org" />
            <group-search group-name="SIMPLE" iterative="true" 
                <group-to-principal search-by="DISTINGUISHED_NAME" 
                    <membership-filter principal-attribute="uniqueMember"/>

Thursday, 21 August 2014

WildFly Command Line Interface - Connection Aliases

A while ago now I added a new feature to the WildFly command line interface to add support for aliases to be defined for connections to servers - I realise however that sometimes when it comes to the CLI capabilities such as this are not as visible until someone actually points out that they exist.

Note: This blog post is written based on WildFly 8.1.0.Final, however this feature was added for WildFly 8.0.0.Final under the following issue WFLY-1850.  This feature is also applicable to later versions of WildFly although most likely using a later version of the schema for configuration.

Configuration File

The first thing that may be new to you is that the command line interface is actually configurable, out of the box we include a base configuration and default settings that are compatible with the application server it is bundled with.

By default the file is called jboss-cli.xml and as of WildFly 8.1.0.Final it is using the following namespace urn:jboss:cli:2.0.

When the CLI starts up a sequence of locations are checked for the location of the configuration file: -

  1. If the system property jboss.cli.config is set it is used as the name of the file, this can either be an absolute path or relative to the CLI's working dir.
  2. The working dir is checked for a file called jboss-cli.xml.
  3. The bin folder of the WildFly installation is checked for a file called jboss-cli.xml.
Failing that a default configuration is assumed not based on any file configuration.

Defining Aliases

The default configuration already contains an example of an alias definition so to define an alias first uncomment this block: -

    <!-- Example controller alias named 'Test'
        <controller name="Test">

For each alias definition four pieces of information can be defined: -

  1. A unique name.
  2. The protocol.
  3. The host name.
  4. The port.

Connecting By Alias

Using an alias is no more complicated than if you were already connecting to servers and specifying a host name.

On starting the CLI you can connect using an alias with a command similar to: -

./ -c --controller=Test

Alternatively start the CLI without any arguments and specify the name of the alias when you call connect e.g.

[disconnected /] connect Test

Why Use Aliases

The next question is why would you want to use aliases.

In the first case if you are administering a number of servers as an example you could have development, staging and production by defining aliases you no longer need to remember the address to use to connect to each of the servers - in addition to that should the address of any of these servers be modified in the future you can update the alias definition and continue to use the command you are used to for connecting to that server.

Secondly and one point I did not mention above, the name of the alias could be an address. So say you have a bunch of scripts that always call connect localhost:9999 - by default the server no longer listens on port 9999, an alias can be used to map this to the correct address.