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: -
./core-service=management/security-realm=LDAPRealm/authentication=ldap/cache=by-access-time:read-resource(include-runtime=true)
{
"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: -
./core-service=management/security-realm=LDAPRealm/authentication=ldap/cache=by-access-time:contains(name=TestUserOne)
{
"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.
./core-service=management/security-realm=LDAPRealm/authentication=ldap/cache=by-access-time:flush-cache(name=TestUserOne)
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">
<authentication>
<ldap connection="MyLdapConnection"
base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org">
<cache type="by-access-time" eviction-time="300"
cache-failures="true" max-cache-size="100"/>
<username-filter attribute="uid"/>
</ldap>
</authentication>
<authorization>
<ldap connection="MyLdapConnection">
<username-to-dn>
<username-filter attribute="uid"
base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org" />
</username-to-dn>
<group-search group-name="SIMPLE" iterative="true"
group-name-attribute="uid">
<group-to-principal search-by="DISTINGUISHED_NAME"
base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"
prefer-original-connection="true">
<membership-filter principal-attribute="uniqueMember"/>
</group-to-principal>
</group-search>
</ldap>
</authorization>
</security-realm>
