Chapter 7. Migrating to Elytron in JBoss EAP 7.1

7.1. Overview of Elytron

JBoss EAP 7.1 introduces Elytron, which provides a single unified framework that can manage and configure access for both standalone servers and managed domains. It can also be used to configure security access for applications deployed to JBoss EAP servers.

Important

The architectures of Elytron and the legacy security subsystem that is based on PicketBox are very different. With Elytron, an attempt was made to create a solution that allows you to operate in the same security environments in which you currently operate; however, this does not mean that every PicketBox configuration option has an equivalent configuration option in Elytron.

If you are not able to find information in the documentation to help you achieve similar functionality using Elytron that you had when using the legacy security implementation, you can find help in one of the following ways.

If you have a Red Hat Development subscription, you have access to Support Cases, Solutions, and Knowledge Articles on the Red Hat Customer Portal. You can also open a case with Technical Support and get help from the WildFly community as described below.
If you do not have a Red Hat Development subscription, you can still access Knowledge Articles on the Red Hat Customer Portal. You can also join the user forums and live chat to ask questions of the WildFly community. The WildFly community offerings are actively monitored by the Elytron engineering team.

Your JBoss EAP 7.0 server configuration and deployments that use the legacy security subsystem, which is based on PicketBox, should run without changes on JBoss EAP 7.1. PicketBox continues to support security domains, which allows applications to continue to use existing login modules. Security realms, which are used by the management layer for security, are also carried over and emulated by Elytron. This allows you to define authentication in both the elytron and legacy security subsystems and use them in parallel. For more information about how to configure your application to use Elytron and legacy security, see Configure Web Applications to Use Elytron or Legacy Security for Authentication in How to Configure Identity Management for JBoss EAP.

Even though PicketBox authentication continues to be supported, you are encouraged to switch to Elytron when you are ready to migrate your applications. One of the advantages for using Elytron security is that it provides a consistent security solution across the server and your applications. For information on how to migrate PicketBox authentication and authorization to use Elytron, see Migrate Authentication Configuration in this guide.

For an overview of the new resources that are available in the elytron subsystem, see Resources in the Elytron Subsystem in the JBoss EAP Security Architecture guide.

Important

Be aware that if you do choose to use both the legacy security subsystem and Elytron in your deployments, invocations between deployments using different security architectures is not supported.

For more information about using these subsystems in parallel, see Using Elytron and Legacy Security Subsystems in Parallel in How to Configure Identity Management for JBoss EAP.

7.2. Migrate Secure Vaults and Properties

7.2.1. Migrate Vaults to Secure Credential Storage

The vault that was used to store plain text string encryption in the legacy security subsystem in JBoss EAP 7.0 is not compatible with Elytron in JBoss EAP 7.1, which uses a newly designed credential store to store strings. Credential stores safely encrypt credentials in a storage file outside of the JBoss EAP configuration files. You can use the implementation provided by Elytron or you can customize the configuration using the credential store APIs and SPIs. Each JBoss EAP server can contain multiple credential stores.

Note

If you previously used vault expressions to parameterize nonsensitive data, it is recommended that you replace the data with Elytron security properties.

If you continue to use the legacy security subsystem, you should not need to modify or update your vault data. However, if you plan to migrate your application to use Elytron, you must convert your existing vaults to credential stores so that they can be processed by the elytron subsystem. For more information about credential stores, see Credential Stores in How to Configure Server Security for JBoss EAP.

Migrating Vault Data Using the WildFly Elytron Tool

The WildFly Elytron Tool that ships with JBoss EAP provides a vault command to help you migrate vault content to credential stores. You execute the tool by running the elytron-tool script, which is located in the EAP_HOME/bin directory.

$ EAP_HOME/bin/elytron-tool.sh vault VAULT_ARGUMENTS

If you prefer, you can execute the tool by running the java -jar command.

$ java -jar EAP_HOME/bin/wildfly-elytron-tool.jar vault VAULT_ARGUMENTS

You can use the following command to get a description of all of the available arguments.

$ EAP_HOME/bin/elytron-tool.sh vault --help

Note

The WildFly Elytron Tool cannot handle the first version of the security vault data files.
You can enter the --keystore-password argument in masked format, as shown in the below example to migrate a single vault, or in clear text.
The --salt and --iteration arguments are provided to supply information to decrypt the masked password or to generate a masked password in the output. If the --salt and --iteration arguments are omitted, default values are used.
The --summary argument produces formatted management CLI commands that can be used to add the converted credential stores to the JBoss EAP configuration. Plain text passwords are masked in the summary output.

Important

Be aware that credential stores can only be used for securing passwords. They do not support the vault expression feature that could be used anywhere in the management model.

Choose one of the following migration options:

Migrate a Single Security Vault to a Credential Store

The following is an example of the command used to convert a single security vault to a credential store.

$ EAP_HOME/bin/elytron-tool.sh vault --enc-dir vault_data/ --keystore vault-jceks.keystore --keystore-password MASK-2hKo56F1a3jYGnJwhPmiF5 --iteration 34 --salt 12345678 --alias test --location cs-v1.store --summary

This command converts the security vault to a credential store and prints the summary of the management CLI commands that were used to convert it in the output.

Vault (enc-dir="vault_data/";keystore="vault-jceks.keystore") converted to credential store "cs-v1.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="cs-v1.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="MASK-2hKo56F1a3jYGnJwhPmiF5;12345678;34"})

Migrate Multiple Security Vaults to a Credential Store in Bulk

You can convert multiple vaults to a credential store using the --bulk-convert argument and pointing to a bulk conversion descriptor file.

The examples in this section use the following bulk conversion descriptor file.

Example: bulk-vault-conversion-descriptor.txt File

keystore:vault-v1/vault-jceks.keystore
keystore-password:MASK-2hKo56F1a3jYGnJwhPmiF5
enc-dir:vault-v1/vault_data/
salt:12345678
iteration:34
location:v1-cs-1.store
alias:test

keystore:vault-v1/vault-jceks.keystore
keystore-password:secretsecret
enc-dir:vault-v1/vault_data/
location:v1-cs-2.store
alias:test

# different vault vault-v1-more
keystore:vault-v1-more/vault-jceks.keystore
keystore-password:MASK-2hKo56F1a3jYGnJwhPmiF5
enc-dir:vault-v1-more/vault_data/
salt:12345678
iteration:34
location:v1-cs-more.store
alias:test

A new conversion starts when each new keystore: line is encountered. All options are mandatory except for salt, iteration, and properties.

To perform the bulk conversion and generate output that formats the management CLI commands, execute the following command.

$ EAP_HOME/bin/elytron-tool.sh vault --bulk-convert path/to/bulk-vault-conversion-descriptor.txt --summary

This command converts all of the security vaults specified in the file to a credential store and prints the summary of the management CLI commands that were used to convert them in the output.

Vault (enc-dir="vault-v1/vault_data/";keystore="vault-v1/vault-jceks.keystore") converted to credential store "v1-cs-1.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="v1-cs-1.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="MASK-2hKo56F1a3jYGnJwhPmiF5;12345678;34"})
--------------------------------------

Vault (enc-dir="vault-v1/vault_data/";keystore="vault-v1/vault-jceks.keystore") converted to credential store "v1-cs-2.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="v1-cs-2.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="secretsecret"})
--------------------------------------

Vault (enc-dir="vault-v1-more/vault_data/";keystore="vault-v1-more/vault-jceks.keystore") converted to credential store "v1-cs-more.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="v1-cs-more.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="MASK-2hKo56F1a3jYGnJwhPmiF5;12345678;34"})
--------------------------------------

7.2.2. Migrate Security Properties to Elytron

The examples in this section assume that the group.name and encoding.algorithm security properties are defined as security-properties in the legacy security subsystem as follows.

Example: Security Properties Defined in the security Subsystem

<subsystem xmlns="urn:jboss:domain:security:2.0">
    ...
    <security-properties>
        <property name="group.name" value="engineering-group" />
        <property name="encoding.algorithm" value="BASE64" />
    </security-properties>
</subsystem>

To define the same security properties in the elytron subsystem, set the security-properties attribute of the elytron subsystem using the following management CLI command.

/subsystem=elytron:write-attribute(name=security-properties, value={ group.name = "engineering-group", encoding.algorithm = "BASE64" })

This configures the following security-properties in the elytron subsystem in the server configuration file.

<subsystem xmlns="urn:wildfly:elytron:1.2" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
    <security-properties>
        <security-property name="group.name" value="engineering-group"/>
        <security-property name="encoding.algorithm" value="BASE64"/>
    </security-properties>
    ...
</subsystem>

The write-attribute operation used in the previous command overwrites the existing properties. To add or change a security property without impacting other security properties, use the map operation in the management CLI command.

/subsystem=elytron:map-put(name=security-properties, key=group.name, value=technical-support)

In a similar manner, you can remove a specific security property by using the map-remove operation.

/subsystem=elytron:map-remove(name=security-properties, key=group.name)

7.3. Migrate Authentication Configuration

7.3.1. Migrate Properties-based Authentication and Authorization to Elytron

7.3.1.1. Migrate PicketBox Properties-based Configuration to Elytron

This section describes how to migrate PicketBox properties-based authentication to Elytron. You can choose to partially migrate properties-based authentication by only exposing the PicketBox security domain to Elytron or you can fully migrate the properties-based authentication configurations to use Elytron.

The following procedures assume that the deployed web application you plan to migrate is configured to require form-based authentication. The application is referencing a PicketBox security domain and is using the UsersRolesLoginModule to load user information from the example-users.properties and example-roles.properties files. These examples also assume that the security domain is defined in the legacy security subsystem using the following management CLI commands.

Example: PicketBox Properties-based Configuration Commands

/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 results in the following server configuration.

Example: PicketBox Properties-based Security Domain Configuration

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

Choose one of the following migration options:

Partially Migrate by Exposing the PicketBox Security Domain to Elytron

You can expose a PicketBox security domain as an Elytron security realm so that it can be wired into an Elytron configuration; however, doing so creates a dependency on the legacy security subsystem. If you are only migrating properties-based authentication, it is recommended that you fully migrate the application to Elytron to avoid the unnecessary dependency on the legacy security subsystem. However, a partial migration can be an intermediate solution when it is not possible to fully migrate the application to use Elytron.

Follow this procedure to add an existing PicketBox security realm configuration as an Elytron security realm.

Add a mapping to the Elytron security realm within the legacy security subsystem.

/subsystem=security/elytron-realm=application-security:add(legacy-jaas-config=application-security)

This configures the following Elytron security realm in the security subsystem of the server configuration file.

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

Define a security domain in the elytron subsystem that references the exported security realm and an HTTP authentication factory that 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=DIGEST,mechanism-realm-configurations=[{realm-name=RealmName}]}]

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

<subsystem xmlns="urn:wildfly:elytron:1.2" 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="DIGEST">
          <mechanism-realm realm-name="RealmName"/>
        </mechanism>
      </mechanism-configuration>
    </http-authentication-factory>
    ...
  </http>
  ...
</subsystem>

Map the 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(http-authentication-factory=application-security-http)

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

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

If the application was already deployed prior to this configuration, you must reload the server or redeploy the application for the new application security domain mapping to take effect.

Verify the mapping was applied to the deployment using the following management CLI command. The deployment used in this example is HelloWorld.war. The output from the this command shows this deployment is referencing the Elytron mapping.

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

At this stage, the previously defined security domain is used for its LoginModule configuration, but it is wrapped by Elytron components, which take over authentication.

Fully Migrate Properties-based Authentication to Elytron

Follow these steps to fully migrate the PicketBox properties-based authentication to Elytron. This procedure assumes you are starting with the legacy configuration described in the introduction to this section and have not migrated to the partially migrated solution. When you have complete this process, any security domain definition that exists in the legacy security subsystem remains completely independent from the Elytron configuration.

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)

Define a security domain subsystem and an HTTP authentication factory in the elytron subsystem.

/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 elytron subsystem configuration in the server configuration file.

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

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(http-authentication-factory=application-security-http)

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

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

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; however Elytron components are now used exclusively for authentication.

7.3.1.2. Migrate Legacy Properties-based Configuration to Elytron

This section describes how to migrate a legacy security realm that loads user, password, and group information from properties files to Elytron. This type of legacy security realm is typically used to secure either the management interfaces or remoting connectors.

These examples assume that the legacy security domain is defined using the following management CLI commands.

Example: Legacy Security Realm Commands

/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 server configuration.

Example: Legacy Security Realm Configuration

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

One of the motivations for adding the Elytron security to the application server is to allow a consistent security solution to be used across the server. The initial steps to migrate a properties-based legacy security realm to Elytron are similar to those used to migrate a PicketBox properties-based authentication to Elytron. Follow these steps to migrate a properties-based legacy security realm to Elytron.

Define a new security realm in the elytron subsystem that references the 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)

Define a security domain subsystem and an HTTP authentication factory in the elytron subsystem.

/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 Elytron configuration.

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

Define a sasl-authentication-factory so that the legacy security realm can also be used for Simple Authentication Security Layer (SASL) authentication.

/subsystem=elytron/sasl-authentication-factory=application-security-sasl:add(sasl-server-factory=elytron, security-domain=application-security, mechanism-configurations=[{mechanism-name=PLAIN}])

This results in the following Elytron configuration.

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

Configure a remoting connector for the SASL authentication and remove the association with the legacy security realm.

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

This results in the following configuration in the remoting subsystem of the server configuration file.

<subsystem xmlns="urn:jboss:domain:remoting:4.0">
  ...
  <http-connector name="http-remoting-connector" connector-ref="default" sasl-authentication-factory="application-security-sasl"/>
</subsystem>

Add the two authentication factories and remove the legacy security realm references to secure the http-interface with Elytron.

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

This results in the following configuration.

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

Note

You should choose more suitable names than those used in these examples when securing management interfaces.

The migration of the legacy properties-based configuration to Elytron is now complete.

7.3.2. Migrate LDAP Authentication Configuration to Elytron

This section describes how to migrate legacy LDAP authentication to Elytron so that it can manage the information as identity attributes. Much of the information provided in the section entitled Migrate Properties-based Authentication and Authorization to Elytron applies here, particularly regarding how to define security domains and authentication factories, and how to map them to be used for authentication. This section does not repeat those instructions, so be sure to read through that section before you continue.

The following examples assume that group or role information is loaded directly from LDAP and that the legacy LDAP authentication is configured as follows.

The LDAP server contains the following user and group entries.

Example: LDAP Server User Entries

dn: uid=TestUserOne,ou=users,dc=group-to-principal,dc=wildfly,dc=org
objectClass: top
objectClass: inetOrgPerson
objectClass: uidObject
objectClass: person
objectClass: organizationalPerson
cn: Test User One
sn: Test User One
uid: TestUserOne
userPassword: {SSHA}UG8ov2rnrnBKakcARVvraZHqTa7mFWJZlWt2HA==

Example: LDAP Server Group Entries

dn: uid=GroupOne,ou=groups,dc=group-to-principal,dc=wildfly,dc=org
objectClass: top
objectClass: groupOfUniqueNames
objectClass: uidObject
cn: Group One
uid: GroupOne
uniqueMember: uid=TestUserOne,ou=users,dc=group-to-principal,dc=wildfly,dc=org

For authentication purposes the user name is matched against the uid attribute and the resulting group name is taken from the uid attribute of the group entry.

The connection to the LDAP server and related security realm is defined using the following management CLI commands.

Example: LDAP Security Realm Configuration Commands

batch
/core-service=management/ldap-connection=MyLdapConnection:add(url="ldap://localhost:10389", search-dn="uid=admin,ou=system", search-credential="secret")

/core-service=management/security-realm=LDAPRealm:add
/core-service=management/security-realm=LDAPRealm/authentication=ldap:add(connection="MyLdapConnection", username-attribute=uid, base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org")

/core-service=management/security-realm=LDAPRealm/authorization=ldap:add(connection=MyLdapConnection)
/core-service=management/security-realm=LDAPRealm/authorization=ldap/username-to-dn=username-filter:add(attribute=uid, base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org")
/core-service=management/security-realm=LDAPRealm/authorization=ldap/group-search=group-to-principal:add(base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org", iterative=true, prefer-original-connection=true, principal-attribute=uniqueMember, search-by=DISTINGUISHED_NAME, group-name=SIMPLE, group-name-attribute=uid)
run-batch

This results in the following server configuration.

Example: LDAP Security Realm Configuration

<management>
  <security-realms>
    ...
    <security-realm name="LDAPRealm">
      <authentication>
        <ldap connection="MyLdapConnection" base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org">
          <username-filter attribute="uid"/>
        </ldap>
      </authentication>
      <authorization>
        <ldap connection="MyLdapConnection">
          <username-to-dn>
            <username-filter base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org" attribute="uid"/>
          </username-to-dn>
          <group-search group-name="SIMPLE" iterative="true" group-name-attribute="uid">
            <group-to-principal search-by="DISTINGUISHED_NAME" base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org" prefer-original-connection="true">
              <membership-filter principal-attribute="uniqueMember"/>
            </group-to-principal>
          </group-search>
        </ldap>
      </authorization>
    </security-realm>
  </security-realms>
  <outbound-connections>
    <ldap name="MyLdapConnection" url="ldap://localhost:10389" search-dn="uid=admin,ou=system" search-credential="secret"/>
  </outbound-connections>
  ...
</management>

The following management CLI commands are used to configure a PicketBox security domain, which uses the LdapExtLoginModule to verify a user name and password.

Example: Security Domain Configuration Commands

/subsystem=security/security-domain=application-security:add
/subsystem=security/security-domain=application-security/authentication=classic:add(login-modules=[{code=LdapExtended, flag=Required, module-options={ java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory, java.naming.provider.url=ldap://localhost:10389, java.naming.security.authentication=simple, bindDN="uid=admin,ou=system", bindCredential=secret, baseCtxDN="ou=users,dc=group-to-principal,dc=wildfly,dc=org", baseFilter="(uid={0})", rolesCtxDN="ou=groups,dc=group-to-principal,dc=wildfly,dc=org", roleFilter="(uniqueMember={1})", roleAttributeID="uid" }}])

This results in the following server configuration.

Example: Security Domain Configuration

<subsystem xmlns="urn:jboss:domain:security:2.0">
  ...
  <security-domains>
    ...
    <security-domain name="application-security">
      <authentication>
        <login-module code="LdapExtended" flag="required">
          <module-option name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
          <module-option name="java.naming.provider.url" value="ldap://localhost:10389"/>
          <module-option name="java.naming.security.authentication" value="simple"/>
          <module-option name="bindDN" value="uid=admin,ou=system"/>
          <module-option name="bindCredential" value="secret"/>
          <module-option name="baseCtxDN" value="ou=users,dc=group-to-principal,dc=wildfly,dc=org"/>
          <module-option name="baseFilter" value="(uid={0})"/>
          <module-option name="rolesCtxDN" value="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
          <module-option name="roleFilter" value="(uniqueMember={1})"/>
          <module-option name="roleAttributeID" value="uid"/>
        </login-module>
      </authentication>
    </security-domain>
  </security-domains>
</subsystem>

7.3.2.1. Migrate the Legacy LDAP Authentication to Elytron

Follow these steps to migrate the previous LDAP authentication example configuration to Elytron. This section applies to the migration of a legacy security LDAP realm as well as a PicketBox LDAP security domain.

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

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"}]})

These steps result in the following elytron subsystem configuration in the server configuration file.

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

7.3.3. Migrate Database Authentication Configuration to Elytron

This section describes how to migrate JDBC datasource-based PicketBox authentication to Elytron. Much of the information provided in the section entitled Migrate Properties-based Authentication and Authorization to Elytron applies here, particularly regarding how to define security domains and authentication factories, and how to map them to be used for authentication. This section does not repeat those instructions, so be sure to read through that section before you continue.

The following examples assume that the user authentication data is stored in a database table created using syntax similar to the following example.

Example: Syntax to Create the Database User Table

CREATE TABLE User (
    id BIGINT NOT NULL,
    username VARCHAR(255),
    password VARCHAR(255),
    role ENUM('admin', 'manager', 'user'),
    PRIMARY KEY (id),
    UNIQUE (username)
)

For authentication purposes the username is matched against data stored in the username column, the password is expected to be stored as a hex-encoded MD5 hash in the password column, and the user role for authorization purposes is stored in the role column.

The PicketBox security domain is configured to use a JBDC datasource to retrieve data from the database table, and then use it to verify the username and password, and to assign roles. Assume the PicketBox security domain is configured using the following management CLI commands.

Example: PicketBox Database LoginModule Configuration Commands

/subsystem=security/security-domain=application-security:add
/subsystem=security/security-domain=application-security/authentication=classic:add( login-modules=[ { code=Database, flag=Required, module-options={ dsJndiName="java:jboss/datasources/ExampleDS", principalsQuery="SELECT password FROM User WHERE username = ?", rolesQuery="SELECT role, 'Roles' FROM User WHERE username = ?", hashAlgorithm=MD5, hashEncoding=base64 } } ] )

This results in the following login-module configuration in the legacy security subsystem.

Example: PicketBox LoginModule Configuration

<subsystem xmlns="urn:jboss:domain:security:2.0">
  <security-domains>
    ...
    <security-domain name="application-security">
      <authentication>
        <login-module code="Database" flag="required">
          <module-option name="dsJndiName" value="java:jboss/datasources/ExampleDS"/>
          <module-option name="principalsQuery" value="SELECT password FROM User WHERE username = ?"/>
          <module-option name="rolesQuery" value="SELECT role, 'Roles' FROM User WHERE username = ?"/>
          <module-option name="hashAlgorithm" value="MD5"/>
          <module-option name="hashEncoding" value="base64"/>
        </login-module>
      </authentication>
    </security-domain>
  </security-domains>
</subsystem>

7.3.3.1. Migrate the Legacy Database Authentication to Elytron

To migrate the previous database authentication example configuration to Elytron, you must define a JDBC realm to enable JDBC datasource access by Elytron.

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:1.2" 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.

7.3.4. Migrate Kerberos Authentication to Elytron

When working with a Kerberos configuration, the JBoss EAP server can rely on configuration information from the environment, or the key configuration can be specified using system properties. This section discusses how to migrate Kerberos HTTP and Kerberos SASL authentication.

The examples that follow assume that Kerberos is configured using the following system properties. These system properties are applicable to both the legacy configuration and the migrated Elytron configuration.

Example: Kerberos System Properties Management CLI Commands

# Enable debugging
/system-property=sun.security.krb5.debug:add(value=true)
# Identify the Kerberos realm to use
/system-property=java.security.krb5.realm:add(value=ELYTRON.ORG)
# Identify the address of the KDC
/system-property=java.security.krb5.kdc:add(value=kdc.elytron.org)

Example: Kerberos System Properties Server Configuration

<system-properties>
  <property name="sun.security.krb5.debug" value="true"/>
  <property name="java.security.krb5.realm" value="ELYTRON.ORG"/>
  <property name="java.security.krb5.kdc" value="kdc.elytron.org"/>
</system-properties>

Choose one of the following migration options:

Migrate Kerberos HTTP Authentication

In legacy security configurations, you can define a security realm to enable SPNEGO authentication for the HTTP management interface as follows.

Example: Enable SPNEGO authentication for the HTTP management interface

/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=HTTP\/test-server.elytron.org@ELYTRON.ORG:add(path=/path/to/test-server.keytab, debug=true)
/core-service=management/security-realm=Kerberos/authentication=kerberos:add(remove-realm=true)

Example: Kerberos Security Realm Configuration

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

You can also define a pair of legacy security domains to allow applications to use Kerberos HTTP authentication.

Example: Define Multiple Security Domains

# Define the first security domain
/subsystem=security/security-domain=host:add
/subsystem=security/security-domain=host/authentication=classic:add
/subsystem=security/security-domain=host/authentication=classic/login-module=1:add(code=Kerberos, flag=Required, module-options={storeKey=true, useKeyTab=true, principal=HTTP/test-server.elytron.org@ELYTRON.ORG, keyTab=path/to/test-server.keytab, debug=true}

# Define the second SPNEGO security domain
/subsystem=security/security-domain=SPNEGO:add
/subsystem=security/security-domain=SPNEGO/authentication=classic:add
/subsystem=security/security-domain=SPNEGO/authentication=classic/login-module=1:add(code=SPNEGO, flag=requisite,  module-options={password-stacking=useFirstPass, serverSecurityDomain=host})
/subsystem=security/security-domain=SPNEGO/authentication=classic/login-module=1:write-attribute(name=module, value=org.jboss.security.negotiation)
/subsystem=security/security-domain=SPNEGO/authentication=classic/login-module=2:add(code=UsersRoles, flag=required, module-options={password-stacking=useFirstPass, usersProperties=  /path/to/kerberos/spnego-users.properties, rolesProperties=  /path/to/kerberos/spnego-roles.properties, defaultUsersProperties=  /path/to/kerberos/spnego-users.properties, defaultRolesProperties=  /path/to/kerberos/spnego-roles.properties})

Example: Configuration Using a Pair of Security Domains

<subsystem xmlns="urn:jboss:domain:security:2.0">
  <security-domains>
    ...
    <security-domain name="host">
      <authentication>
        <login-module name="1" code="Kerberos" flag="required">
          <module-option name="storeKey" value="true"/>
          <module-option name="useKeyTab" value="true"/>
          <module-option name="principal" value="HTTP/test-server.elytron.org@ELYTRON.ORG"/>
          <module-option name="keyTab" value="/path/to/test-server.keytab"/>
          <module-option name="debug" value="true"/>
        </login-module>
      </authentication>
    </security-domain>
    <security-domain name="SPNEGO">
      <authentication>
        <login-module name="1" code="SPNEGO" flag="requisite" module="org.jboss.security.negotiation">
          <module-option name="password-stacking" value="useFirstPass"/>
          <module-option name="serverSecurityDomain" value="host"/>
        </login-module>
        <login-module name="2" code="UsersRoles" flag="required">
          <module-option name="password-stacking" value="useFirstPass"/>
          <module-option name="usersProperties" value="path/to/kerberos/spnego-users.properties"/>
          <module-option name="rolesProperties" value="  /path/to/kerberos/spnego-roles.properties"/>
          <module-option name="defaultUsersProperties" value="  /path/to/kerberos/spnego-users.properties"/>
          <module-option name="defaultRolesProperties" value="  /path/to/kerberos/spnego-roles.properties"/>
        </login-module>
      </authentication>
    </security-domain>
  </security-domains>
</subsystem>

The legacy applications are then deployed referencing the SPNEGO security domain and secured with the SPNEGO mechanism.

Migrate the Kerberos HTTP Authentication to Elytron

Both the management interface and applications can be secured in Elytron by using a security realm and a Kerberos security factory.

Define a security realm to be used to load identity information.

/subsystem=elytron/properties-realm=spnego-properties:add(users-properties={path=path/to/spnego-users.properties, plain-text=true, digest-realm-name=ELYTRON.ORG}, groups-properties={path=path/to/spnego-roles.properties})

Define a Kerberos security factory that allows the server to load its own Kerberos identity.

/subsystem=elytron/kerberos-security-factory=test-server:add(path=path/to/test-server.keytab, principal=HTTP/test-server.elytron.org@ELYTRON.ORG, debug=true)

Define a security domain to pull together the policy as well as an HTTP authentication factory for the authentication policy.

/subsystem=elytron/security-domain=SPNEGODomain:add(default-realm=spnego-properties, realms=[{realm=spnego-properties, role-decoder=groups-to-roles}], permission-mapper=default-permission-mapper)
/subsystem=elytron/http-authentication-factory=spnego-http-authentication:add(security-domain=SPNEGODomain, http-server-mechanism-factory=global,mechanism-configurations=[{mechanism-name=SPNEGO, credential-security-factory=test-server}])

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

Example: Migrated Elytron Configuration

<subsystem xmlns="urn:wildfly:elytron:1.2" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-domains>
  ...
    <security-domain name="SPNEGODomain" default-realm="spnego-properties" permission-mapper="default-permission-mapper">
      <realm name="spnego-properties" role-decoder="groups-to-roles"/>
    </security-domain>
  </security-domains>
  <security-realms>
    ...
    <properties-realm name="spnego-properties">
      <users-properties path="path/to/spnego-users.properties" digest-realm-name="ELYTRON.ORG" plain-text="true"/>
      <groups-properties path="path/to/spnego-roles.properties"/>
    </properties-realm>
  </security-realms>
  <credential-security-factories>
    <kerberos-security-factory name="test-server" principal="HTTP/test-server.elytron.org@ELYTRON.ORG" path="path/to/test-server.keytab" debug="true"/>
  </credential-security-factories>
  ...
  <http>
    ...
    <http-authentication-factory name="spnego-http-authentication" http-server-mechanism-factory="global" security-domain="SPNEGODomain">
      <mechanism-configuration>
        <mechanism mechanism-name="SPNEGO" credential-security-factory="test-server"/>
      </mechanism-configuration>
    </http-authentication-factory>
    ...
  </http>
  ...
</subsystem>

To secure the application, define an application security domain in the undertow subsystem to map security domains to this http-authentication-factory. The HTTP management interface can be updated to reference the http-authentication-factory defined in this configuration. This process is documented in the Migrate Properties-based Authentication and Authorization to Elytron section of this guide.

Migrate Kerberos Remoting SASL Authentication

It is possible to 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>

Migrate the Kerberos Remoting SASL Authentication to Elytron

The steps to define the equivalent Elytron configuration are very similar to those described in Migrate Kerberos HTTP Authentication.

Define a security realm to be used to load identity information.

/path=kerberos:add(relative-to=user.home, path=src/kerberos)
/subsystem=elytron/properties-realm=kerberos-properties:add(users-properties={path=kerberos-users.properties, relative-to=kerberos, digest-realm-name=ELYTRON.ORG}, groups-properties={path=kerberos-groups.properties, relative-to=kerberos})

Define the Kerberos security factory for the server’s identity.

/subsystem=elytron/kerberos-security-factory=test-server:add(relative-to=kerberos, path=remote-test-server.keytab, principal=remote/test-server.elytron.org@ELYTRON.ORG)

Define the security domain and a SASL authentication factory.

/subsystem=elytron/security-domain=KerberosDomain:add(default-realm=kerberos-properties, realms=[{realm=kerberos-properties, role-decoder=groups-to-roles}], permission-mapper=default-permission-mapper)
/subsystem=elytron/sasl-authentication-factory=gssapi-authentication-factory:add(security-domain=KerberosDomain, sasl-server-factory=elytron, mechanism-configurations=[{mechanism-name=GSSAPI, credential-security-factory=test-server}])

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

<subsystem xmlns="urn:wildfly:elytron:1.2" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-domains>
    ...
    <security-domain name="KerberosDomain" default-realm="kerberos-properties" permission-mapper="default-permission-mapper">
      <realm name="kerberos-properties" role-decoder="groups-to-roles"/>
    </security-domain>
  </security-domains>
  <security-realms>
   ...
     <properties-realm name="kerberos-properties">
       <users-properties path="kerberos-users.properties" relative-to="kerberos" digest-realm-name="ELYTRON.ORG"/>
       <groups-properties path="kerberos-groups.properties" relative-to="kerberos"/>
     </properties-realm>
   </security-realms>
   <credential-security-factories>
     <kerberos-security-factory name="test-server" principal="remote/test-server.elytron.org@ELYTRON.ORG" path="remote-test-server.keytab" relative-to="kerberos"/>
   </credential-security-factories>
   ...
   <sasl>
     ...
     <sasl-authentication-factory name="gssapi-authentication-factory" sasl-server-factory="elytron" security-domain="KerberosDomain">
       <mechanism-configuration>
         <mechanism mechanism-name="GSSAPI" credential-security-factory="test-server"/>
       </mechanism-configuration>
     </sasl-authentication-factory>
     ...
   </sasl>
 </subsystem>

The management interface or remoting connectors can now be updated to reference the SASL authentication factory.

The two Elytron examples defined here could also be combined to use a shared security domain and security realm and just use protocol-specific authentication factories each referencing their own Kerberos security factory.

7.3.5. Migrate Composite Stores to Elytron

This section describes how to migrate a PicketBox or legacy security realm configuration that uses multiple identity stores to Elytron. When using either PicketBox or the legacy security realms, it is possible to define a configuration where authentication is performed against one identity store while the information used for authorization is loaded from a different store. When migrating to Elytron, this can be achieved by using an aggregate security realm.

The following examples perform user authentication using the example-users.properties properties file, and then query LDAP to load the group and role information.

Note

The configurations shown are based on the examples in the following sections, which provide additional background information:

PicketBox Composite Store Configuration

The PicketBox security domain for this scenario is configured using the following management CLI commands.

Example: PicketBox Configuration Commands

/subsystem=security/security-domain=application-security:add

/subsystem=security/security-domain=application-security/authentication=classic:add(login-modules=[ {code=UsersRoles, flag=Required, module-options={ password-stacking=useFirstPass, usersProperties=file://${jboss.server.config.dir}/example-users.properties}} {code=LdapExtended, flag=Required, module-options={ password-stacking=useFirstPass, java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory, java.naming.provider.url=ldap://localhost:10389, java.naming.security.authentication=simple, bindDN="uid=admin,ou=system", bindCredential=secret, baseCtxDN="ou=users,dc=group-to-principal,dc=wildfly,dc=org", baseFilter="(uid={0})", rolesCtxDN="ou=groups,dc=group-to-principal,dc=wildfly,dc=org",roleFilter="(uniqueMember={1})", roleAttributeID="uid" }}])

This results in the following server configuration.

Example: PicketBox Security Domain Configuration

<security-domain name="application-security">
  <authentication>
    <login-module code="UsersRoles" flag="required">
      <module-option name="password-stacking" value="useFirstPass"/>
      <module-option name="usersProperties" value="file://${jboss.server.config.dir}/example-users.properties"/>
    </login-module>
    <login-module code="LdapExtended" flag="required">
      <module-option name="password-stacking" value="useFirstPass"/>
      <module-option name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
      <module-option name="java.naming.provider.url" value="ldap://localhost:10389"/>
      <module-option name="java.naming.security.authentication" value="simple"/>
      <module-option name="bindDN" value="uid=admin,ou=system"/>
      <module-option name="bindCredential" value="secret"/>
      <module-option name="baseCtxDN" value="ou=users,dc=group-to-principal,dc=wildfly,dc=org"/>
      <module-option name="baseFilter" value="(uid={0})"/>
      <module-option name="rolesCtxDN" value="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
      <module-option name="roleFilter" value="(uniqueMember={1})"/>
      <module-option name="roleAttributeID" value="uid"/>
    </login-module>
  </authentication>
</security-domain>

See Elytron Aggregate Security Realm Configuration for how to configure an aggregate security realm in the elytron subsystem to accomplish this.

Legacy Security Realm Composite Store Configuration

The legacy security realm configuration for this scenario is configured using the following management CLI commands.

Example: Legacy Security Realm Configuration Commands

/core-service=management/ldap-connection=MyLdapConnection:add(url="ldap://localhost:10389", search-dn="uid=admin,ou=system", search-credential="secret")

/core-service=management/security-realm=ApplicationSecurity:add
/core-service=management/security-realm=ApplicationSecurity/authentication=properties:add(path=example-users.properties, relative-to=jboss.server.config.dir, plain-text=true)

batch
/core-service=management/security-realm=ApplicationSecurity/authorization=ldap:add(connection=MyLdapConnection)
/core-service=management/security-realm=ApplicationSecurity/authorization=ldap/username-to-dn=username-filter:add(attribute=uid, base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org")
/core-service=management/security-realm=ApplicationSecurity/authorization=ldap/group-search=group-to-principal:add(base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org", iterative=true, prefer-original-connection=true, principal-attribute=uniqueMember, search-by=DISTINGUISHED_NAME, group-name=SIMPLE, group-name-attribute=uid)
run-batch

This results in the following server configuration.

Example: Legacy Security Realm Configuration

<security-realms>
  ...
  <security-realm name="ApplicationSecurity">
    <authentication>
      <properties path="example-users.properties" relative-to="jboss.server.config.dir" plain-text="true"/>
    </authentication>
    <authorization>
      <ldap connection="MyLdapConnection">
        <username-to-dn>
          <username-filter base-dn="ou=users,dc=group-to-principal,dc=wildfly,dc=org" attribute="uid"/>
        </username-to-dn>
        <group-search group-name="SIMPLE" iterative="true" group-name-attribute="uid">
          <group-to-principal search-by="DISTINGUISHED_NAME" base-dn="ou=groups,dc=group-to-principal,dc=wildfly,dc=org" prefer-original-connection="true">
            <membership-filter principal-attribute="uniqueMember"/>
          </group-to-principal>
        </group-search>
      </ldap>
    </authorization>
  </security-realm>
</security-realms>
<outbound-connections>
  <ldap name="MyLdapConnection" url="ldap://localhost:10389" search-dn="uid=admin,ou=system" search-credential="secret"/>
</outbound-connections>

See Elytron Aggregate Security Realm Configuration for how to configure an aggregate security realm in the elytron subsystem to accomplish this.

Elytron Aggregate Security Realm Configuration

The equivalent Elytron configuration for this scenario is configured using the following management CLI commands.

Example: Elytron 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/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"})

/subsystem=elytron/aggregate-realm=combined-realm:add(authentication-realm=application-properties, authorization-realm=ldap-realm)

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

This results in the following server configuration.

Example: Elytron Configuration

<subsystem xmlns="urn:wildfly:elytron:1.2" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <security-domains>
    ...
    <security-domain name="application-security" default-realm="combined-realm" permission-mapper="default-permission-mapper">
      <realm name="combined-realm"/>
    </security-domain>
  </security-domains>
  <security-realms>
    <aggregate-realm name="combined-realm" authentication-realm="application-properties" authorization-realm="ldap-realm"/>
      ...
      <properties-realm name="application-properties">
        <users-properties path="example-users.properties" relative-to="jboss.server.config.dir" digest-realm-name="Application Security" plain-text="true"/>
      </properties-realm>
      <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>
  ...
  <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>
</subsystem>

In the elytron subsystem, an aggregate-realm has been defined that specifies which security realms to use for authentication and which to use for authorization decisions.

7.3.6. Migrate Security Domains That Use Caching to Elytron

When using PicketBox, it is possible to define a security domain and enable in-memory caching for its access. This allows you to access the identity data in memory and avoids additional direct access to the identity store. It is possible to achieve a similar configuration with Elytron. This section describes how to configure security domain caching when using Elytron.

PicketBox Cached Security Domain Configuration

The following commands show how to configure a PicketBox security domain that enables caching.

Example: PicketBox Cached Security Domain Commands

/subsystem=security/security-domain=application-security:add(cache-type=default)
/subsystem=security/security-domain=application-security/authentication=classic:add(login-modules=[{code=LdapExtended, flag=Required, module-options={ java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory, java.naming.provider.url=ldap://localhost:10389, java.naming.security.authentication=simple, bindDN="uid=admin,ou=system", bindCredential=secret, baseCtxDN="ou=users,dc=group-to-principal,dc=wildfly,dc=org", baseFilter="(uid={0})", rolesCtxDN="ou=groups,dc=group-to-principal,dc=wildfly,dc=org", roleFilter="(uniqueMember={1})", roleAttributeID="uid" }}])

This results in the following server configuration.

Example: PicketBox Cached Security Domain Configuration

<subsystem xmlns="urn:jboss:domain:security:2.0">
  <security-domains>
    ...
    <security-domain name="application-security" cache-type="default">
      <authentication>
        <login-module code="LdapExtended" flag="required">
          <module-option name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
          <module-option name="java.naming.provider.url" value="ldap://localhost:10389"/>
          <module-option name="java.naming.security.authentication" value="simple"/>
          <module-option name="bindDN" value="uid=admin,ou=system"/>
          <module-option name="bindCredential" value="secret"/>
          <module-option name="baseCtxDN" value="ou=users,dc=group-to-principal,dc=wildfly,dc=org"/>
          <module-option name="baseFilter" value="(uid={0})"/>
          <module-option name="rolesCtxDN" value="ou=groups,dc=group-to-principal,dc=wildfly,dc=org"/>
          <module-option name="roleFilter" value="(uniqueMember={1})"/>
          <module-option name="roleAttributeID" value="uid"/>
        </login-module>
      </authentication>
    </security-domain>
  </security-domains>
</subsystem>

Note

This command and resulting configuration is similar to the example shown in Migrate LDAP Authentication Configuration to Elytron; however, here the attribute cache-type is defined with a value of default. The default cache type is an in-memory cache. When using PicketBox, you can also specify a cache-type of infinispan, however this type is not supported with Elytron.

Elytron Cached Security Domain Configuration

Follow the steps below to create a similar configuration that caches a security domain when using Elytron.

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)

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

In this step, it is important that you 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:1.2" 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>
  ...

7.3.7. Migrate JACC Security to Elytron

By default, JBoss EAP uses the legacy security subsystem to configure the Java Authorization Contract for Containers (JACC) policy provider and factory. The default configuration maps to implementations from PicketBox.

The elytron subsystem provides a built-in policy provider based on the JACC specification. Before you configure your server to allow Elytron to manage JACC configurations and other policies, you must first disable JACC in the legacy security subsystem by using the following management CLI command.

/subsystem=security:write-attribute(name=initialize-jacc, value=false)

Failure to do so can result in the following error in the server log: MSC000004: Failure during stop of service org.wildfly.security.policy: java.lang.StackOverflowError.

For information about how to enable JACC and define a JACC policy provider in the elytron subsystem, see Enabling JACC Using the elytron Subsystem in the Development Guide for JBoss EAP.

7.4. Migrate Application Clients

7.4.1. Migrate a Naming Client Configuration to Elytron

This section describes how to migrate a client application that performs a remote JNDI lookup using an org.jboss.naming.remote.client.InitialContext class, which is backed by an org.jboss.naming.remote.client.InitialContextFactory class, to Elytron.

The following examples assume that the InitialContextFactory class is created by specifying properties for the user credentials and for the URL of the naming provider that it connects to.

Example: InitialContext Code Used in the Previous Release

Properties properties = new Properties();
properties.put(Context.INITIAL_CONTEXT_FACTORY, "org.jboss.naming.remote.client.InitialContextFactory");
properties.put(Context.PROVIDER_URL,"http-remoting://127.0.0.1:8080");
properties.put(Context.SECURITY_PRINCIPAL, "bob");
properties.put(Context.SECURITY_CREDENTIALS, "secret");
InitialContext context = new InitialContext(properties);
Bar bar = (Bar) context.lookup("foo/bar");
...

You can choose from one of the following migration approaches:

7.4.1.1. Migrate the Naming Client Using the Configuration File Approach

Follow these steps to migrate your naming client to Elytron using the configuration approach.

Create a wildfly-config.xml file in the client application META-INF/ directory. The file should contain the user credentials that are to be used when establishing a connection to the naming provider.

Example: wildfly-config.xml File

<configuration>
  <authentication-client xmlns="urn:elytron:1.0.1">
    <authentication-rules>
      <rule use-configuration="namingConfig">
        <match-host name="127.0.0.1"/>
      </rule>
    </authentication-rules>
    <authentication-configurations>
      <configuration name="namingConfig">
        <set-user-name name="bob"/>
        <credentials>
          <clear-password password="secret"/>
        </credentials>
      </configuration>
    </authentication-configurations>
  </authentication-client>
</configuration>

Create an InitialContext as in the following example. Note that the InitialContext is backed by the org.wildfly.naming.client.WildFlyInitialContextFactory class.

Example: InitialContext Code

Properties properties = new Properties();
properties.put(Context.INITIAL_CONTEXT_FACTORY,"org.wildfly.naming.client.WildFlyInitialContextFactory");
properties.put(Context.PROVIDER_URL,"remote+http://127.0.0.1:8080");
InitialContext context = new InitialContext(properties);
Bar bar = (Bar) context.lookup("foo/bar");
...

7.4.1.2. Migrate the Naming Client Using the Programmatic Approach

Using this approach, you provide the user credentials that are used to establish a connection to the naming provider directly in the application code.

Example: Code Using the Programmatic Approach

// Create the authentication configuration
AuthenticationConfiguration namingConfig = AuthenticationConfiguration.empty().useName("bob").usePassword("secret");

// Create the authentication context
AuthenticationContext context = AuthenticationContext.empty().with(MatchRule.ALL.matchHost("127.0.0.1"), namingConfig);

// Create a callable that creates and uses an InitialContext
Callable<Void> callable = () -> {
    Properties properties = new Properties();
    properties.put(Context.INITIAL_CONTEXT_FACTORY,"org.wildfly.naming.client.WildFlyInitialContextFactory");
    properties.put(Context.PROVIDER_URL,"remote+http://127.0.0.1:8080");
    InitialContext context = new InitialContext(properties);
    Bar bar = (Bar) context.lookup("foo/bar");
    ...
    return null;
};

// Use the authentication context to run the callable
context.runCallable(callable);

7.4.2. Migrate an EJB Client to Elytron

This migration example assumes that the client application is configured to invoke an EJB deployed to a remote server using a jboss-ejb-client.properties file. This file, which is located in the client application META-INF/ directory, contains the following information needed to connect to the remote server.

Example: jboss-ejb-client.properties File

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=127.0.0.1
remote.connection.default.port = 8080
remote.connection.default.username=bob
remote.connection.default.password=secret

The client looks up the EJB and calls one of its methods using code similar to the following example.

Example: Client Code That Calls a Remote EJB

// Create an InitialContext
Properties properties = new Properties();
properties.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
InitialContext context = new InitialContext(properties);

// Look up the EJB and invoke one of its methods
RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.lookup(
    "ejb:/ejb-remote-server-side//CalculatorBean!" + RemoteCalculator.class.getName());
int sum = statelessRemoteCalculator.add(101, 202);

You can choose from one of the following migration approaches:

7.4.2.1. Migrate the EJB Client Using the Configuration File Approach

Follow these steps to migrate your naming client to Elytron using the configuration approach.

Configure a wildfly-config.xml file in the client application META-INF/ directory. The file should contain the user credentials that are to be used when establishing a connection to the naming provider.

Example: wildfly-config.xml File

<configuration>
  <authentication-client xmlns="urn:elytron:1.0.1">
    <authentication-rules>
      <rule use-configuration="ejbConfig">
        <match-host name="127.0.0.1"/>
      </rule>
    </authentication-rules>
    <authentication-configurations>
      <configuration name="ejbConfig">
        <set-user-name name="bob"/>
        <credentials>
          <clear-password password="secret"/>
        </credentials>
      </configuration>
    </authentication-configurations>
  </authentication-client>
  <jboss-ejb-client xmlns="urn:jboss:wildfly-client-ejb:3.0">
    <connections>
      <connection uri="remote+http://127.0.0.1:8080" />
    </connections>
  </jboss-ejb-client>
</configuration>

Create an InitialContext as in the following example. Note that the InitialContext is backed by the org.wildfly.naming.client.WildFlyInitialContextFactory class.

Example: InitialContext Code

// Create an InitialContext
Properties properties = new Properties();
properties.put(Context.INITIAL_CONTEXT_FACTORY,"org.wildfly.naming.client.WildFlyInitialContextFactory");
InitialContext context = new InitialContext(properties);

// Look up an EJB and invoke one of its methods
// Note that this code is the same as before
RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.lookup(
    "ejb:/ejb-remote-server-side//CalculatorBean!" + RemoteCalculator.class.getName());
int sum = statelessRemoteCalculator.add(101, 202);----

You can now delete the obsolete jboss-ejb-client.properties file as that file is no longer needed.

7.4.2.2. Migrate the EJB Client Using the Programmatic Approach

Using this approach, you provide the information needed to connect to the remote server directly in the application code.

Example: Code Using the Programmatic Approach

// Create the authentication configuration
AuthenticationConfiguration ejbConfig = AuthenticationConfiguration.empty().useName("bob").usePassword("secret");

// Create the authentication context
AuthenticationContext context = AuthenticationContext.empty().with(MatchRule.ALL.matchHost("127.0.0.1"), ejbConfig);

// Create a callable that invokes the EJB
Callable<Void> callable = () -> {

    // Create an InitialContext
    Properties properties = new Properties();
    properties.put(Context.INITIAL_CONTEXT_FACTORY, "org.wildfly.naming.client.WildFlyInitialContextFactory");
    properties.put(Context.PROVIDER_URL, "remote+http://127.0.0.1:8080");
    InitialContext context = new InitialContext(properties);

    // Look up the EJB and invoke one of its methods
    // Note that this code is the same as before
    RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.lookup(
        "ejb:/ejb-remote-server-side//CalculatorBean!" + RemoteCalculator.class.getName());
    int sum = statelessRemoteCalculator.add(101, 202);
    ...
    return null;
};

// Use the authentication context to run the callable
context.runCallable(callable);

You can now delete the obsolete jboss-ejb-client.properties file as that file is no longer needed.

7.5. Migrate SSL Configurations

7.5.1. Migrate a Simple SSL Configuration to Elytron

If you secured HTTP connections to the JBoss EAP server using a security realm, you can migrate that configuration to Elytron using the information provided in this section.

The following examples assume you have the following keystore configured in the security-realm.

Example: SSL Configuration Using a Security Realm Keystore

<security-realm name="ApplicationRealm">
  <server-identities>
    <ssl>
      <keystore path="server.keystore" relative-to="jboss.server.config.dir" keystore-password="keystore_password" alias="server" key-password="key_password" />
    </ssl>
  </server-identities>
</security-realm>

Follow the steps below to achieve the same configuration using Elytron.

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

Create a key-manager in the elytron subsystem that specifies the key-store defined in the previous step, 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"})

Create a server-ssl-context in the elytron subsystem that references the key-manager that was defined in the previous step.
```
/subsystem=elytron/server-ssl-context=LocalhostSslContext:add(key-manager=LocalhostKeyManager)
```

Switch the https-listener from the legacy security-realm to the newly created Elytron ssl-context.

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

Reload the server.
```
reload
```

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

<subsystem xmlns="urn:wildfly:elytron:1.2" ...>
  ...
  <tls>
    <key-stores>
      <key-store name="LocalhostKeyStore">
        <credential-reference clear-text="keystore_password"/>
        <implementation type="JKS"/>
        <file path="server.keystore" relative-to="jboss.server.config.dir"/>
      </key-store>
    </key-stores>
    <key-managers>
      <key-manager name="LocalhostKeyManager" key-store="LocalhostKeyStore"  alias-filter="server">
        <credential-reference clear-text="key_password"/>
      </key-manager>
    </key-managers>
    <server-ssl-contexts>
      <server-ssl-context name="LocalhostSslContext" key-manager="LocalhostKeyManager"/>
    </server-ssl-contexts>
  </tls>
</subsystem>

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

<https-listener name="https" socket-binding="https" ssl-context="LocalhostSslContext" enable-http2="true"/>

For more information, see Elytron Subsystem and How to Secure the Management Interfaces in How to Configure Server Security for JBoss EAP.

7.5.2. Migrate Client-Cert SSL Authentication to Elytron

If you configured Client-Cert SSL authentication using a security realm truststore, you can migrate that configuration to Elytron using the information provided in this section.

The steps below assume you have the following truststore configured in the security-realm.

Example: SSL Configuration Using Security Realm Truststore

<security-realm name="ApplicationRealm">
  <server-identities>
    <ssl>
      <keystore path="server.keystore" relative-to="jboss.server.config.dir" keystore-password="keystore_password" alias="server" key-password="key_password" />
    </ssl>
  </server-identities>
  <authentication>
    <truststore path="server.truststore" relative-to="jboss.server.config.dir" keystore-password="truststore_password" />
    <local default-user="$local"/>
    <properties path="application-users.properties" relative-to="jboss.server.config.dir"/>
  </authentication>
  <authorization>
    <properties path="application-roles.properties" relative-to="jboss.server.config.dir"/>
  </authorization>
</security-realm>

Important

The steps below only provide configuration to prevent users without a valid certificate and a private key from accessing the server. They do not configure user identity to authenticate to the server. It is assumed that you have already configured CLIENT-CERT HTTP authentication and external SASL authentication for user identity authentication.

Follow these steps to configure the server to prevent users without a valid certificate and private key from accessing the server using Elytron.

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

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"})

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

Switch the https-listener from the legacy security-realm to the newly created Elytron ssl-context.

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

Reload the server.
```
reload
```

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

<subsystem xmlns="urn:wildfly:elytron:1.2" ...>
  ...
  <tls>
    <key-stores>
      <key-store name="LocalhostKeyStore">
        <credential-reference clear-text="keystore_password"/>
        <implementation type="JKS"/>
        <file path="server.keystore" relative-to="jboss.server.config.dir"/>
      </key-store>
      <key-store name="TrustStore">
        <credential-reference clear-text="truststore_password"/>
        <implementation type="JKS"/>
        <file path="server.truststore" relative-to="jboss.server.config.dir"/>
      </key-store>
    </key-stores>
    <key-managers>
      <key-manager name="LocalhostKeyManager" key-store="LocalhostKeyStore" alias-filter="server">
        <credential-reference clear-text="key_password"/>
      </key-manager>
    </key-managers>
    <trust-managers>
      <trust-manager name="TrustManager" key-store="TrustStore"/>
    </trust-managers>
    <server-ssl-contexts>
      <server-ssl-context name="LocalhostSslContext" need-client-auth="true" key-manager="LocalhostKeyManager" trust-manager="TrustManager"/>
    </server-ssl-contexts>
  </tls>
</subsystem>

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

<https-listener name="https" socket-binding="https" ssl-context="LocalhostSslContext" enable-http2="true"/>

For more information, see Elytron Subsystem and Using a client-ssl-context in How to Configure Server Security for JBoss EAP.

Chapter 7. Migrating to Elytron in JBoss EAP 7.1

7.1. Overview of Elytron

7.2. Migrate Secure Vaults and Properties

7.2.1. Migrate Vaults to Secure Credential Storage

Migrating Vault Data Using the WildFly Elytron Tool

Migrate a Single Security Vault to a Credential Store

Migrate Multiple Security Vaults to a Credential Store in Bulk

7.2.2. Migrate Security Properties to Elytron

7.3. Migrate Authentication Configuration

7.3.1. Migrate Properties-based Authentication and Authorization to Elytron

7.3.1.1. Migrate PicketBox Properties-based Configuration to Elytron

Partially Migrate by Exposing the PicketBox Security Domain to Elytron

Fully Migrate Properties-based Authentication to Elytron

7.3.1.2. Migrate Legacy Properties-based Configuration to Elytron

7.3.2. Migrate LDAP Authentication Configuration to Elytron

7.3.2.1. Migrate the Legacy LDAP Authentication to Elytron

7.3.3. Migrate Database Authentication Configuration to Elytron

7.3.3.1. Migrate the Legacy Database Authentication to Elytron

7.3.4. Migrate Kerberos Authentication to Elytron

Migrate Kerberos HTTP Authentication

Migrate the Kerberos HTTP Authentication to Elytron

Migrate Kerberos Remoting SASL Authentication

Migrate the Kerberos Remoting SASL Authentication to Elytron

7.3.5. Migrate Composite Stores to Elytron

PicketBox Composite Store Configuration

Legacy Security Realm Composite Store Configuration

Elytron Aggregate Security Realm Configuration

7.3.6. Migrate Security Domains That Use Caching to Elytron

PicketBox Cached Security Domain Configuration

Elytron Cached Security Domain Configuration

7.3.7. Migrate JACC Security to Elytron

7.4. Migrate Application Clients

7.4.1. Migrate a Naming Client Configuration to Elytron

7.4.1.1. Migrate the Naming Client Using the Configuration File Approach

7.4.1.2. Migrate the Naming Client Using the Programmatic Approach

7.4.2. Migrate an EJB Client to Elytron

7.4.2.1. Migrate the EJB Client Using the Configuration File Approach

7.4.2.2. Migrate the EJB Client Using the Programmatic Approach

7.5. Migrate SSL Configurations

7.5.1. Migrate a Simple SSL Configuration to Elytron

7.5.2. Migrate Client-Cert SSL Authentication to Elytron

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links