Chapter 9. Migrating to Elytron

Procedure

1. Define a new security realm in the elytron subsystem that references the PicketBox properties files.

   /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)

2. Define a security domain subsystem in the elytron subsystem.

   /subsystem=elytron/security-domain=application-security:add(realms=[{realm=application-properties}], default-realm=application-properties, permission-mapper=default-permission-mapper)

   This results in the following elytron subsystem configuration in the server configuration file.

   <subsystem xmlns="urn:wildfly:elytron:4.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>
     ...
   </subsystem>

3. Map the application security domain referenced by the deployment to the newly defined HTTP authentication factory in the undertow subsystem.

   /subsystem=undertow/application-security-domain=application-security:add(security-domain=application-security)

   This results in the following undertow subsystem configuration in the server configuration file.

   <subsystem xmlns="urn:jboss:domain:undertow:12.0">
     ...
     <application-security-domains>
       <application-security-domain name="application-security" security-domain="application-security"/>
     </application-security-domains>
     ...
   </subsystem>

4. You must reload the server or redeploy the application for the new application security domain mapping to take effect.

   Authentication is now configured to be equivalent to the PicketBox configuration.

1. Migrate the properties file.

   You can migrate a single user-properties file at a time, or migrate the properties files in bulk. The following examples illustrate the procedures for both types of migration.

   • To migrate a single properties file, do this.

     The following example converts a single users-properties file with the associated roles-properties file to filesystem-realm. The example assumes that the legacy security domain has the following user-properties and role-properties files:

     example-users.properties
     example-roles.properties

     Example: Single user-property file migration

     $./bin/elytron-tool.sh filesystem-realm --users-file example-users.properties --roles-file example-roles.properties --output-location realms/example

     This creates filesystem-realm files and a script containing management CLI commands. The script is stored in the realms/example directory.

   • To migrate multiple properties files do.

     The following example converts the users-properties files with the associated roles-properties files in bulk to filesystem-realm. The example assumes that the legacy security domain has the following properties files:

     users-1.properties
     users-2.properties
     roles-1.properties
     roles-2.properties

     To convert users-roles files in bulk, you must create a descriptor file to use with the filesystem-realm command. For this example, a descriptor file example-descriptor-file located in the /bin directory is created with the following content:

     Example: descriptor file

     users-file:/full/path/to/users-1.properties
     roles-file:/full/path/to/roles-1.properties
     output-location:./realms/bulk-1-example
     filesystem-realm-name:exampleFileSystemRealm1
     security-domain-name:exampleSecurityDomain1
     
     users-file:/full/path/to/users-2.properties
     roles-file:/full/path/to/roles-2.properties
     output-location:./realms/bulk-2-example
     filesystem-realm-name:exampleFileSystemRealm2
     security-domain-name:exampleSecurityDomain2

     A blank line in the descriptor file is used to separate the operations for each users-properties file.

     The following example converts two users-properties files with the associated roles-properties file using a descriptor file to filesystem-realm.

     Example: Bulk migration

     $./bin/elytron-tool.sh filesystem-realm --bulk-convert example-descriptor-file

     This creates the filesystem-realm files and scripts containing the management CLI commands. The scripts are stored in directories specified in the descriptor file’s output-location attribute.

2. Add the new security realm and the security domain to the elytron subsystem using the CLI commands generated by the Elytron tool.

   Example: Adding the filesystem-realm

   /subsystem=elytron/filesystem-realm=converted-properties-filesystem-realm:add(path=/full/path/to/realms/example)
   
   /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)

Procedure

1. Define a connection to LDAP in the elytron subsystem.

   /subsystem=elytron/dir-context=ldap-connection:add(url=ldap://localhost:10389, principal="uid=admin, ou=system", credential-reference={clear-text=secret})

2. Create a security realm to search LDAP and verify the supplied password.

   /subsystem=elytron/ldap-realm=ldap-realm:add(dir-context=ldap-connection, direct-verification=true, identity-mapping={search-base-dn="ou=users, dc=group-to-principal, dc=wildfly, dc=org", rdn-identifier="uid", attribute-mapping=[{filter-base-dn="ou=groups, dc=group-to-principal, dc=wildfly, dc=org", filter="(uniqueMember={1})", from="uid", to="Roles"}]})

   Example elytron subsystem configuration file

   <subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
     ...
     <security-realms>
       ...
       <ldap-realm name="ldap-realm" dir-context="ldap-connection" direct-verification="true">
         <identity-mapping rdn-identifier="uid" search-base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org">
           <attribute-mapping>
             <attribute from="uid" to="Roles" filter="(uniqueMember={1})" filter-base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
           </attribute-mapping>
         </identity-mapping>
       </ldap-realm>
     </security-realms>
     ...
     <dir-contexts>
       <dir-context name="ldap-connection" url="ldap://localhost:10389" principal="uid=admin,ou=system">
         <credential-reference clear-text="secret"/>
       </dir-context>
     </dir-contexts>
   </subsystem>

   Note

   By default, if no role-decoder is defined for a given security-domain, the "Roles" identity attribute is mapped to the identity roles.

   Information loaded from LDAP can now be associated with identities as attributes. These attributes can be mapped to roles, but they can also be loaded and used for other purposes. The newly created security realm can be used in a security domain in the same way as it is described in the Migrate Properties-based Authentication and Authorization to Elytron section of this guide.

Procedure

1. Use the following management command to define the jdbc-realm.

   /subsystem=elytron/jdbc-realm=jdbc-realm:add(principal-query=[ { data-source=ExampleDS, sql="SELECT role, password FROM User WHERE username = ?", attribute-mapping=[{index=1, to=Roles } ] simple-digest-mapper={algorithm=simple-digest-md5, password-index=2} } ] )

   This results in the following jdbc-realm configuration in the elytron subsystem of the server configuration file.

   <subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
     ...
     <security-realms>
       ...
       <jdbc-realm name="jdbc-realm">
         <principal-query sql="SELECT role, password FROM User WHERE username = ?" data-source="ExampleDS">
           <attribute-mapping>
             <attribute to="Roles" index="1"/>
           </attribute-mapping>
           <simple-digest-mapper password-index="2"/>
         </principal-query>
       </jdbc-realm>
       ...
     </security-realms>
     ...
   </subsystem>

   Elytron now manages the database authentication using the JDBC realm configuration. Elytron is more efficient than PicketBox because it uses one SQL query to obtain all of the user attributes and credentials, and then extracts data from the SQL results and creates a mapping of the attributes to use for authentication.

Procedure

1. Define a legacy security realm for Kerberos / GSSAPI SASL authentication to be used for remoting authentication, such as the native management interface.

   Example: Kerberos Authentication for Remoting Management CLI Commands

   /core-service=management/security-realm=Kerberos:add
   /core-service=management/security-realm=Kerberos/server-identity=kerberos:add
   /core-service=management/security-realm=Kerberos/server-identity=kerberos/keytab=remote\/test-server.elytron.org@ELYTRON.ORG:add(path=path/to/remote-test-server.keytab, debug=true)
   /core-service=management/security-realm=Kerberos/authentication=kerberos:add(remove-realm=true)

   Example: Kerberos Remoting Security Realm Configuration

   <management>
     <security-realms>
       ...
       <security-realm name="Kerberos">
         <server-identities>
           <kerberos>
             <keytab principal="remote/test-server.elytron.org@ELYTRON.ORG" path="path/to/remote-test-server.keytab" debug="true"/>
           </kerberos>
         </server-identities>
         <authentication>
           <kerberos remove-realm="true"/>
         </authentication>
       </security-realm>
     </security-realms>
     ...
   </management>

Procedure

1. Define a security realm and wrap the security realm in a caching realm. The caching realm can then be used in a security domain and subsequently in an authentication factory.

   Example: Elytron Security Realm Configuration Commands

   /subsystem=elytron/dir-context=ldap-connection:add(url=ldap://localhost:10389, principal="uid=admin,ou=system", credential-reference={clear-text=secret})
   /subsystem=elytron/ldap-realm=ldap-realm:add(dir-context=ldap-connection, direct-verification=true, identity-mapping={search-base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org", rdn-identifier="uid", attribute-mapping=[{filter-base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org",filter="(uniqueMember={1})",from="uid",to="Roles"}]})
   /subsystem=elytron/caching-realm=cached-ldap:add(realm=ldap-realm)

2. Define a security domain and an HTTP authentication factory that use the cached-ldap realm defined in the previous step.

   Example: Elytron Security Domain and Authentication Factory Configuration Commands

   /subsystem=elytron/security-domain=application-security:add(realms=[{realm=cached-ldap}], default-realm=cached-ldap, 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=BASIC}])

   Note

   You must reference the caching-realm instead of the original realm. Otherwise, caching is bypassed.

   These commands result in the following additions to the server configuration.

   Example: Elytron Cached Security Domain Configuration

   <subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
     ...
     <security-domains>
       ...
       <security-domain name="application-security" default-realm="cached-ldap" permission-mapper="default-permission-mapper">
         <realm name="cached-ldap"/>
       </security-domain>
     </security-domains>
     ...
     <security-realms>
       ....
     <ldap-realm name="ldap-realm" dir-context="ldap-connection" direct-verification="true">
         <identity-mapping rdn-identifier="uid" search-base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org">
           <attribute-mapping>
             <attribute from="uid" to="Roles" filter="(uniqueMember={1})" filter-base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
           </attribute-mapping>
         </identity-mapping>
       </ldap-realm>
       <caching-realm name="cached-ldap" realm="ldap-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="BASIC"/>
         </mechanism-configuration>
       </http-authentication-factory>
       ...
     </http>
      ...
     <dir-contexts>
       <dir-context name="ldap-connection" url="ldap://localhost:10389" principal="uid=admin,ou=system">
         <credential-reference clear-text="secret"/>
       </dir-context>
     </dir-contexts>
     ...

Procedure

1. Create a key-store in the elytron subsystem that specifies the location of the keystore and the password by which it is encrypted. This command assumes the keystore was generated using the keytool command and its type is JKS.

   /subsystem=elytron/key-store=LocalhostKeyStore:add(path=server.keystore,relative-to=jboss.server.config.dir,credential-reference={clear-text="keystore_password"},type=JKS)

2. Create a key-store in the elytron subsystem that specifies the location of the truststore and the password by which it is encrypted. This command assumes the keystore was generated using the keytool command and its type is JKS.

   /subsystem=elytron/key-store=TrustStore:add(path=server.truststore,relative-to=jboss.server.config.dir,credential-reference={clear-text="truststore_password"},type=JKS)

3. Create a key-manager in the elytron subsystem that specifies the previously defined LocalhostKeyStore keystore, the alias, and password of the key.

   /subsystem=elytron/key-manager=LocalhostKeyManager:add(key-store=LocalhostKeyStore,alias-filter=server,credential-reference={clear-text="key_password"})

4. Create a trust-manager in the elytron subsystem that specifies the key-store of the previously created truststore.

   /subsystem=elytron/trust-manager=TrustManager:add(key-store=TrustStore)

5. Create a server-ssl-context in the elytron subsystem that references the previously defined key-manager, sets the trust-manager attribute, and enables client authentication.

   /subsystem=elytron/server-ssl-context=LocalhostSslContext:add(key-manager=LocalhostKeyManager,trust-manager=TrustManager,need-client-auth=true)

6. Update the https-listener to the newly created Elytron ssl-context.

   /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=LocalhostSslContext)

7. Reload the server.

   reload

   This results in the following elytron subsystem configuration in the server configuration file.