WildFly Properties Realm

December 27, 2020

This article shows how to set up the WildFly Properties Realm referenced in demonstration code on this site. The article will create .properties files and WildFly configuration entries to support secured webapps.

Security is standard with JavaEE. For a webapp, this means setting up protected URL patterns in a web.xml file and applying a security-constraint. Additionally, business logic is protected by annotations that restrict who can run certain methods. (This is called RBAC or "Role-Based Access Control".)

WildFly supports two security models. "Elytron" is the new model and it's more flexible. Specifically, you can use Elytron similarly in the standalone and domain modes of operation. "Legacy" is the prior model and requires different configurations for different modes of operations. This article is on Elytron.

WildFly can be configured to store credentials and authorization mappings in a variety of stores. These are called Realms and includes filesystem-based stores, RDBMS-based stores, LDAP-based stores, and custom stores. The Realm is then used in an Elytron Security Domain. For this article, the Security Domain will rely on defaults, but the Security Domain is flexible can be extended to handle complicated or legacy security models.

The Elytron Security Domain is then mapped to Application Security Domains: Undertow and EJB3. These are the names that will appear in the webapp configuration file "jboss-web.xml"

The Files

Start configuring WildFly but creating two files in the /configuration folder. This example will create "codepen-users.properties" and "codepen-roles.properties". If you're working with the Application and Management Realms that ship with WildFly, you'll do this with the add-user script in bin. You can extend add-user to work with custom .properties files, but you need to have the initial files in place. These are the steps to create initial versions.

In the configuration folder, create a file "codepen-users.properties". codepen-users.properties contains usernames paired with credentials. The credentials are stored as hashes that are made up of a username, a realm, and a password. These tokens are separated by colons. For example,

	
$ echo -n 'codepen:CodePenRealm:dT49An9V' | openssl dgst -md5
(stdin)= 44a3431a674d3fcaee6be5f776c3ddc2	
	

"codepen" is the username. "CodePenRealm" is the realm. "dT49An9V" is the password. The hash starting with 44a343 will be stored with the username "codepen" as in this file codepen-users.properties. The hash is not simply the password.

These are the contents of codepen-users.properties.

#$REALM_NAME=CodePenRealm$ This line is used by the add-user utility to identify the realm name already used in this file.
codepen=44a3431a674d3fcaee6be5f776c3ddc2

The commented out line above the username REALM_NAME is important. That enables WildFly to hash the same input cleartext as is stored in the .properties file.

Next, create the codepen-roles.properties which is a username paired with a list of groups. In this example, there is the username created in codepen-user.properties "codepen" assigned to a single group "codepenuser".

In small organizations, roles and groups are equivalent. However, in larger organizations, the mapping may not be one-to-one.

codepen=codepenuser

You should now have two files in the WildFly /configuration folder: codepen-users.properties and codepen-roles.properties

Realm

Next, start WildFly's jboss-cli tool and connect. Run the following command which creates the Realm. The command tells WildFly where to find the previously-created codepen-users.properties and codepen-roles.properties.

[standalone@localhost:9990 /] /subsystem=elytron/properties-realm=CodePenRealm:add(users-properties={path=codepen-users.properties,relative-to=jboss.server.config.dir},groups-properties={path=codepen-roles.properties,relative-to=jboss.server.config.dir})

Security Domain

With the Realm defined, now associate it with a Elytron Security Domain. When studying the WildFly config files, be aware that there is also a Legacy Security Domain. The Elytron Security Domain is found in the :elytron section and the Legacy in the :security section.

The Security Domain can reference many Realms and has options for advanced permission and role mapping. This set up is more straightforward, dealing with the defaults and a single Realm.

[standalone@localhost:9990 /] /subsystem=elytron/security-domain=CodePenDomain:add(default-realm=CodePenRealm,permission-mapper=default-permission-mapper,realms=[{realm=CodePenRealm,role-decoder=groups-to-roles}])

At this point, Elytron has been configured. There is one more step before this can be used in your web applications.

Application Security Domain

The Application Security Domain is the name used in your web application. This is a facade in front of the Elytron and Legacy Security Domains. This configuration will pair an Elytron Security Domain with an Undertow Application Security Domain.

[standalone@localhost:9990 application-security-domain=CodePenSecurityDomain] /subsystem=undertow/application-security-domain=CodePenSecurityDomain:add(security-domain=CodePenDomain)

If you're using EJBs, you'll need a second Application Security Domain for the EJB3 subsystem. In similar fashion,

[standalone@localhost:9990 application-security-domain] /subsystem=ejb3/application-security-domain=CodePenSecurityDomain:add(security-domain=CodePenDomain)

Verification

Before working with code, you can verify the commands by looking at the HAL Management Console. Starting with the Elytron Realms, the Realm created in this article should have similar entries to the out-of-the-box Application Realm. If that is in order, check the Elytron Security Domain. Make sure that the new Security Domain matches Application Domain. Pay particular attention to "default-permission-mapper" and "groups-to-roles".

This article is the sequence of steps for creating a file-based Properties Realm in WildFly. While a real deployment will use a more capable security store (ex, RDBMS or LDAP), I find the Properties Realm useful in development. You'll find links to this in future articles that will use this Realm in web applications.

---