This migration example assumes a deployed web application is configured to require authentication using FORM based authentication and is referencing a PicketBox based security domain using the UsersRolesLoginModule to load user information from a pair or properties files.
A security domain can be defined in the legacy security subsystem using the following management operations: -
./subsystem=security/security-domain=application-security:add
./subsystem=security/security-domain=application-security/authentication=classic:add(login-modules=[{code=UsersRoles, flag=Required, module-options={usersProperties=file://${jboss.server.config.dir}/example-users.properties, rolesProperties=file://${jboss.server.config.dir}/example-roles.properties}}])
This would result in a security domain definition: -
<security-domain name="application-security">
<authentication>
<login-module code="UsersRoles" flag="required">
<module-option name="usersProperties" value="file://${jboss.server.config.dir}/example-users.properties"/>
<module-option name="rolesProperties" value="file://${jboss.server.config.dir}/example-roles.properties"/>
</login-module>
</authentication>
</security-domain>
It is possible to take a previously defined PicketBox security domain and expose it as an Elytron security realm so it can be wired into a complete Elytron based configuration, if only properties based authentication was to be migrated it would be recommended to jump to the fully migration configuration and avoid the unnecessary dependency on the legacy security subsystem but for situations where that is not immediately possible these commands illustrate an intermediate solution.
These steps assume the original configuration is already in place.
The first step is to add a mapping to an Elytron security realm within the legacy security subsystem.
./subsystem=security/elytron-realm=application-security:add(legacy-jaas-config=application-security)
This results in the following configuration.
<subsystem xmlns="urn:jboss:domain:security:2.0">
...
<elytron-integration>
<security-realms>
<elytron-realm name="application-security" legacy-jaas-config="application-security"/>
</security-realms>
</elytron-integration>
...
</subsystem>
Within the Elytron subsystem a security domain can be defined which references the exported security realm and also a http authentication factory which supports FORM based authentication.
./subsystem=elytron/security-domain=application-security:add(realms=[{realm=application-security}], default-realm=application-security, permission-mapper=default-permission-mapper)
./subsystem=elytron/http-authentication-factory=application-security-http:add(http-server-mechanism-factory=global, security-domain=application-security, mechanism-configurations=[{mechanism-name=FORM}])
And the resulting configuration: -
<subsystem xmlns="urn:wildfly:elytron:1.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
...
<security-domains>
...
<security-domain name="application-security" default-realm="application-security" permission-mapper="default-permission-mapper">
<realm name="application-security"/>
</security-domain>
</security-domains>
...
<http>
...
<http-authentication-factory name="application-security-http" http-server-mechanism-factory="global" security-domain="application-security">
<mechanism-configuration>
<mechanism mechanism-name="FORM"/>
</mechanism-configuration>
</http-authentication-factory>
...
</http>
...
</subsystem>
Finally configuration needs to be added to the Undertow subsystem to map the security domain referenced by the deployment to the newly defined http authentication factory.
./subsystem=undertow/application-security-domain=application-security:add(http-authentication-factory=application-security-http)
Which results in: -
<subsystem xmlns="urn:jboss:domain:undertow:4.0">
...
<application-security-domains>
<application-security-domain name="application-security" http-authentication-factory="application-security-http"/>
</application-security-domains>
...
</subsystem>
Note: If the deployment was already deployed at this point the application server should be reloaded or the deployment redeployed for the application security domain mapping to take effect.
The following command can then be used to verify the mapping was applied to the deployment.
[standalone@localhost:9990 /] ./subsystem=undertow/application-security-domain=application-security:read-resource(include-runtime=true)
{
"outcome" => "success",
"result" => {
"enable-jacc" => false,
"http-authentication-factory" => "application-security-http",
"override-deployment-config" => false,
"referencing-deployments" => ["HelloWorld.war"],
"setting" => undefined
}
}
The deployment being tested here is 'HelloWorld.war' and the output from the previous command shows this deployment is referencing the mapping.
At this stage the previously defined security domain is used for it's LoginModule configuration but this is wrapped by Elytron components which take over authentication.
Alternatively the configuration can be completely defined within the Elytron subsystem, in this case it is assumed none of the previous commands have been executed and this is started from a clean configuration - however if the security domain definition does exist in the legacy security subsystem that will remain completely independent.
First a new security realm can be defined within the Elytron subsystem referencing the files referenced previously: -
./subsystem=elytron/properties-realm=application-properties:add(users-properties={path=example-users.properties, relative-to=jboss.server.config.dir, plain-text=true, digest-realm-name="Application Security"}, groups-properties={path=example-roles.properties, relative-to=jboss.server.config.dir}, groups-attribute=Roles)
As before a security domain and http authentication factory can be defined.
./subsystem=elytron/security-domain=application-security:add(realms=[{realm=application-properties}], default-realm=application-properties, permission-mapper=default-permission-mapper)
./subsystem=elytron/http-authentication-factory=application-security-http:add(http-server-mechanism-factory=global, security-domain=application-security, mechanism-configurations=[{mechanism-name=FORM}])
This results in the following overall configuration.
<subsystem xmlns="urn:wildfly:elytron:1.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
...
<security-domains>
...
<security-domain name="application-security" default-realm="application-properties" permission-mapper="default-permission-mapper">
<realm name="application-properties"/>
</security-domain>
</security-domains>
<security-realms>
...
<properties-realm name="application-properties" groups-attribute="Roles">
<users-properties path="example-users.properties" relative-to="jboss.server.config.dir" digest-realm-name="Application Security" plain-text="true"/>
<groups-properties path="example-roles.properties" relative-to="jboss.server.config.dir"/>
</properties-realm>
</security-realms>
...
<http>
...
<http-authentication-factory name="application-security-http" http-server-mechanism-factory="global" security-domain="application-security">
<mechanism-configuration>
<mechanism mechanism-name="FORM"/>
</mechanism-configuration>
</http-authentication-factory>
...
</http>
...
</subsystem>
As before the application-security-domain mapping should be added to the Undertow subsystem and the server reloaded or the deployment redeployed as required.
./subsystem=undertow/application-security-domain=application-security:add(http-authentication-factory=application-security-http)
Which results in: -
<subsystem xmlns="urn:jboss:domain:undertow:4.0">
...
<application-security-domains>
<application-security-domain name="application-security" http-authentication-factory="application-security-http"/>
</application-security-domains>
...
</subsystem>
At this stage the authentication is the equivalent of the original configuration however now Elytron components are used exclusively.
A legacy security realm can be defined using the following commands to load users passwords and group information from properties files.
./core-service=management/security-realm=ApplicationSecurity:add ./core-service=management/security-realm=ApplicationSecurity/authentication=properties:add(relative-to=jboss.server.config.dir, path=example-users.properties, plain-text=true) ./core-service=management/security-realm=ApplicationSecurity/authorization=properties:add(relative-to=jboss.server.config.dir, path=example-roles.properties)
This results in the following realm definition.
<security-realm name="ApplicationSecurity">
<authentication>
<properties path="example-users.properties" relative-to="jboss.server.config.dir" plain-text="true"/>
</authentication>
<authorization>
<properties path="example-roles.properties" relative-to="jboss.server.config.dir"/>
</authorization>
</security-realm>
A legacy security realm would typically be used to secure either the management interfaces or remoting connectors.
One of the motivations for adding the Elytron based security to the application server is to allow a consistent security solution to be used across the server, to replace the security realm the same steps as described in the previous 'Fully Migrated' section can be followed again up until the http-authentication-factory is defined.
A legacy security realm can also be used for SASL based authentication so a sasl-authentication-factory should also be defined.
./subsystem=elytron/sasl-authentication-factory=application-security-sasl:add(sasl-server-factory=elytron, security-domain=application-security, mechanism-configurations=[{mechanism-name=PLAIN}])
<subsystem xmlns="urn:wildfly:elytron:1.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
...
<sasl>
...
<sasl-authentication-factory name="application-security-sasl" sasl-server-factory="elytron" security-domain="application-security">
<mechanism-configuration>
<mechanism mechanism-name="PLAIN"/>
</mechanism-configuration>
</sasl-authentication-factory>
...
</sasl>
</subsystem>
This can be associated with a Remoting connector to use for authentication and the existing security realm reference cleared.
./subsystem=remoting/http-connector=http-remoting-connector:write-attribute(name=sasl-authentication-factory, value=application-security-sasl) ./subsystem=remoting/http-connector=http-remoting-connector:undefine-attribute(name=security-realm)
<subsystem xmlns="urn:jboss:domain:remoting:4.0">
...
<http-connector name="http-remoting-connector" connector-ref="default" sasl-authentication-factory="application-security-sasl"/>
</subsystem>
If this new configuration was to be used to secure the management interfaces more suitable names should be chosen but the following commands illustrate how to set the two authentication factories and clear the existing security realm reference.
./core-service=management/management-interface=http-interface:write-attribute(name=http-authentication-factory, value=application-security-http) ./core-service=management/management-interface=http-interface:write-attribute(name=http-upgrade.sasl-authentication-factory, value=application-security-sasl) ./core-service=management/management-interface=http-interface:undefine-attribute(name=security-realm)
<management-interfaces>
<http-interface http-authentication-factory="application-security-http">
<http-upgrade enabled="true" sasl-authentication-factory="application-security-sasl"/>
<socket-binding http="management-http"/>
</http-interface>
</management-interfaces>