This tutorial guides you through configuring a caching realm in Elytron to improve authentication performance for your WildFly applications. By caching user credentials retrieved from a separate security realm (e.g., LDAP), you can significantly reduce the load on your identity store and enhance application responsiveness.
Setting up the Base Realm
Securing your WildFly applications often involves user authentication against external identity stores like LDAP servers. While this approach ensures robust security, repeated lookups for frequently accessed users can impact performance. Here’s where caching realms in WildFly Elytron come in.
A Caching Realm requires a Base Realm which we will cache in the Elytron Layer. For the purpose of this tutorial, we will Cache the LDAP Realm discussed in this article: How to configure an Elytron LDAP Realm on WildFly
Therefore, make sure that the Realm “demoLdapRealm” is available before moving on to the next section.
Adding the Caching Realm configuration
Once you have your base realm set up, use the caching-realm add operation within the Elytron subsystem to create a caching realm. This new realm references the existing one for credential lookups.
/subsystem=elytron/caching-realm=exampleCacheRealm:add(realm=demoLdapRealm, maximum-age="60000")
The following properties can be applied to a caching realm:
- maximum-age: The time in milliseconds that an item can stay in the cache.
- maximum-entries: The maximum number of entries to keep in the cache.
In our example, the Caching Realm will keep entries in the cache up to 60000 ms.
After you create the caching-realm, you can then use it in your security configuration just as you would any other security realm. For example, here is how to create a security-domain and the http-autenthication-factory to be added to undertow:
/subsystem=elytron/security-domain=cachedLDAPSD:add(realms=[{realm=exampleCacheRealm, role-decoder=from-roles-attribute}], default-realm=exampleCacheRealm, permission-mapper=default-permission-mapper)
/subsystem=elytron/http-authentication-factory=cached-ldap-http-auth:add(http-server-mechanism-factory=global, security-domain=cachedLDAPSD, mechanism-configurations=[{mechanism-name=BASIC, mechanism-realm-configurations=[{realm-name=RealmUsersRoles}]}])
/subsystem=undertow/application-security-domain=cachedLDAPSD:add(http-authentication-factory=cached-ldap-http-auth)
Here’s an overview of the Caching Realm from the Admistration Console:
Finally, in your application, include the security-domain in jboss-web.xml which uses the cachedLDAPSD:
<security-domain>cachedLDAPSD</security-domain>
Once you authenticate through the Caching Realm, you can verify that the authentication process still works ( until Maximum Age is reached) by shutting down the LDAP Server.
Clearing and updating a caching-realm Cache
You can clear an existing cache by using the clear-cache command. Clearing a cache forces it to repopulate using the latest data from the security realm.
/subsystem=elytron/caching-realm=exampleCacheRealm:clear-cache
Besides, WildFly 32 provides the possibility for the caching realm to authenticate a user with the underlying realm directly when the authentication fails with the cached credential. If the credential verification is successful with the underlying realm, WildFly removes the old credential from cache and put the updated credential to the cache.
When the logger org.wildfly.security.auth is set to TRACE, you should see evidence of this feature in your logs:
19:03:07,960 INFO [org.wildfly.security.auth] (MSC service thread 1-6) verifyEvidence for principal='frank' using cached credential failed, so trying verifyEvidence for principal='frank' using underlying security realm
Conclusion:
By implementing a caching realm, you can significantly improve authentication performance for your WildFly applications, especially for frequently accessed users. Remember to adjust the cache settings based on your expected usage patterns and security requirements.
Note: The book WildFly Administration guide will be soon updated to include all changes available in the latest version of WildFly (32). Subscribe to our mailing list so you don’t miss the announcement!
