Red Hat Summit Red Hat SummitApoyoConsolaDesarrolladoresIniciar una pruebaContacto

Este contenido no está disponible en el idioma seleccionado.

Chapter 7. Migrating to Elytron

7.1. Overview of Elytron
Copiar enlace

JBoss EAP 7.1 introduced 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.

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 and later. 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
Copiar enlace

7.2.1. Migrate Vaults to Secure Credential Storage
Copiar enlace

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 or later, 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
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

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

$ EAP_HOME/bin/elytron-tool.sh vault --help
Copy to Clipboard Toggle word wrap
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
Copy to Clipboard Toggle word wrap

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"})
Copy to Clipboard Toggle word wrap
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
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

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"})
--------------------------------------
Copy to Clipboard Toggle word wrap

7.2.2. Migrate Security Properties to Elytron
Copiar enlace

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>
Copy to Clipboard Toggle word wrap

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" })
Copy to Clipboard Toggle word wrap

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

<subsystem xmlns="urn:wildfly:elytron:4.0" 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>
Copy to Clipboard Toggle word wrap

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)
Copy to Clipboard Toggle word wrap

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)
Copy to Clipboard Toggle word wrap

7.3. Migrate Authentication Configuration
Copiar enlace

7.3.1.1. Migrate PicketBox Properties-based Configuration to Elytron
Copiar enlace

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}}])
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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.

  1. 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)
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap

  2. Define a security domain in the elytron subsystem that references the exported security realm. 

    /subsystem=elytron/security-domain=application-security:add(realms=[{realm=application-security}], default-realm=application-security, permission-mapper=default-permission-mapper)
    Copy to Clipboard Toggle word wrap

    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-security" permission-mapper="default-permission-mapper">
      <realm name="application-security"/>
    </security-domain>
  </security-domains>
  ...
</subsystem>
    Copy to Clipboard Toggle word wrap

  3. In the undertow subsystem, map the application security domain referenced by the deployment to the newly defined security domain. 

    /subsystem=undertow/application-security-domain=application-security:add(security-domain=application-security)
    Copy to Clipboard Toggle word wrap

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

    <subsystem xmlns="urn:wildfly:elytron:4.0">
  ...
  <application-security-domains>
    <application-security-domain name="application-security" security-domain="application-security"/>
  </application-security-domains>
  ...
</subsystem>
    Copy to Clipboard Toggle word wrap
    Note
    • 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.
    • In current web service-Elytron integration, the name of the security domain specified to secure a web service endpoint and the Elytron security domain name must be the same.

  4. 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" => undefined,
        "override-deployment-config" => false,
        "referencing-deployments" => ["HelloWorld.war"],
        "security-domain" => "application-security",
        "setting" => undefined
    }
}
    Copy to Clipboard Toggle word wrap

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.

  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)
    Copy to Clipboard Toggle word wrap

  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)
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap

  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)
    Copy to Clipboard Toggle word wrap

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

    <subsystem xmlns="urn:jboss:domain:undertow:10.0">
  ...
  <application-security-domains>
    <application-security-domain name="application-security" security-domain="application-security"/>
  </application-security-domains>
  ...
</subsystem>
    Copy to Clipboard Toggle word wrap
    Note

    In current web service-Elytron integration, the name of the security domain specified to secure a web service endpoint and the Elytron security domain name must be the same.

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

7.3.1.2. Migrate Legacy Properties-based Configuration to Elytron
Copiar enlace

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)
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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.

  1. 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)
    Copy to Clipboard Toggle word wrap

  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)
    Copy to Clipboard Toggle word wrap

    This results in the following Elytron configuration. 

    <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>
    Copy to Clipboard Toggle word wrap

  3. 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}])
    Copy to Clipboard Toggle word wrap

    This results in the following Elytron configuration. 

    <subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <sasl>
    ...
    <sasl-authentication-factory name="application-security-sasl" sasl-server-factory="elytron" security-domain="application-security">
      <mechanism-configuration>
        <mechanism mechanism-name="PLAIN"/>
      </mechanism-configuration>
    </sasl-authentication-factory>
    ...
  </sasl>
</subsystem>
    Copy to Clipboard Toggle word wrap

  4. 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)
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap

  5. 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)
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap
    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.

This section describes how to migrate the legacy properties-based security realm to a filesystem-based realm in Elytron with the filesystem-realm command of the elytron.sh tool.

A filesystem-based realm is a filesystem-based identity store used by Elytron for storing user identities. The filesystem-realm command converts the properties-realm files to filesystem-realm. It also generates commands for adding this realm and a security domain to the elytron subsystem.

The steps for migrating properties-based authentication to filesystem-based authentication are the following:

  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.

    • Migrate a single properties file.

      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
      Copy to Clipboard Toggle word wrap

      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
      Copy to Clipboard Toggle word wrap

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

    • Migrate multiple properties files.

      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
      Copy to Clipboard Toggle word wrap

      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
      Copy to Clipboard Toggle word wrap

      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
      Copy to Clipboard Toggle word wrap

      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 filesystem security realm to Elytron.

    After migrating the files, 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)
    Copy to Clipboard Toggle word wrap

7.3.3. Migrate LDAP Authentication Configuration to Elytron
Copiar enlace

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==
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap

  • 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" }}])
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap

7.3.3.1. Migrate the Legacy LDAP Authentication to Elytron
Copiar enlace

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.

  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})
    Copy to Clipboard Toggle word wrap

  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"}]})
    Copy to Clipboard Toggle word wrap

These steps result 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-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>
Copy to Clipboard Toggle word wrap
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.4. Migrate Database Authentication Configuration to Elytron
Copiar enlace

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)
)
Copy to Clipboard Toggle word wrap

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 } } ] )
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

7.3.4.1. Migrate the Legacy Database Authentication to Elytron
Copiar enlace

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} } ] )
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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.5. Migrate Kerberos Authentication to Elytron
Copiar enlace

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)
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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)
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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})
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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.

  1. 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})
    Copy to Clipboard Toggle word wrap

  2. 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)
    Copy to Clipboard Toggle word wrap

  3. 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}])
    Copy to Clipboard Toggle word wrap

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

    Example: Migrated Elytron Configuration

    <subsystem xmlns="urn:wildfly:elytron:4.0" 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>
    Copy to Clipboard Toggle word wrap

  4. 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)
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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.

  1. 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})
    Copy to Clipboard Toggle word wrap

  2. 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)
    Copy to Clipboard Toggle word wrap

  3. 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}])
    Copy to Clipboard Toggle word wrap

This results in the following 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-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>
Copy to Clipboard Toggle word wrap

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.6. Migrate Composite Stores to Elytron
Copiar enlace

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" }}])
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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}])
Copy to Clipboard Toggle word wrap

This results in the following server configuration.

Example: Elytron Configuration

<subsystem xmlns="urn:wildfly:elytron:4.0" 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>
Copy to Clipboard Toggle word wrap

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.7. Migrate Security Domains That Use Caching to Elytron
Copiar enlace

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" }}])
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap

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.

  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)
    Copy to Clipboard Toggle word wrap

  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}])
    Copy to Clipboard Toggle word wrap

    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: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>
  ...
Copy to Clipboard Toggle word wrap

7.3.8. Migrate JACC Security to Elytron
Copiar enlace

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)
Copy to Clipboard Toggle word wrap

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

7.4.1. Migrate a Naming Client Configuration to Elytron
Copiar enlace

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");
...
Copy to Clipboard Toggle word wrap

You can choose from one of the following migration approaches:

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

  1. 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:client:1.2">
    <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>
    Copy to Clipboard Toggle word wrap

  2. 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");
...
    Copy to Clipboard Toggle word wrap

7.4.1.2. Migrate the Naming Client Using the Programmatic Approach
Copiar enlace

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);
Copy to Clipboard Toggle word wrap

7.4.2. Migrate an EJB Client to Elytron
Copiar enlace

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
Copy to Clipboard Toggle word wrap

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);
Copy to Clipboard Toggle word wrap

You can choose from one of the following migration approaches:

7.4.2.1. Migrate the EJB Client Using the Configuration File Approach
Copiar enlace

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

  1. 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:client:1.2">
    <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>
    Copy to Clipboard Toggle word wrap

  2. 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);----
    Copy to Clipboard Toggle word wrap

  3. 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
Copiar enlace

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);
Copy to Clipboard Toggle word wrap

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

7.5. Migrate SSL Configurations
Copiar enlace

7.5.1. Migrate a Simple SSL Configuration to Elytron
Copiar enlace

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>
Copy to Clipboard Toggle word wrap

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

  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)
    Copy to Clipboard Toggle word wrap

  2. 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"})
    Copy to Clipboard Toggle word wrap

  3. 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)
    Copy to Clipboard Toggle word wrap

  4. 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
    Copy to Clipboard Toggle word wrap

  5. Reload the server. 

    reload
    Copy to Clipboard Toggle word wrap

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

<subsystem xmlns="urn:wildfly:elytron:4.0" ...>
  ...
  <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>
Copy to Clipboard Toggle word wrap

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"/>
Copy to Clipboard Toggle word wrap

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

To enable CLIENT-CERT SSL authentication, add a truststore element to the authentication element. 

<security-realm name="ManagementRealm">
  <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="mgmt-users.properties" relative-to="jboss.server.config.dir"/>
  </authentication>
</security-realm>
Copy to Clipboard Toggle word wrap
Note

With this configuration if the CLIENT-CERT authentication does not occur, clients can fall back to use either the local mechanism or the username/password authentication mechanism. To make CLIENT-CERT based authentication mandatory, remove the local and properties elements.

A legacy truststore can be used in two ways:

Legacy truststore Containing Only CA

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

  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)
    Copy to Clipboard Toggle word wrap

  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)
    Copy to Clipboard Toggle word wrap

  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"})
    Copy to Clipboard Toggle word wrap

  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)
    Copy to Clipboard Toggle word wrap

  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)
    Copy to Clipboard Toggle word wrap

  6. 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
    Copy to Clipboard Toggle word wrap

  7. Reload the server. 

    reload
    Copy to Clipboard Toggle word wrap

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

<subsystem xmlns="urn:wildfly:elytron:4.0"...>
  ...
  <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>
Copy to Clipboard Toggle word wrap

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

<subsystem xmlns="urn:jboss:domain:undertow:10.0">
...
<https-listener name="https" socket-binding="https" ssl-context="LocalhostSslContext" enable-http2="true"/>
...
</subsystem>
Copy to Clipboard Toggle word wrap
Realms and Domains

To allow using the predefined Elytron ManagementDomain security domain and ManagementRealm security realm, users are stored in standard properties files. 

<security-domains>
    <security-domain name="ManagementDomain" default-realm="ManagementRealm" permission-mapper="default-permission-mapper">
        <realm name="ManagementRealm" role-decoder="groups-to-roles"/>
        <realm name="local"/>
    </security-domain>
</security-domains>
<security-realms>
    <properties-realm name="ManagementRealm">
        <users-properties path="mgmt-users.properties" relative-to="jboss.server.config.dir" digest-realm-name="ManagementRealm"/>
        <groups-properties path="mgmt-groups.properties" relative-to="jboss.server.config.dir"/>
    </properties-realm>
</security-realms>
Copy to Clipboard Toggle word wrap

The security realm is used in two situations:

  • When certificate authentication fails, the security realm is used in password fallback case.
  • When authorization is done for password as well as certificate, the realm provides the roles of individual users.

Thus, for any client certificate, a user must exist in the security realm.

Principal Decoder

When certificate authentication is used and the security realm accepts user names to resolve an identity, there has to be a defined way to obtain the username from a client certificate.

In this case the CN attribute is used in the certificate subject. 

/subsystem=elytron/x500-attribute-principal-decoder=x500-decoder:add(attribute-name=CN)
Copy to Clipboard Toggle word wrap
HTTP Authentication Factory

For the HTTP connections, an HTTP authentication factory is defined, using the previously defined resources. It is configured to support CLIENT_CERT and DIGEST authentication.

Since a properties realm only verifies passwords and is not able to verify client certificates, you need to first add a configuring mechanism factory. This disables certificate verification against the security realm. 

/subsystem=elytron/configurable-http-server-mechanism-factory=configured-cert:add(http-server-mechanism-factory=global, properties={org.wildfly.security.http.skip-certificate-verification=true})
Copy to Clipboard Toggle word wrap

The HTTP authentication can be created as: 

./subsystem=elytron/http-authentication-factory=client-cert-digest:add(http-server-mechanism-factory=configured-cert,security-domain=ManagementDomain,mechanism-configurations=[{mechanism-name=CLIENT_CERT,pre-realm-principal-transformer=x500-decoder},{mechanism-name=DIGEST, mechanism-realm-configurations=[{realm-name=ManagementRealm}]}])
Copy to Clipboard Toggle word wrap

The above command results in: 

<subsystem xmlns="urn:wildfly:elytron:4.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
  ...
  <http>
    ...
    <http-authentication-factory name="client-cert-digest" http-server-mechanism-factory="configured-cert" security-domain="ManagementDomain">
      <mechanism-configuration>
        <mechanism mechanism-name="CLIENT_CERT" pre-realm-principal-transformer="x500-decoder"/>
        <mechanism mechanism-name="DIGEST">
          <mechanism-realm realm-name="ManagementRealm"/>
        </mechanism>
      </mechanism-configuration>
    </http-authentication-factory>
    ...
    <configurable-http-server-mechanism-factory name="configured-cert" http-server-mechanism-factory="configured-cert">
        <properties>
            <property name="org.wildfly.security.http.skip-certificate-verification" value="true"/>
        </properties>
    </configurable-http-server-mechanism-factory>
    ...
  </http>
  ...
</subsystem>
Copy to Clipboard Toggle word wrap
Volver arriba
Red Hat logoGithubredditYoutubeTwitter

Aprender

Pruebe, compre y venda

Comunidades

Acerca de la documentación de Red Hat

Ayudamos a los usuarios de Red Hat a innovar y alcanzar sus objetivos con nuestros productos y servicios con contenido en el que pueden confiar. Explore nuestras recientes actualizaciones.

Hacer que el código abierto sea más inclusivo

Red Hat se compromete a reemplazar el lenguaje problemático en nuestro código, documentación y propiedades web. Para más detalles, consulte el Blog de Red Hat.

Acerca de Red Hat

Ofrecemos soluciones reforzadas que facilitan a las empresas trabajar en plataformas y entornos, desde el centro de datos central hasta el perímetro de la red.

Theme

© 2025 Red Hat