Converting Legacy Properties Files into a FileSystemRealm with Elytron Tool
Overview
In WildFly 16, Elytron Tool now provides a command for easily converting any legacy properties files into a FileSystemRealm. This blog post will give an overview of the two ways parameters can be specified for this command, the various parameters, and an example of how to convert both properties files for both a single users-roles mapping and for specifying multiple files at once.
The Two Ways to Specify Parameters
This new command, FileSystemRealmCommand, allows the ability to specify the input files and Elytron object names on either the command line, ideal for a single users-roles combination, or through a text file called a Descriptor File, ideal for multiple users-roles combinations.
In either case, the general use options will have to be specified on the command line, which are:
Both the command line and descriptor file have three required parameters and two optional parameters in relation to the non general use options specified before.
The required parameters are:
--users-file/-u <pathToUsersFile>
--roles-file/-r <pathToRolesFile>
--output-location/-o <pathToOutputDirectory>If the two optional parameters, are not specified then defaults are used of: converted-properties-filesystem-realm and converted-properties-security-domain. The two optional parameters are:
While both the long form option, such as –users-file, and the short form option, respectively -u, are available for the command line input, only the long form option can be used in the Descriptor File. When specifying one of the required parameters on the command line, if the Descriptor File option of –bulk-convert/-b
Using Only the Command Line
To use just the command line to specify inputs for FileSystemRealmCommand is identical to most other command line utilities. Each parameter can be specified in any order with spaces between, other than the input for that parameter having to be specified directly after the name of the parameter with a space between. As mentioned above, the three required parameters must be specified, if they are not then the command will provide an error message stating which parameters are missing.
Example: Command Line Only
For this example, we will use the multiple users file and the multiple roles file in the Appendix section. We will also specify a filesystem-realm name but not a security-domain name, along with having the command give us a summary of the operations
Running this command will give the following output on the command line:
WARNING: No name provided for security-domain, using default security-domain name for conf/users.properties.
----------------------------------------------------------------------------------------------------
Summary for execution of Elytron-Tool command FileSystemRealm
----------------------------------------------------------------------------------------------------
Options were specified via CLI, converting single users-roles combination
Added roles: {role1,role2,role3} for user elytron.
Added roles: {role1,role3,role4,role5} for user javajoe.
Configured script for WildFly named example-fs-realm.sh at realms/example.
The script is using the following names:
Name of filesystem-realm: example-fs-realm
WARNING: No name provided for security-domain, using default security-domain name for conf/users.properties.
----------------------------------------------------------------------------------------------------
End of summary
----------------------------------------------------------------------------------------------------The new Elytron FileSystemRealms will be created in the realms/example directory with the elytron user created under realms/example/e/l and the javajoe user created under realms/example/j/a. The script containing the commands for the WildFly CLI will also be available at realms/example/example-fs-realm.sh and will contain:
/subsystem=elytron/filesystem-realm=example-fs-realm:add(path=/absolute/path/to/realms/example)
/subsystem=elytron/security-domain=converted-properties-security-domain:add(realms=[{realm=example-fs-realm}],default-realm=example-fs-realm,permission-mapper=default-permission-mapper)Using a Descriptor File
FileSystemRealmCommand can also be used by specifying the input through a text file. In this case, the only required option on the CLI is –bulk-convert/-b
Example: Descriptor File
This time, we will again use the multiple users & roles files in the Appendix, but we will also use the single user & role files and the descriptor-file. The options we will use can be seen in the descriptor file, but we will also specify that we want to suppress warnings.
Due to including the –silent, there will be nothing printed to the command line when this command is run. It will create two new directories under realms (if they are not already created) named example-multiple and example-single.
The directory example-multiple will contain two FileSystemRealms, one for elytron under realms/example-multiple/e/l and one for javajoe under realms/example-multiple/j/a similar to the command line only example above. Similarly, it will also create a script file with the WildFly CLI commands under realms/example-multiple/converted-properties-filesystem-realm.sh containing:
/subsystem=elytron/filesystem-realm=converted-properties-filesystem-realm:add(path=/absolute/path/to/realms/example-multiple)
/subsystem=elytron/security-domain=converted-properties-security-domain:add(realms=[{realm=converted-properties-filesystem-realm}],default-realm=converted-properties-filesystem-realm,permission-mapper=default-permission-mapper)The directory example-single will contain one FileSystemRealm, which will be for singleuser under realms/example-single/s/i. As before, it will also create a script file with the WildFly CLI commands under realms/example-single/converted-properties-filesystem-realm.sh containing:
/subsystem=elytron/filesystem-realm=converted-properties-filesystem-realm:add(path=/absolute/path/to/realms/example-single)
/subsystem=elytron/security-domain=nameOfSecurityDomain2:add(realms=[{realm=converted-properties-filesystem-realm}],default-realm=converted-properties-filesystem-realm,permission-mapper=default-permission-mapper)Errors
There are three common ways that an error will be thrown during execution. The first of which is due to a missing required parameter, that is one of users-file, roles-file, and output-location, when using the command line method. The second error is due to the path to the descriptor file, when using the --bulk-convert/-b option, being invalid. A final error is due to the path given to one of the files or the output-location not existing. In all of these cases, Elytron Tool will stop operation with the error code and a message describing the cause.
Warnings
There are several different warnings that can be encountered during the execution of the command, which can be found in the table below. These warnings range from minor ones, such as a default name being used for an optional parameter, to major warnings like a block in the descriptor file being skipped due to missing or invalid required parameters. In all cases, the warning will be outputted to the command line, if the –silent option is not used, during operation, and will be included in the summary after operation is completed, if the –summary option is used, along with being prepended by “WARNING:”.
| Warning | Result | Cause |
|---|---|---|
| Skipping descriptor block <number> <reason> | A block in the descriptor file will be skipped | Missing required parameter or the parameter cannot be found |
| No value found for <param> | <param> will have a value of null | Given <param> has no value specified in the descriptor block or <param> is not a valid parameter |
| Could not find the specified file <file> | The block will be skipped | One of the users-files, roles-files, or output-locations parameters has an invalid path |
| No password were found for user <user> | Indicates that no password was found for a given user resulting in no password protection for that user in the FileSystemRealm | A user in the users-file has a blank entry for the password (i.e. user=) |
| No roles were found for user <user> | Indicates that a user has no roles assigned | A user is listed in the users-file but is unlisted in the roles-file or has a blank entry in it (i.e. user=) |
| Roles were found for user <user>, but user <user> was not defined | Indicates a user has roles but was never defined as a user and so will have no password | A user is listed in the roles-file but not the useres-file |
| Could not create realm for user <user> due to error: <error> | The current block’s FileSystemRealm will not be created | Several causes, most likely being a user has an invalid password |
| No name provided for filesystem-realm, using default filesystem-realm name for <users-file> | The default filesystem-realm name is used in the WildFly CLI commands | No value provided for filesystem-realm-name option |
| No name provided for security-domain, using default security-domain name for <users-file> | The default security-domain name is used in the WildFly CLI commands | No value provided for security-domain-name option |
Using the Created FileSystemRealm for Two-Way SSL
Step-by-Step Instructions
- Use the generated WildFly CLI commands in the <outputLocation> directory you provided in the command input
- Next, create an authentication-factory such as the one provided below
- Thirdly, configure an application-security-domain in the undertow subsystem
- Finally, configure your application’s web.xml and jboss-web.xml files to use the application-security-domain created in the previous step
Using the FileSystemRealm Example
[standalone@localhost:9990 /] /subsystem=elytron/filesystem-realm=single-user-single-role-fs:add(path="/absolute/path/to/output/directory")
{"outcome" => "success"}
[standalone@localhost:9990 /] /subsystem=elytron/security-domain=single-user-single-role-sd:add(realms=[{realm=single-user-single-role-fs}],default-realm=single-user-single-role-fs,permission-mapper=default-permission-mapper)
{"outcome" => "success"}
[standalone@localhost:9990 /] /subsystem=elytron/http-authentication-factory=example-fs-http-auth:add(http-server-mechanism-factory=global,security-domain=single-user-single-role-sd,mechanism-configurations=[{mechanism-name=BASIC,mechanism-realm-configurations=[{realm-name=exampleApplicationDomain}]}])
{"outcome" => "success"}
[standalone@localhost:9990 /] /subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-fs-http-auth)
{"outcome" => "success"}Summary
This blog post provides some information on the new Elytron Tool command FileSystemRealmCommand that helps to migrate legacy properties-files into a FileSystemRealm. The post provides some information on the two ways that input to be provided to the command, how to run the command itself, example command line output, the common errors and warnings that can be encountered, and an example of how to use the output of command in the WildFly CLI to secure applications.
In short, the new tool can either be used solely on the command line for a single users-roles combination or with a descriptor-file for multiple users-roles combinations and multiple FileSystemRealms being created. In both cases, the options of users-file, roles-file, and output-location are mandatory and the options filesystem-realm-name and security-domain-name are optional. In the former case, the options can be provided with the long or short form names and has additional optional options of –help, –debug, –silent, and –summary. In the latter case, the file is organized into blocks with the both cases options, with blocks separated by a new line, and being called with the –bulk-convert/-b option. The latter case also provides the additional options as in the former case, but these are specified file wide alongside the –bulk-convert/-b option.
Appendix
Single User File
singleuser=729463dc24ca5a339330be9e8fbe4ab6
#
#$REALM_NAME=ManagementRealm$Single Role File
singleuser=role1Multiple Users File
elytron=729463dc24ca5a339330be9e8fbe4ab6
javajoe=a424fdb694f978291777d98de4270380
#
#$REALM_NAME=ManagementRealm$Multiple Roles File
elytron=role1,role2,role3
javajoe=role1,role3,role4,role5Descriptor File
users-file:conf/users-multiple.properties
roles-file:conf/roles-multiple.properties
output-location:realms/example-multiple
users-file:conf/users-single.properties
roles-file:conf/roles-single.properties
output-location:realms/example-single
security-domain-name:nameOfSecurityDomain2
Comments
Post a Comment