Chapter 2. Securing the Server and Its Interfaces
2.1. Building Blocks
2.1.1. Interfaces and Socket Bindings
JBoss EAP utilizes its host’s interfaces, for example inet-address
and nic
, as well as ports for communication for both its web applications as well as its management interfaces. These interfaces and ports are defined and configured through the interfaces
and socket-binding-groups
settings in the JBoss EAP.
For more information on how to define and configure interfaces
and socket-binding-groups
, see the Socket Bindings section of the JBoss EAP Configuration Guide.
Example: Interfaces
<interfaces> <interface name="management"> <inet-address value="${jboss.bind.address.management:127.0.0.1}"/> </interface> <interface name="public"> <inet-address value="${jboss.bind.address:127.0.0.1}"/> </interface> </interfaces>
Example: Socket Binding Group
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/> <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9993}"/> <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/> <socket-binding name="http" port="${jboss.http.port:8080}"/> <socket-binding name="https" port="${jboss.https.port:8443}"/> <socket-binding name="txn-recovery-environment" port="4712"/> <socket-binding name="txn-status-manager" port="4713"/> <outbound-socket-binding name="mail-smtp"> <remote-destination host="localhost" port="25"/> </outbound-socket-binding> </socket-binding-group>
2.1.2. Elytron Subsystem
2.1.2.1. Enable Elytron Security Across the Server
There is a simple way to enable Elytron across the server. JBoss EAP 7.1 introduces an example configuration script that enables Elytron as the security provider. This script resides in the EAP_HOME/docs/examples directory in the server installation.
Execute the following command to enable Elytron security across the server.
$ EAP_HOME/bin/jboss-cli.sh --file=EAP_HOME/docs/examples/enable-elytron.cli
2.1.2.2. Create an Elytron Security Domain
Security domains in the elytron
subsystem, when used in conjunction with security realms, are used for both core management authentication as well as for authentication with applications.
Deployments are limited to using one Elytron security domain per deployment. Scenarios that may have required multiple legacy security domains can now be accomplished using a single Elytron security domain.
Add a Security Domain Using the Management CLI
/subsystem=elytron/security-domain=domainName:add(realms=[{realm=realmName,role-decoder=roleDecoderName}],default-realm=realmName,permission-mapper=permissionMapperName,role-mapper=roleMapperName,...)
Add a Security Domain Using the Management Console
- Access the management console. For more information, see the Management Console section in the JBoss EAP Configuration Guide.
-
Navigate to Configuration
Subsystems Security - Elytron Other. - Click on View. Select Security Domain from the list on the SSL tab. All security domain related configurations can be done here.
2.1.2.3. Create an Elytron Security Realm
Security realms in the elytron
subsystem, when used in conjunction with security domains, are used for both core management authentication as well as for authentication with applications. Security realms are also specifically typed based on their identity store, for example jdbc-realm
, filesystem-realm
, properties-realm
, etc.
Add a Security Realm Using the Management CLI
/subsystem=elytron/type-of-realm=realmName:add(....)
Examples of adding specific realms, such as jdbc-realm
, filesystem-realm
, and properties-realm
can be found in previous sections.
Add a Security Realm Using the Management Console
- Access the management console. For more information, see the Management Console section in the JBoss EAP Configuration Guide.
-
Navigate to Configuration
Subsystems Security - Elytron Security Realm / Authentication. - Click on View. The Security Realm, Security Realm Mapper and Authentication tabs let you configure all the security realm and authentication related attributes.
2.1.2.4. Create an Elytron Role Decoder
A role decoder converts attributes from the identity provided by the security realm into roles. Role decoders are also specifically typed based on their functionality, for example empty-role-decoder
, simple-role-decoder
, and custom-role-decoder
.
Add a Role Decoder Using the Management CLI
/subsystem=elytron/ROLE-DECODER-TYPE=roleDeoderName:add(....)
Add a Role Decoder Using the Management Console
- Access the management console. For more information, see the Management Console section in the JBoss EAP Configuration Guide.
-
Navigate to Configuration
Subsystems Security - Elytron Mapper / Decoder. - Click on View. The Decoder tab lets you do all the role decoder related configurations.
2.1.2.5. Create an Elytron Role Mapper
A role mapper maps roles after they have been decoded to other roles. Examples include normalizing role names or adding and removing specific roles from principals after they have been decoded. Role mappers are also specifically typed based on their functionality, for example add-prefix-role-mapper
, add-suffix-role-mapper
, and constant-role-mapper
.
Adding a Role Mapper Takes the General Form
/subsystem=elytron/ROLE-MAPPER-TYPE=roleMapperName:add(...)
Adding a Role Mapper Using the Management Console
- Access the management console. For more information, see the Management Console section in the JBoss EAP Configuration Guide.
-
Navigate to Configuration
Subsystems Security - Elytron Mapper / Decoder. - Click on View. The Role Mapper tab lets you do all the role mapper related configurations.
2.1.2.6. Create an Elytron Permission Mapper
In addition to roles being assigned to a identity, permissions may also be assigned. A permission mapper assigns permissions to an identity. Permission mappers are also specifically typed based on their functionality, for example logical-permission-mapper
, simple-permission-mapper
, and custom-permission-mapper
.
Add a Permission Mapper Using the Management CLI
/subsystem=elytron/simple-permission-mapper=PermissionMapperName:add(...)
Add a Permission Mapper Using the Management Console
- Access the management console. For more information, see the Management Console section in the JBoss EAP Configuration Guide.
-
Navigate to Configuration
Subsystems Security - Elytron Mapper / Decoder. - Click on View. The Permission Mapper tab lets you do all the permission mapper related configurations.
2.1.2.7. Creating an Authentication Configuration
An authentication configuration contains the credentials to use when making a connection. For more information on authentication configurations, see Configure Client Authentication with Elytron Client in How to Configure Identity Management for JBoss EAP.
Instead of a credential store, you can configure an Elytron security domain to use the credentials of the accessing user. For instance, a security domain can be used in conjunction with Kerberos for authenticating incoming users. Follow the instructions in Configure the Elytron Subsystem in How to Set Up SSO with Kerberos for JBoss EAP, and set obtain-kerberos-ticket=true
in the Kerberos security factory.
Add an Authentication Configuration Using the Management CLI
/subsystem=elytron/authentication-configuration=AUTHENTICATION_CONFIGURATION_NAME:add(authentication-name=AUTHENTICATION_NAME, credential-reference={clear-text=PASSWORD})
Add an Authentication Configuration Using the Management Console
- Access the management console. For more information, see the Management Console section in the JBoss EAP Configuration Guide.
-
Navigate to Configuration
Subsystems Security - Elytron Security Realm/Authentication. - Click on View. Select Authentication Configuration from the list on the Authentication tab. All authentication configuration related configurations can be done here.
For the full list of authentication-configuration
attributes, see Elytron Subsystem Components Reference.
2.1.2.8. Creating an Authentication Context
An authentication context contains a set of rules and either authentication configurations or SSL contexts to use for establishing a connection. For more information on authentication contexts, see Configure Client Authentication with Elytron Client in How to Configure Identity Management for JBoss EAP.
Add an Authentication Context Using the Management CLI
An authentication context can be created using the following management CLI command.
/subsystem=elytron/authentication-context=AUTHENTICATION_CONTEXT_NAME:add()
Typically, an authentication context will contain a set of rules and either an authentication configuration or a SSL context. The following CLI command provides demonstrates defining an authentication context that only functions when the hostname is localhost
.
/subsystem=elytron/authentication-context=AUTHENTICATION_CONTEXT_NAME:add(match-rules=[{authentication-configuration=AUTHENTICATION_CONFIGURATION_NAME, match-host=localhost}])
Add an Authentication Context Using the Management Console
- Access the management console. For more information, see the Management Console section in the JBoss EAP Configuration Guide.
-
Navigate to Configuration
Subsystems Security - Elytron Security Realm/Authentication. - Click on View. Select Authentication Context from the list on the Authentication tab. All authentication context related configurations can be done here.
For the full list of authentication-context
attributes, see Elytron Subsystem Components Reference.
2.1.2.9. Create an Elytron Authentication Factory
An authentication factory is an authentication policy used for specific authentication mechanisms. Authentication factories are specifically based on the authentication mechanism, for example http-authentication-factory
, sasl-authentication-factory
and kerberos-security-factory
.
Add an Authentication Factory Using the Management CLI
/subsystem=elytron/AUTH-FACTORY-TYPE=authFactoryName:add(....)
Add an Authentication Factory Using the Management Console
- Access the management console. For more information, see the Management Console section in the JBoss EAP Configuration Guide.
-
Navigate to Configuration
Subsystems Security - Elytron Factory. - Click on View. All Elytron settings for factories can be configured here.
2.1.2.10. Create an Elytron Keystore
A key-store
is the definition of a keystore or truststore including the type of keystore, its location, and the credential for accessing it.
To generate an example keystore for use with the elytron
subsystem, use the following command in Red Hat Enterprise Linux 7.
$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore keystore.jks -dname "CN=localhost" -keypass secret -storepass secret
Add a Keystore Using the Management CLI
To define a key-store
in Elytron that references the newly made keystore, execute the following management CLI command. This command species the path to the keystore, relative to the file system path provided, the credential reference used for accessing the keystore, and the type of keystore.
/subsystem=elytron/key-store=newKeyStore:add(path=keystore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS)
The above command uses relative-to
to reference the location of the keystore file. Alternatively, you can specify the full path to the keystore in path
and omit relative-to
.
Add a Keystore Using the Management Console
- Access the management console. For more information, see the Management Console section in the JBoss EAP Configuration Guide.
-
Navigate to Configuration
Subsystems Security - Elytron Other. - Click on View. The Key Store tab lets you do all the keystore related configurations.
2.1.2.11. Create an Elytron Key Manager
A key-manager
references a key-store
, and is used in conjunction with an SSL context.
Add a Key Manager Using the Management CLI
The following command specifies the underlying keystore to reference, the algorithm to use when initializing the key manager, and the credential reference for accessing the entries in the underlying keystore.
/subsystem=elytron/key-manager=newKeyManager:add(key-store=KEY_STORE,algorithm="PKIX",credential-reference={clear-text=secret})
If an algorithm is not specified, then it will be set to the default KeyManagerFactory
algorithm name.
The available key manager algorithms are provided by the JDK in use. For example, a JDK that uses SunJSSE provides the PKIX
and SunX509
algorithms.
Add a Key Manager Using the Management Console
- Access the management console. For more information, see the Management Console section in the JBoss EAP Configuration Guide.
-
Navigate to Configuration
Subsystems Security - Elytron Other. - Click on View. The Key Manager tab lets you do all the key manager related configurations.
2.1.2.12. Create an Elytron Truststore
To create a truststore in Elytron execute the following CLI command.
/subsystem=elytron/key-store=default-trust-store:add(type=JKS, relative-to=jboss.server.config.dir, path=application.truststore, credential-reference={clear-text=password})
In order to successfully execute the command above you must have an application.truststore
file inside your EAP_HOME/standalone/configuration
directory. The truststore must contain the certificates associated with the endpoint or a certificate chain in case the end point’s certificate is signed by a CA.
Red Hat recommends you to avoid using self-signed certificates. Ideally, certificates should be signed by a CA and your truststore should contain a certificate chain representing your ROOT
and intermediary CAs.
2.1.2.13. Create an Elytron Trust Manager
To define a trust manager in Elytron execute the following CLI command.
/subsystem=elytron/trust-manager=default-trust-manager:add(key-store=TRUST-STORE-NAME)
This sets the defined truststore as the source of the certificates that the application server trusts.
2.1.2.14. Using the Out of the Box Elytron Components
JBoss EAP provides a default set of Elytron components configured in the elytron
subsystem. You can find more details on these pre-configured components in the Out of the Box section of the Security Architecture guide.
2.1.2.14.1. Securing Management Interfaces
You can find more details on the enabling JBoss EAP to use the out of the box Elytron components for securing the management interfaces in the User Authentication with Elytron section.
2.1.2.14.2. Securing Applications
The elytron
subsystem provides application-http-authentication
for http-authentication-factory
by default, which can be used to secure applications. For more information on how to configure application-http-authentication
, see the Out of the Box section of the Security Architecture guide.
To configure applications to use application-http-authentication
, see Configure Web Applications to Use Elytron or Legacy Security for Authentication in How to Configure Identity Management Guide. You can also override the default behavior of all applications using the steps in the Override an Application’s Authentication Configuration section of the JBoss EAP How to Configure Identity Management Guide.
2.1.2.14.3. Using SSL/TLS
JBoss EAP does provide a default one-way SSL/TLS configuration using the legacy core management authentication, but it does not provide one in the elytron
subsystem. You can find more details on configuring SSL/TLS using the elytron
subsystem for both the management interfaces as well as for applications in the following sections:
2.1.2.14.4. Using Elytron with Other Subsystems
In addition to securing applications and management interfaces, Elytron also integrates with other subsystems in JBoss EAP.
batch-jberet
-
You can configure the
batch-jberet
subsystem to run batch jobs using an Elytron security domain. For more information, see Configure Security for Batch Jobs in the Configuration Guide. datasources
- You can use a credential store or an Elytron security domain to provide authentication information in a datasource definition. For more information, see Datasource Security in the Configuration Guide.
ejb3
-
You can create mappings for Elytron security domains in the
ejb3
subsystem to be referenced by deployments. For more information, see Elytron Integration with the EJB Subsystem in Developing EJB Applications. iiop-openjdk
-
You can use the
elytron
subsystem to configure SSL/TLS between clients and servers using theiiop-openjdk
subsystem. For more information, see Configure IIOP to use SSL/TLS with the Elytron Subsystem in the Configuration Guide. jca
-
You can use the
elytron-enabled
attribute to enable Elytron security for a work manager. For more information, see Configuring the JCA Subsystem in the Configuration Guide. jgroups
-
You can configure the
SYM_ENCRYPT
andASYM_ENCRYPT
protocols to reference keystores or credential references defined in theelytron
subsystem. For more information, see Securing a Cluster in the Configuration Guide. mail
-
You can use a credential store to provide authentication information in a server definition in the
mail
subsystem. For more information, see Use a Credential Store for Passwords in the Configuration Guide. messaging-activemq
-
You can secure remote connections to the remote connections used by the
messaging-activemq
subsystem. For more information, see the Using the Elytron Subsystem section of Configuring Messaging. modcluster
-
You can use an Elytron client
ssl-context
to communicate with a load balancer using SSL/TLS. For more information, see Elytron Integration with the ModCluster Subsystem. remoting
-
You can configure inbound and outbound connections in the
remoting
subsystem to reference authentication contexts, SASL authentication factories, and SSL contexts defined in theelytron
subsystem. For full details on configuring each type of connection, see Elytron Integration with the Remoting Subsystem. resource-adapters
- You can secure connections to the resource adapter using Elytron. You can enable security inflow to establish security credentials when submitting work to be executed by the work manager. For more information, see Configure Resource Adapters to Use the Elytron Subsystem in the Configuration Guide.
undertow
-
You can use the
elytron
subsystem to configure both SSL/TLS and application authentication. For more information on configuring application authentication, see Using SSL/TLS and Configure Web Applications to Use Elytron or Legacy Security for Authentication in How to Configure Identity Management.
2.1.2.15. Elytron Audit Logging
Audit logging for the elytron
subsystem enables logging of Elytron authentication and authorization events within the application server. Audit log entries are stored in either JSON
or SIMPLE
, human readable format. By default, audit logging is disabled in Elytron.
You can enable audit logging by configuring any of the following log handlers for Elytron, and then adding them to the desired security domain:
Elytron audit logging is distinct from other audit logging, such as audit logging for the JBoss EAP management interfaces. For more information on management interface audit logging options, see the Management Audit Logging section in the JBoss EAP Configuration Guide.
File Audit Logging
File audit logging stores audit log messages in one specified file in the file system, without dividing them into multiple files.
An Elytron file audit logger, named local-audit
, is defined by default. Once enabled, it will write Elytron audit logs to EAP_HOME/standalone/log/audit.log
on a standalone server, or EAP_HOME/domain/log/audit.log
for a managed domain host.
The attributes of a file audit logger are:
-
path
andrelative-to
: Defines the location of the log file. -
synchronized
: Specifies whether every event should be immediately written to disk. format
: UseSIMPLE
for human readable text format, orJSON
for storing individual events in JSON.You can use a command similar to the following to create a file audit log.
/subsystem=elytron/file-audit-log=my_audit_log:add(path="my_audit.log",relative-to="jboss.server.log.dir",format=SIMPLE,synchronized=true)
Enable the defined file audit logger by adding it to a security domain.
/subsystem=elytron/security-domain=domain-with-file-logger:write-attribute(name=security-event-listener, value=my_audit_log)
Periodic Rotating File Audit Logging
Periodic rotating file audit logging automatically rotates audit log files based on a configured schedule. It has the same basic attributes as the default file audit logger, with the following additional attribute:
suffix
: This must be in thejava.text.SimpleDateFormat
format, for example.yyyy-MM-dd-HH
. The period of the rotation is automatically calculated based on this suffix, and the suffix is appended to the end of the log file names.You can use a command similar to the following to create a periodic rotating file audit log.
/subsystem=elytron/periodic-rotating-file-audit-log=my_periodic_audit_log:add(path="my_periodic_audit.log",relative-to="jboss.server.log.dir",format=SIMPLE,synchronized=false,suffix=".yyyy-MM-dd-HH")
Enable the defined periodic rotating file audit logger by adding it to a security domain.
/subsystem=elytron/security-domain=domain-with-periodic-file-logger:write-attribute(name=security-event-listener, value=my_periodic_audit_log)
Size Rotating File Audit Logging
Size rotating file audit logging automatically rotates audit log files when the log file reaches a configured file size. It has the same basic attributes as the default file audit logger, with the following additional attributes:
-
rotate-size
: The maximum size that the log file can reach before being rotated. The default is2m
for 2 megabytes. -
max-backup-index
: The maximum number of files to backup when rotating. -
rotate-on-boot
: By default, a new log file is not created on server restart. You can set this totrue
to rotate the log on server restart. -
suffix
: This optionally adds a date suffix to a rotated log. This must be in thejava.text.SimpleDateFormat
format, for example.yyyy-MM-dd-HH
.
When the log file size exceeds the limit defined by the rotate-size
attribute, the suffix .1
is appended to the end of the current file and a new log file is created. If there are any existing log files, their suffixed number is incremented by one, for example audit_log.1
is renamed to audit_log.2
. This happens until the maximum number of log files defined by max-backup-index
is reached. When the max-backup-index
is exceeded, the file that is over limit, for example audit_log.99
, is removed.
You can use a command similar to the following to create a size rotating file audit log.
/subsystem=elytron/size-rotating-file-audit-log=my_size_log:add(path="my_size_audit.log",relative-to="jboss.server.log.dir",format=SIMPLE,synchronized=false,rotate-size="2m",max-backup-index=10)
Enable the defined size rotating audit logger by adding it to a security domain.
/subsystem=elytron/security-domain=domain-with-size-logger:write-attribute(name=security-event-listener, value=my_size_log)
Syslog Audit Logging
A syslog handler specifies the parameters by which audit log entries are sent to a syslog server, specifically the syslog server’s host name and port on which the syslog server is listening. Sending audit logging to a syslog server provides more security options than logging to a local file or local syslog server. Multiple syslog handlers can be defined and be active at the same time.
Add a syslog handler.
/subsystem=elytron/syslog-audit-log=syslog-logger:add(host-name=HOST_NAME, port=PORT, server-address=SERVER_ADDRESS, format=JSON, transport=UDP)
Enable the defined syslog audit logger by adding it to a security domain.
/subsystem=elytron/security-domain=domain-with-syslog-logger:write-attribute(name=security-event-listener, value=syslog-logger)
To send logs to syslog server over TLS, you can add the following configuration:
/subsystem=elytron/syslog-audit-log=remote-audit:add(transport=SSL_TCP,server-address=127.0.0.1,port=9898,host-name=Elytron,ssl-context=audit-ssl)
To send security events to more destinations, mainly loggers, the aggregate-security-event-listener
resource is used. This delivers all events to all listeners specified in the aggregate listener definition.
2.1.2.16. Enable and Disable the Elytron Subsystem
The elytron
subsystem comes pre-configured with the default JBoss EAP profiles alongside the legacy security
subsystem.
If you are using a profile where the elytron
subsystem has not been configured, you can add it by adding the elytron
extension and enabling the elytron
subsystem.
To add the elytron
extension required for the elytron
subsystem:
/extension=org.wildfly.extension.elytron:add()
To enable the elytron
subsystem in JBoss EAP:
/subsystem=elytron:add reload
To disable the elytron
subsystem in JBoss EAP:
/subsystem=elytron:remove reload
Other subsystems within JBoss EAP may have dependencies on the elytron
subsystem. If these dependencies are not resolved before disabling it, you will see errors when starting JBoss EAP.
2.1.3. Legacy Security Subsystem
2.1.3.1. Enable and Disable the Security Subsystem
To disable the security subsystem in JBoss EAP:
/subsystem=security:remove
Other subsystems within JBoss EAP may have dependencies on the security subsystem. If these dependencies are not resolved before disabling it, you will see errors when starting JBoss EAP.
To enable the security subsystem in JBoss EAP:
/subsystem=security:add
2.1.4. Legacy Security Realms
JBoss EAP uses security realms to define authentication and authorization mechanisms, such as local, LDAP, properties, which can then be used by the management interfaces. For more background information on security realms, see the Security Realms section of the Red Hat JBoss Enterprise Application Platform Security Architecture guide.
Example: Security Realms
<security-realms> <security-realm name="ManagementRealm"> <authentication> <local default-user="$local" skip-group-loading="true"/> <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/> </authentication> <authorization map-groups-to-roles="false"> <properties path="mgmt-groups.properties" relative-to="jboss.server.config.dir"/> </authorization> </security-realm> <security-realm name="ApplicationRealm"> <authentication> <local default-user="$local" allowed-users="*" skip-group-loading="true"/> <properties path="application-users.properties" relative-to="jboss.server.config.dir"/> </authentication> <authorization> <properties path="application-roles.properties" relative-to="jboss.server.config.dir"/> </authorization> </security-realm> </security-realms>
In addition to updating the existing security realms, JBoss EAP also allows you to create new security realms. You can create new security realms via the management console as well as invoking the following command from the management CLI:
/core-service=management/security-realm=NEW-REALM-NAME:add()
If you create a new security realm and want to use a properties file for authentication or authorization, you must create a new properties file specifically for the new security domain. JBoss EAP does not reuse existing files used by other security domains nor does it automatically create new files specified in the configuration if they do not exist.
2.1.5. Using Authentication and Socket Bindings for Securing the Management Interfaces
By default, JBoss EAP defines an http-interface
to connect to the management interfaces:
[standalone@localhost:9990 /] /core-service=management:read-resource(recursive=true) { "outcome" => "success", "result" => { "access" => {...}, "ldap-connection" => undefined, "management-interface" => {"http-interface" => { "allowed-origins" => undefined, "console-enabled" => true, "http-authentication-factory" => "management-http-authentication", "http-upgrade" => { "enabled" => true, "sasl-authentication-factory" => "management-sasl-authentication" }, "http-upgrade-enabled" => true, "sasl-protocol" => "remote", "secure-socket-binding" => undefined, "security-realm" => undefined, "server-name" => undefined, "socket-binding" => "management-http", "ssl-context" => undefined }}, "security-realm" => {...}, "service" => undefined } }
You can use a combination socket-binding
, http-authentication-factory
and http-upgrade
to secure the management interfaces using the elytron
subsystem. Alternatively, you can use socket-binding
with security-realm
to secure the management interfaces with the legacy core management authentication. You can also disable the management interfaces, and configure users of the interfaces to have various roles and access rights.
2.2. How to Secure the Management Interfaces
The following sections show how to perform various operations related to securing the JBoss EAP management interfaces and related subsystems.
The management CLI commands shown assume that you are running a JBoss EAP standalone server. For more details on using the management CLI for a JBoss EAP managed domain, see the JBoss EAP Management CLI Guide.
Elytron Integration with the Management CLI
The management interfaces can be secured using resources from the elytron
subsystem in the same way as it is done by the legacy security realms.
The SSL configuration for connections comes from one of these locations:
- Any SSL configuration within the CLI specific configuration.
- The default SSL configuration that automatically prompts users to accept the server’s certificate.
- The java system property.
Client configuration can be modified using the wildfly-config.xml
file.
If you set the -Dwildfly.config.url
property, any file can be used by the client for configuration.
2.2.1. Configure Networking and Ports
Depending on the configuration of the host, JBoss EAP may be configured to use various network interfaces and ports. This allows JBoss EAP to work with different host, networking, and firewall requirements.
For more information on the networking and ports used by JBoss EAP, as well as how to configure these settings, see the Network and Port Configuration section of the JBoss EAP Configuration Guide.
2.2.2. Disabling the Management Console
Other clients, such as JBoss Operations Network, operate using the HTTP interface for managing JBoss EAP. In order to continue using these services, just the web-based management console itself may be disabled. This is accomplished by setting the console-enabled
attribute to false
:
/core-service=management/management-interface=http-interface/:write-attribute(name=console-enabled,value=false)
2.2.3. Disabling Remote Access to JMX
Remote access to the jmx
subsystem allows for JDK and application management operations to be triggered remotely. To disable remote access to JMX in JBoss EAP, remove the remoting connector in the jmx
subsystem:
Removing the Remoting Connector
/subsystem=jmx/remoting-connector=jmx/:remove
For more information on JMX, see the JMX section of the Red Hat JBoss Enterprise Application Platform Security Architecture guide.
2.2.4. Silent Authentication
The default installation of JBoss EAP contains a method of silent authentication for a local management CLI user. This allows the local user the ability to access the management CLI without user name or password authentication. This functionality is enabled as a convenience, and to assist local users running the management CLI scripts without requiring authentication. It is considered a useful feature given that access to the local configuration typically also gives the user the ability to add their own user details or otherwise disable security checks.
The convenience of silent authentication for local users can be disabled where greater security control is required. This can be achieved by removing the local element within the security-realm
attribute of the configuration file. This is applicable to both standalone instance as well as managed domain.
The removal of the local element should only be done if the impact on the JBoss EAP instance and its configuration is fully understood.
To remove silent authentication when using the elytron
subsystem:
[standalone@localhost:9990 /] /subsystem=elytron/sasl-authentication-factory=managenet-sasl-authentication:read-resource { "outcome" => "success", "result" => { "mechanism-configurations" => [ { "mechanism-name" => "JBOSS-LOCAL-USER", "realm-mapper" => "local" }, { "mechanism-name" => "DIGEST-MD5", "mechanism-realm-configurations" => [{"realm-name" => "ManagementRealm"}] } ], "sasl-server-factory" => "configured", "security-domain" => "ManagementDomain" } } /subsystem=elytron/sasl-authentication-factory=temp-sasl-authentication:list-remove(name=mechanism-configurations,index=0) reload
To remove silent authentication when using a legacy security realm:
/core-service=management/security-realm=REALM_NAME/authentication=local:remove
2.2.5. Removing Undertow Response Headers
The default JBoss EAP undertow
subsystem includes two response headers that are appended to each HTTP response by the default-host
:
-
Server
, which is set toJBoss-EAP/7
-
X-Powered-By
, which is set toUndertow/1
Although these can be useful for development and debugging purposes, you might want to remove these headers if you do not want to disclose information about the server in use.
Use the following management CLI commands to remove these response headers from the default-host
:
/subsystem=undertow/server=default-server/host=default-host/filter-ref=server-header:remove /subsystem=undertow/server=default-server/host=default-host/filter-ref=x-powered-by-header:remove reload
2.2.6. Enable One-way SSL/TLS for the Management Interfaces Using the Elytron Subsystem
Obtain or generate your keystore.
Before enabling one-way SSL/TLS in JBoss EAP, you must obtain or generate the keystore you plan on using. To generate an example keystore in Red Hat Enterprise Linux 7, use the following command.
$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore keystore.jks -dname "CN=localhost" -keypass secret -storepass secret
Create a
key-store
,key-manager
, andserver-ssl-context
./subsystem=elytron/key-store=httpsKS:add(path=keystore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS) /subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS,algorithm="SunX509",credential-reference={clear-text=secret}) /subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM,protocols=["TLSv1.2"])
ImportantYou need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the
PKIX
andSunX509
algorithms. You also need to determine what HTTPS protocols you want to support. The example commands above useTLSv1.2
. You can use thecipher-suite-filter
argument to specify which cipher suites are allowed, and theuse-cipher-suites-order
argument to honor server cipher suite order. Theuse-cipher-suites-order
attribute by default is set totrue
. This differs from the legacysecurity
subsystem behavior, which defaults to honoring client cipher suite order.NoteThe above command uses
relative-to
to reference the location of the keystore file. Alternatively, you can specify the full path to the keystore inpath
and omitrelative-to
.Enable HTTPS on the management interface.
/core-service=management/management-interface=http-interface:write-attribute(name=ssl-context, value=httpsSSC) /core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https)
Reload the JBoss EAP instance.
reload
One-way SSL/TLS is now enabled for the management interfaces.
In cases where you have both a security-realm
and ssl-context
defined, JBoss EAP will use the SSL/TLS configuration provided by ssl-context
.
2.2.7. Enable Two-way SSL/TLS for the Management Interfaces Using the Elytron Subsystem
Obtain or generate your keystore.
Before enabling one-way SSL/TLS in JBoss EAP, you must obtain or generate the keystores, truststores and certificates you plan on using. To generate an example set of keystores, truststores, and certificates in Red Hat Enterprise Linux 7, use the following commands.
Generate your server and client keystores.
$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore server.keystore.jks -dname "CN=localhost" -keypass secret -storepass secret $ keytool -genkeypair -alias client -keyalg RSA -keysize 1024 -validity 365 -keystore client.keystore.jks -dname "CN=client" -keypass secret -storepass secret
Export your server and client certificates.
$ keytool -exportcert -keystore server.keystore.jks -alias localhost -keypass secret -storepass secret -file server.cer $ keytool -exportcert -keystore client.keystore.jks -alias client -keypass secret -storepass secret -file client.cer
Import the server and client certificates into the opposing truststores.
$ keytool -importcert -keystore server.truststore.jks -storepass secret -alias client -trustcacerts -file client.cer $ keytool -importcert -keystore client.truststore.jks -storepass secret -alias localhost -trustcacerts -file server.cer
Configure a
key-store
,key-manager
,trust-manager
, andserver-ssl-context
for the server keystore and truststore./subsystem=elytron/key-store=twoWayKS:add(path=server.keystore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS) /subsystem=elytron/key-store=twoWayTS:add(path=server.truststore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS) /subsystem=elytron/key-manager=twoWayKM:add(key-store=twoWayKS,algorithm="SunX509",credential-reference={clear-text=secret}) /subsystem=elytron/trust-manager=twoWayTM:add(key-store=twoWayTS,algorithm="SunX509") /subsystem=elytron/server-ssl-context=twoWaySSC:add(key-manager=twoWayKM,protocols=["TLSv1.2"],trust-manager=twoWayTM,want-client-auth=true,need-client-auth=true)
ImportantYou need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the
PKIX
andSunX509
algorithms. You also need to determine what HTTPS protocols you want to support. The example commands above useTLSv1.2
. You can use thecipher-suite-filter
argument to specify which cipher suites are allowed, and theuse-cipher-suites-order
argument to honor server cipher suite order. Theuse-cipher-suites-order
attribute by default is set totrue
. This differs from the legacysecurity
subsystem behavior, which defaults to honoring client cipher suite order.NoteThe above command uses
relative-to
to reference the location of the keystore file. Alternatively, you can specify the full path to the keystore inpath
and omitrelative-to
.Enable HTTPS on the management interface.
/core-service=management/management-interface=http-interface:write-attribute(name=ssl-context, value=twoWaySSC) /core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https)
Reload the JBoss EAP instance.
reload
Configure your client to use the client certificate.
You need to configure your client to present the trusted client certificate to the server to complete the two-way SSL/TLS authentication. For example, if using a browser, you need to import the trusted certificate into the browser’s trust store.
This results in a forced two-way SSL/TLS authentication, without changing the original authentication to the server management.
If you want to change the original authentication method, see Configure Authentication with Certificates in How to Configure Identity Management for JBoss EAP.
Two-way SSL/TLS is now enabled for the management interfaces.
In cases where you have both a security-realm
and ssl-context
defined, JBoss EAP will use the SSL/TLS configuration provided by ssl-context
.
2.2.8. Configure the Management Interfaces for One-way SSL/TLS with Legacy Core Management Authentication
Configuring the JBoss EAP management interfaces for communication only using one-way SSL/TLS provides increased security. All network traffic between the client and the management interfaces is encrypted, which reduces the risk of security attacks such as a man-in-the-middle attack.
In this procedure unencrypted communication with the JBoss EAP instance is disabled. This procedure applies to both standalone server and managed domain configurations. For a managed domain, prefix the management CLI commands with the name of the host, for example: /host=master
.
While performing the steps for enabling one-way SSL/TLS on the management interfaces, do not reload the configuration unless explicitly instructed. Doing so may cause you to be locked out of the management interfaces.
- Create a keystore to secure the management interfaces.
- Ensure the management interfaces bind to HTTPS.
-
Optional: Implement a custom
socket-binding-group
. - Create a new security realm.
- Configure the management interfaces to use the new security realm.
- Configure the management interfaces to use the keystore.
-
Update the
jboss-cli.xml
.
Create a Keystore to Secure the Management Interfaces
This keystore must be in JKS format as the management interfaces are not compatible with keystores in JCEKS format.
Use the following to generate a keystore, replacing the example values for the parameters, for example alias
, keypass
, keystore
, storepass
and dname
, with the correct values for the environment.
$ keytool -genkeypair -alias appserver -storetype jks -keyalg RSA -keysize 2048 -keypass password1 -keystore EAP_HOME/standalone/configuration/identity.jks -storepass password1 -dname "CN=appserver,OU=Sales,O=Systems Inc,L=Raleigh,ST=NC,C=US" -validity 730 -v
The parameter validity
specifies for how many days the key is valid. A value of 730
equals two years.
Ensure the Management Interfaces Bind to HTTPS
Running a Standalone Server
To ensure the management interfaces bind to HTTPS, you must add the management-https
configuration and remove the management-http
configuration.
Use the following CLI commands to bind the management interfaces to HTTPS:
/core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https) /core-service=management/management-interface=http-interface:undefine-attribute(name=socket-binding)
Running a Managed Domain
Change the socket element within the management-interface
attribute by adding secure-port
and removing port configuration.
Use the following commands to bind the management interfaces to HTTPS:
/host=master/core-service=management/management-interface=http-interface:write-attribute(name=secure-port,value=9993) /host=master/core-service=management/management-interface=http-interface:undefine-attribute(name=port)
Optional: Implement a Custom socket-binding-group
If you want to use a custom socket-binding-group
, you must ensure the management-https
binding is defined, which by default is bound to port 9993
. You can verify this from the socket-binding-group
attribute of the server’s configuration file or using the management CLI:
/socket-binding-group=standard-sockets/socket-binding=management-https:read-resource(recursive=true) { "outcome" => "success", "result" => { "client-mappings" => undefined, "fixed-port" => false, "interface" => "management", "multicast-address" => undefined, "multicast-port" => undefined, "name" => "management-https", "port" => expression "${jboss.management.https.port:9993}" } }
Create a New Security Realm
In this example, the new security realm using HTTPS, ManagementRealmHTTPS
, uses a properties file named https-mgmt-users.properties
located in the EAP_HOME/standalone/configuration/
directory for storing user names and passwords.
Create a properties file for storing user name and passwords.
User names and passwords can be added to the file later, but for now, you need to create an empty file named
https-mgmt-users.properties
and save it to that location. The below example shows using thetouch
command, but you may also use other mechanisms, such as a text editor.Example: Using the touch Command to Create an Empty File
$ touch EAP_HOME/standalone/configuration/https-mgmt-users.properties
Next, use the following management CLI commands to create a new security realm named
ManagementRealmHTTPS
:/core-service=management/security-realm=ManagementRealmHTTPS:add /core-service=management/security-realm=ManagementRealmHTTPS/authentication=properties:add(path=https-mgmt-users.properties,relative-to=jboss.server.config.dir)
Add users to the properties file.
At this point, you have created a new security realm and configured it to use a properties file for authentication. You must now add users to that properties file using the
add-user
script, which is available in theEAP_HOME/bin/
directory. When running theadd-user
script, you must specify both the properties file and the security realm using the-up
and-r
options respectively. From there, theadd-user
script will interactively prompt you for the user name and password information to store in thehttps-mgmt-users.properties
file.$ EAP_HOME/bin/add-user.sh -up EAP_HOME/standalone/configuration/https-mgmt-users.properties -r ManagementRealmHTTPS ... Enter the details of the new user to add. Using realm 'ManagementRealmHTTPS' as specified on the command line. ... Username : httpUser Password requirements are listed below. To modify these restrictions edit the add-user.properties configuration file. - The password must not be one of the following restricted values {root, admin, administrator} - The password must contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), 1 non-alphanumeric symbol(s) - The password must be different from the username ... Password : Re-enter Password : About to add user 'httpUser' for realm 'ManagementRealmHTTPS' ... Is this correct yes/no? yes .. Added user 'httpUser' to file 'EAP_HOME/configuration/https-mgmt-users.properties' ... Is this new user going to be used for one AS process to connect to another AS process? e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls. yes/no? no
ImportantWhen configuring security realms that use properties files to store usernames and passwords, it is recommended that each realm use a distinct properties file that is not shared with another realm.
Configure the Management Interfaces to Use the New Security Realm
Use the following management CLI command to configure the management interfaces to use the new security realm.
/core-service=management/management-interface=http-interface:write-attribute(name=security-realm,value=ManagementRealmHTTPS)
Configure the Management Interfaces to Use the Keystore
Use the below management CLI command to configure the management interfaces to use the keystore. For the parameters file, password and alias their values must be copied from the Create a Keystore to Secure the Management Interfaces step.
/core-service=management/security-realm=ManagementRealmHTTPS/server-identity=ssl:add(keystore-path=identity.jks,keystore-relative-to=jboss.server.config.dir,keystore-password=password1, alias=appserver)
To update the keystore password, use the following CLI command:
/core-service=management/security-realm=ManagementRealmHTTPS/server-identity=ssl:write-attribute(name=keystore-password,value=newpassword)
At this point, you need to reload the server’s configuration:
reload
After reloading the server configuration, the log should contain the following, just before the text which states the number of services that are started:
13:50:54,160 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0061: Http management interface listening on https://127.0.0.1:9993/management 13:50:54,162 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0052: Admin console listening on https://127.0.0.1:9993
The management interfaces are now listening on port 9993
, which confirms that the procedure was successful.
At this point, the CLI will disconnect and will be unable to reconnect since the port bindings have changed. Proceed to the next step to update the jboss-cli.xml
file to allow the management CLI to reconnect.
Update the jboss-cli.xml File
If using the management CLI to perform management actions, the following changes must to be made to the EAP_HOME/bin/jboss-cli.xml
file:
-
Update the value of
<default-protocol>
tohttps-remoting
. -
In
<default-controller>
, update the value of<protocol>
tohttps-remoting
. -
In
<default-controller>
, update the value of<port>
to9993
.
Example: jboss-cli.xml
<jboss-cli xmlns="urn:jboss:cli:2.0"> <default-protocol use-legacy-override="true">https-remoting</default-protocol> <!-- The default controller to connect to when 'connect' command is executed w/o arguments --> <default-controller> <protocol>https-remoting</protocol> <host>localhost</host> <port>9993</port> </default-controller> ...
The next time you connect to the management interface using the management CLI, you must accept the server certificate and authenticate against the ManagementRealmHTTPS
security realm:
Example: Accepting Server Certificate and Authenticating
$ ./jboss-cli.sh -c Unable to connect due to unrecognised server certificate Subject - CN=appserver,OU=Sales,O=Systems Inc,L=Raleigh,ST=NC,C=US Issuer - CN=appserver, OU=Sales, O=Systems Inc, L=Raleigh, ST=NC, C=US Valid From - Tue Jun 28 13:38:48 CDT 2016 Valid To - Thu Jun 28 13:38:48 CDT 2018 MD5 : 76:f4:81:8b:7e:c3:be:6d:ee:63:c1:7a:b7:b8:f0:fb SHA1 : ea:e3:f1:eb:53:90:69:d0:c9:69:4a:5a:a3:20:8f:76:c1:e6:66:b6 Accept certificate? [N]o, [T]emporarily, [P]ermenantly : p Authenticating against security realm: ManagementRealmHTTPS Username: httpUser Password: [standalone@localhost:9993 /]
In cases where you have both a security-realm
and ssl-context
defined, JBoss EAP will use the SSL/TLS configuration provided by ssl-context
.
2.2.9. Setting up Two-way SSL/TLS for the Management Interfaces with Legacy Core Management Authentication
Two-way SSL/TLS authentication, also known as client authentication, authenticates both the client and the server using SSL/TLS certificates. This differs from the Configure the Management Interfaces for One-way SSL/TLS section in that both the client and server each have a certificate. This provides assurance that not only is the server who it says it is, but the client is also who it says it is.
In this section the following conventions are used:
- HOST1
-
The JBoss server hostname. For example:
jboss.redhat.com
. - HOST2
-
A suitable name for the client. For example:
myclient
. Note this is not necessarily an actual hostname. - CA_HOST1
-
The DN (distinguished name) to use for the HOST1 certificate. For example:
cn=jboss,dc=redhat,dc=com
. - CA_HOST2
-
The DN (distinguished name) to use for the HOST2 certificate. For example:
cn=myclient,dc=redhat,dc=com
.
Prerequisites
If a password vault is used to store the keystore and truststore passwords, which is recommended, the password vault should already be created. For more information on the password vault, see the Password Vault section as well as the Password Vault System section of the Red Hat JBoss Enterprise Application Platform 7 Security Architecture guide.
Red Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages.
Generate the keystores.
$ keytool -genkeypair -alias HOST1_alias -keyalg RSA -keysize 1024 -validity 365 -keystore HOST1.keystore.jks -dname "CA_HOST1" -keypass secret -storepass secret $ keytool -genkeypair -alias HOST2_alias -keyalg RSA -keysize 1024 -validity 365 -keystore HOST2.keystore.jks -dname "CA_HOST2" -keypass secret -storepass secret
Export the certificates.
$ keytool -exportcert -keystore HOST1.keystore.jks -alias HOST1_alias -keypass secret -storepass secret -file HOST1.cer $ keytool -exportcert -keystore HOST2.keystore.jks -alias HOST2_alias -keypass secret -storepass secret -file HOST2.cer
Import the certificates into the opposing truststores.
$ keytool -importcert -keystore HOST1.truststore.jks -storepass secret -alias HOST2_alias -trustcacerts -file HOST2.cer $ keytool -importcert -keystore HOST2.truststore.jks -storepass secret -alias HOST1_alias -trustcacerts -file HOST1.cer
Define a CertificateRealm.
Define a CertificateRealm in the configuration for the server (
host.xml
orstandalone.xml
) and point the interface to it. This can be done using the following commands:/core-service=management/security-realm=CertificateRealm:add() /core-service=management/security-realm=CertificateRealm/server-identity=ssl:add(keystore-path=/path/to/HOST1.keystore.jks, keystore-password=secret,alias=HOST1_alias) /core-service=management/security-realm=CertificateRealm/authentication=truststore:add(keystore-path=/path/to/HOST1.truststore.jks,keystore-password=secret)
Change the
security-realm
of thehttp-interface
to the new CertificateRealm./core-service=management/management-interface=http-interface:write-attribute(name=security-realm,value=CertificateRealm)
Add the SSL/TLS configuration for the CLI.
ImportantIn addition to adding the two-way SSL/TLS, the management interface should also be configured to bind to HTTPS. For details, see Ensure the Management Interfaces Bind to HTTPS in the section entitled Configure the Management Interfaces for One-way SSL/TLS with Legacy Core Management Authentication.
Add the SSL/TLS configuration for the CLI, which uses
EAP_HOME/bin/jboss-cli.xml
as a settings file.To store the keystore and truststore passwords in plain text, edit
EAP_HOME/bin/jboss-cli.xml
and add the SSL/TLS configuration using the appropriate values for the variables:Example: jboss-cli.xml Storing Keystore and Truststore Passwords in Plain Text
<ssl> <alias>HOST2_alias</alias> <key-store>/path/to/HOST2.keystore.jks</key-store> <key-store-password>secret</key-store-password> <trust-store>/path/to/HOST2.truststore.jks</trust-store> <trust-store-password>secret</trust-store-password> <modify-trust-store>true</modify-trust-store> </ssl>
To use the keystore and truststore passwords stored in a password vault, you need to add the vault configuration and appropriate vault values to
EAP_HOME/bin/jboss-cli.xml
:Example: jboss-cli.xml Storing Keystore and Truststore Passwords in a Password Vault
<ssl> <vault> <vault-option name="KEYSTORE_URL" value="path-to/vault/vault.keystore"/> <vault-option name="KEYSTORE_PASSWORD" value="MASK-5WNXs8oEbrs"/> <vault-option name="KEYSTORE_ALIAS" value="vault"/> <vault-option name="SALT" value="12345678"/> <vault-option name="ITERATION_COUNT" value="50"/> <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/> </vault> <alias>HOST2_alias</alias> <key-store>/path/to/HOST2.keystore.jks</key-store> <key-store-password>VAULT::VB::cli_pass::1</key-store-password> <key-password>VAULT::VB::cli_pass::1</key-password> <trust-store>/path/to/HOST2.truststore.jks</trust-store> <trust-store-password>VAULT::VB::cli_pass::1</trust-store-password> <modify-trust-store>true</modify-trust-store> </ssl>
In cases where you have both a security-realm
and ssl-context
defined, JBoss EAP will use the SSL/TLS configuration provided by ssl-context
.
2.2.10. HTTPS Listener Reference
For a full list of attributes available for the HTTPS listener, see the Undertow Subsystem Attributes section in the JBoss EAP Configuration Guide.
2.2.10.1. About Cipher Suites
You can configure a list of the encryption ciphers which are allowed. For JSSE syntax, it must be a comma-separated list. For OpenSSL syntax, it must be a colon-separated list. Ensure that only one syntax is used. The default is the JVM default.
Using weak ciphers is a significant security risk. See NIST Guidelines for NIST recommendations on cipher suites.
See the OpenSSL documentation for a list of available OpenSSL ciphers. Note that the following are not supported:
- @SECLEVEL
- SUITEB128
- SUITEB128ONLY
- SUITEB192
See the Java documentation for a list of the standard JSSE ciphers.
To update the list of enabled cipher suites, use the enabled-cipher-suites attribute of the HTTPS listener in the undertow
subsystem.
Example: Management CLI Command for Updating the List of Enabled Cipher Suites
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=enabled-cipher-suites,value="TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA")
The example only lists two possible ciphers, but real-world examples will likely use more.
2.2.11. Enable FIPS 140-2 Cryptography for SSL/TLS on Red Hat Enterprise Linux 7
You can configure Undertow to use FIPS 140-2 compliant cryptography for SSL/TLS. The scope of this configuration example is limited to Red Hat Enterprise Linux 7, using the Mozilla NSS library in FIPS mode.
Red Hat Enterprise Linux 7 must already be configured to be FIPS 140-2 compliant. For more information, see the solution titled How can I make RHEL 6 or RHEL 7 FIPS 140-2 compliant?, which is located on the Red Hat Customer Portal.
Using the TLS 1.2 protocol when running JBoss EAP in FIPS mode can cause a NoSuchAlgorithmException
to occur. More details on this issue can be found in the solution titled NoSuchAlgorithmException: no such algorithm: SunTls12MasterSecret, which is located on the Red Hat Customer Portal.
Therefore, it is not possible to configure HTTP/2 in FIPS mode because HTTP/2 requires the TLS 1.2 protocol. FIPS mode (PKCS11) supports the TLS 1 and the TLS 1.1 protocols so you can use:
- TLS 1.1 in case of Oracle/OpenJDK
- TLS 1 in case of IBM java
To configure Undertow to use FIPS 140-2 compliant cryptography for SSL/TLS, you must do the following:
- Configure the NSS database.
- Configure the management CLI for FIPS 140-2 compliant cryptography for SSL/TLS.
-
Configure the
undertow
subsystem to use either Elytron or the legacy core management authentication.
The OpenSSL provider requires a private key, but it is not possible to retrieve a private key from the PKCS11 store. FIPS does not allow the export of unencrypted keys from FIPS compliant cryptographic module. Therefore, for both the elytron
subsystem as well as legacy security, it is not possible to use the OpenSSL provider for TLS when in FIPS mode.
2.2.11.1. Configuring the NSS database
Create a directory owned by the appropriate user to house the NSS database.
Example Commands for Creating the NSS Database Directory
$ mkdir -p /usr/share/jboss-as/nssdb $ chown jboss /usr/share/jboss-as/nssdb $ modutil -create -dbdir /usr/share/jboss-as/nssdb
NoteThe jboss user is only an example. You need to replace it with a user on your operating system that you plan on using for running JBoss EAP.
Create the NSS configuration file:
/usr/share/jboss-as/nss_pkcsll_fips.cfg
.It must specify:
- a name
- the directory where the NSS library is located
the directory where the NSS database was created in the previous step
Example:
nss_pkcsll_fips.cfg
name = nss-fips nssLibraryDirectory=/usr/lib64 nssSecmodDirectory=/usr/share/jboss-as/nssdb nssDbMode = readOnly nssModule = fips
NoteIf you are not running a 64-bit version of Red Hat Enterprise Linux 6 then set
nssLibraryDirectory
to/usr/lib
instead of/usr/lib64
.
Edit the
$JAVA_HOME/jre/lib/security/java.security
configuration file.Add the following line to
$JAVA_HOME/jre/lib/security/java.security
:Example:
java.security
security.provider.1=sun.security.pkcs11.SunPKCS11 /usr/share/jboss-as/nss_pkcsll_fips.cfg
NoteThe
nss_pkcsll_fips.cfg
configuration file specified in the above line is the file created in the previous step.You also need to update the following link in
$JAVA_HOME/jre/lib/security/java.security
from:security.provider.5=com.sun.net.ssl.internal.ssl.Provider
to
security.provider.5=com.sun.net.ssl.internal.ssl.Provider SunPKCS11-nss-fips
ImportantAny other
security.provider.X
lines in this file, for examplesecurity.provider.2
, must have the value of their X increased by one to ensure that this provider is given priority.Run the
modutil
command on the NSS database directory you created in the previous step to enable FIPS mode.modutil -fips true -dbdir /usr/share/jboss-as/nssdb
NoteYou may get a security library error at this point requiring you to regenerate the library signatures for some of the NSS shared objects.
Set the password on the FIPS token.
The name of the token must be NSS FIPS 140-2 Certificate DB.
modutil -changepw "NSS FIPS 140-2 Certificate DB" -dbdir /usr/share/jboss-as/nssdb
ImportantThe password used for the FIPS token must be a FIPS compliant password. If the password is not strong enough, you may receive an error: ERROR: Unable to change password on token "NSS FIPS 140-2 Certificate DB".
Create a certificate using the NSS tools.
Example Command
$ certutil -S -k rsa -n undertow -t "u,u,u" -x -s "CN=localhost, OU=MYOU, O=MYORG, L=MYCITY, ST=MYSTATE, C=MY" -d /usr/share/jboss-as/nssdb
Verify that the JVM can read the private key from the PKCS11 keystore by running the following command:
$ keytool -list -storetype pkcs11
Once you have FIPS enabled, you may see the following error when starting JBoss EAP:
10:16:13,993 ERROR [org.jboss.msc.service.fail] (MSC service thread 1-1) MSC000001: Failed to start service jboss.server.controller.management.security_realm.ApplicationRealm.key-manager: org.jboss.msc.service.StartException in service jboss.server.controller.management.security_realm.ApplicationRealm.key-manager: WFLYDM0018: Unable to start service at org.jboss.as.domain.management.security.AbstractKeyManagerService.start(AbstractKeyManagerService.java:85) at org.jboss.msc.service.ServiceControllerImpl$StartTask.startService(ServiceControllerImpl.java:1963) at org.jboss.msc.service.ServiceControllerImpl$StartTask.run(ServiceControllerImpl.java:1896) at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142) at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617) at java.lang.Thread.run(Thread.java:745) Caused by: java.security.KeyStoreException: FIPS mode: KeyStore must be from provider SunPKCS11-nss-fips at sun.security.ssl.KeyManagerFactoryImpl$SunX509.engineInit(KeyManagerFactoryImpl.java:67) at javax.net.ssl.KeyManagerFactory.init(KeyManagerFactory.java:256) at org.jboss.as.domain.management.security.AbstractKeyManagerService.createKeyManagers(AbstractKeyManagerService.java:130) at org.jboss.as.domain.management.security.AbstractKeyManagerService.start(AbstractKeyManagerService.java:83) ... 5 more
This message will appear if you have any existing key managers configured, such as the default key manager in legacy core management authentication, that do not use FIPS 140-2 compliant cryptography.
2.2.11.2. Configure the Management CLI for FIPS 140-2 Compliant Cryptography for SSL/TLS
You must configure the JBoss EAP management CLI to work in an environment with FIPS 140-2 compliant cryptography for SSL/TLS enabled. By default, if you try to use the management CLI in such an environment, the following exception is thrown: org.jboss.as.cli.CliInitializationException: java.security.KeyManagementException: FIPS mode: only SunJSSE TrustManagers may be used
.
If you are using the legacy
security
subsystem:Update the
javax.net.ssl.keyStore
andjavax.net.ssl.trustStore
system properties in thejboss-cli.sh
file, as shown below:JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=NONE -Djavax.net.ssl.trustStoreType=PKCS11" JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.keyStore=NONE -Djavax.net.ssl.keyStoreType=PKCS11 -Djavax.net.ssl.keyStorePassword=P@ssword123"
If you are using the
elytron
subsystem:Create an XML configuration file for the management CLI with the following contents:
Example:
cli-wildfly-config.xml
<configuration> <authentication-client xmlns="urn:elytron:1.0.1"> <key-stores> <key-store name="truststore" type="PKCS11"> <key-store-clear-password password="P@ssword123"/> </key-store> </key-stores> <ssl-contexts> <ssl-context name="client-cli-context"> <trust-store key-store-name="truststore"/> <cipher-suite selector="${cipher.suite.filter}"/> <protocol names="TLSv1.1"/> </ssl-context> </ssl-contexts> <ssl-context-rules> <rule use-ssl-context="client-cli-context"/> </ssl-context-rules> </authentication-client> </configuration>
NoteIf you are using the IBM JDK, see the IBM management CLI configuration example for the specific configuration required.
When starting the management CLI, pass the configuration file to the management CLI script using the
-Dwildfly.config.url
property. For example:$ jboss-cli.sh -Dwildfly.config.url=cli-wildfly-config.xml
2.2.11.3. Configure the Elytron and Undertow Subsystems
Add the FIPS 140-2 compliant cryptography
key-store
,key-manager
andssl-context
./subsystem=elytron/key-store=fipsKS:add(type=PKCS11,provider="SunPKCS11-nss-fips",credential-reference={clear-text="P@ssword123"}) /subsystem=elytron/key-manager=fipsKM:add(key-store=fipsKS,algorithm="SunX509",provider=SunPKCS11-nss-fips,credential-reference={clear-text="P@ssword123"}) /subsystem=elytron/server-ssl-context=fipsSSC:add(key-manager=fipsKM,protocols=["TLSv1.1"])
Update the
undertow
subsystem to use the newssl-context
.Notehttps-listener
must always have either asecurity-realm
orssl-context
configured. When changing between the two configurations, the commands must be executed as a single batch, as shown below.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=fipsSSC) run-batch reload
In the elytron
subsystem, OpenJDK and Oracle JDK in FIPS mode restrict the usage of any advanced features that are based on providing custom KeyManager
or TrustManager
implementations. The following configuration attributes do not work:
On the client:
-
ssl-context.key-store-ssl-certificate
-
On the server:
-
server-ssl-context.security-domain
-
trust-manager.certificate-revocation-list
-
2.2.11.4. Configure Undertow with the Legacy Core Management Authentication
Optionally, you can still use the legacy core management authentication instead of the elytron
subsystem to complete the setup of FIPS 140-2 compliant cryptography for SSL/TLS:
Configure Undertow to use SSL/TLS.
NoteThe following commands below must either be run in batch mode, or the server must be reloaded after adding the ssl server identity. The example below is shown using batch mode.
batch /core-service=management/security-realm=HTTPSRealm:add /core-service=management/security-realm=HTTPSRealm/server-identity=ssl:add(keystore-provider=PKCS11, keystore-password="strongP@ssword1") /subsystem=undertow/server=default-server/https-listener=https:add(socket-binding=https, security-realm=HTTPSRealm, enabled-protocols="TLSv1.1") run-batch
The basic details for configuring Undertow to SSL/TLS are covered in Setting up an SSL/TLS for Applications.
Configure the cipher suites used by Undertow.
Once you have SSL/TLS configured, you need to configure the https listener and security realm to have a specific set of cipher suites enabled:
Required Cipher Suites
SSL_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_DHE_DSS_WITH_AES_256_CBC_SHA, TLS_DHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_RSA_WITH_AES_128_CBC_SHA, TLS_ECDH_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_anon_WITH_AES_128_CBC_SHA, TLS_ECDH_anon_WITH_AES_256_CBC_SHA
The basics behind enabling cipher suites for the https listener are covered in About Cipher Suites. To enable cipher suites on the https listener:
Example Command for Enabling Cipher Suites on the Https Listener
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=enabled-cipher-suites,value="SSL_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_DSS_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_DSS_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_anon_WITH_AES_128_CBC_SHA,TLS_ECDH_anon_WITH_AES_256_CBC_SHA")
Enable cipher suites on the security realm.
Example Command for Enabling Cipher Suites on the Security Realm
/core-service=management/security-realm=HTTPSRealm/server-identity=ssl:write-attribute(name=enabled-cipher-suites, value=[SSL_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, TLS_DHE_DSS_WITH_AES_256_CBC_SHA, TLS_DHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_RSA_WITH_AES_128_CBC_SHA, TLS_ECDH_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_anon_WITH_AES_128_CBC_SHA, TLS_ECDH_anon_WITH_AES_256_CBC_SHA])
2.2.12. FIPS 140-2 Compliant Cryptography on IBM JDK
On the IBM JDK, the IBM Java Cryptographic Extension (JCE) IBMJCEFIPS provider and the IBM Java Secure Sockets Extension (JSSE) FIPS 140-2 Cryptographic Module (IBMJSSE2) for multi-platforms provide FIPS 140-2 compliant cryptography.
For more information on the IBMJCEFIPS provider, see the IBM Documentation for IBM JCEFIPS and NIST IBMJCEFIPS – Security Policy. For more information on IBMJSSE2, see Running IBMJSSE2 in FIPS mode.
2.2.12.1. Key Storage
The IBM JCE does not provide a keystore. The keys are stored on the computer and do not leave its physical boundary. If the keys are moved between computers they must be encrypted.
To run keytool
in FIPS-compliant mode use the -providerClass
option on each command like this:
keytool -list -storetype JCEKS -keystore mystore.jck -storepass mystorepass -providerClass com.ibm.crypto.fips.provider.IBMJCEFIPS
2.2.12.2. Management CLI Configuration
To configure the management CLI for FIPS 140-2 compliant cryptography on the IBM JDK, you must use a management CLI configuration file specifically for the IBM JDK, such as the following:
Example: cli-wildfly-config-ibm.xml
<configuration> <authentication-client xmlns="urn:elytron:1.0.1"> <key-stores> <key-store name="truststore" type="JKS"> <file name="/path/to/truststore"/> <key-store-clear-password password="P@ssword123"/> </key-store> </key-stores> <ssl-contexts> <ssl-context name="client-cli-context"> <trust-store key-store-name="truststore"/> <cipher-suite selector="${cipher.suite.filter}"/> <protocol names="TLSv1"/> </ssl-context> </ssl-contexts> <ssl-context-rules> <rule use-ssl-context="client-cli-context"/> </ssl-context-rules> </authentication-client> </configuration>
2.2.12.3. Examine FIPS Provider Information
To examine information about the IBMJCEFIPS used by the server, enable debug-level logging by adding -Djavax.net.debug=true
to the standalone.conf
or domain.conf
files. Information about the FIPS provider is logged to the server.log
file, for example:
04:22:45,685 INFO [stdout] (http-/127.0.0.1:8443-1) JsseJCE: Using MessageDigest SHA from provider IBMJCEFIPS version 1.7 04:22:45,689 INFO [stdout] (http-/127.0.0.1:8443-1) DHCrypt: DH KeyPairGenerator from provider from init IBMJCEFIPS version 1.7 04:22:45,754 INFO [stdout] (http-/127.0.0.1:8443-1) JsseJCE: Using KeyFactory DiffieHellman from provider IBMJCEFIPS version 1.7 04:22:45,754 INFO [stdout] (http-/127.0.0.1:8443-1) JsseJCE: Using KeyAgreement DiffieHellman from provider IBMJCEFIPS version 1.7 04:22:45,754 INFO [stdout] (http-/127.0.0.1:8443-1) DHCrypt: DH KeyAgreement from provider IBMJCEFIPS version 1.7 04:22:45,754 INFO [stdout] (http-/127.0.0.1:8443-1) DHCrypt: DH KeyAgreement from provider from initIBMJCEFIPS version 1.7
2.2.13. Starting a Managed Domain when the JVM is Running in FIPS Mode
It is assumed you have a managed domain, FIPS configured, as well as all necessary certificates configured. This includes having imported the domain controller’s certificate into each controller’s truststore. For more details on configuring a managed domain, see the Domain Management section in the JBoss EAP Configuration Guide. For more details on configuring FIPS, see Enable FIPS 140-2 Cryptography for SSL/TLS on Red Hat Enterprise Linux 7.
You need to update each host controller and the master domain controller to use SSL/TLS for communication.
Red Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 in all affected packages.
Create an SSL/TLS security realm on the master domain controller.
You need to create an SSL/TLS security realm on the master domain controller configured to use your NSS database as a PKCS11 provider.
Example: Security Realm on the Master Domain Controller
<security-realm name="HTTPSRealm"> <server-identities> <ssl> <engine enabled-protocols="TLSv1.1"/> <keystore provider="PKCS11" keystore-password="strongP@ssword1"/> </ssl> </server-identities> <authentication> <local default-user="\$local"/> <properties path="https-users.properties" relative-to="jboss.domain.config.dir"/> </authentication> </security-realm>
Create an SSL/TLS security realm on each host controller.
You need to create a security realm with an SSL/TLS truststore for authentication.
Example: Security Realm on Each Host Controller
<security-realm name="HTTPSRealm"> <authentication> <truststore provider="PKCS11" keystore-password="strongP@ssword1"/> </authentication> </security-realm>
NoteYou need to repeat this process on each host.
Secure the native interface on the master domain controller.
You need to ensure that the native interface on the master domain controller is secured with the security realm you just created.
Example: Native Interface
<management-interfaces> ... <native-interface security-realm="HTTPSRealm"> <socket interface="management" port="${jboss.management.native.port:9999}"/> </native-interface> </management-interfaces>
Use the SSL/TLS realm on each host controller to connect to the master domain controller.
You need to update the security realm used for connecting to the master domain controller. This change must be done directly in the host controller’s configuration file, for example
host.xml
orhost-slave.xml
, while the server is not running.Example: Host Controller Configuration File
<domain-controller> <remote security-realm="HTTPSRealm"> <discovery-options> <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote}" host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}"/> </discovery-options> </remote> </domain-controller>
Update how each server connects back to its host controller.
You also need to update how each server connects back to its host controller.
Example: Server Configuration
<server name="my-server" group="my-server-group"> <ssl ssl-protocol="TLS" trust-manager-algorithm="SunX509" truststore-type="PKCS11" truststore-password="strongP@ssword1"/> </server>
Configure two-way SSL/TLS in a managed domain.
To enable two-way SSL/TLS, add a truststore authentication method to the SSL/TLS security realm for the master domain controller, execute the following management CLI commands:
/host=master/core-service=management/security-realm=HTTPSRealm/authentication=truststore:add(keystore-provider="PKCS11",keystore-password="strongP@ssword1") reload --host=master
You also need to update each host controller’s security realm to have an SSL server identity, execute the following management CLI commands:
/host=host1/core-service=management/security-realm=HTTPSRealm/server-identity=ssl:add(keystore-provider=PKCS11, keystore-password="strongP@ssword1",enabled-protocols=["TLSv1.1"]) reload --host=host1
ImportantYou also need to ensure that each host’s certificate is imported into the domain controller’s truststore.
2.3. Security Auditing
Security auditing refers to triggering events, such as writing to a log, in response to an event that happens within the security
subsystem or the management interfaces. Auditing mechanisms are configured as part of a security domain or management interface.
Auditing uses provider modules. Both included provider modules as well as custom implementations may be used.
2.3.1. Configure Security Auditing for the Legacy Security Domains
To configure security auditing settings for a security domain, the following steps must be performed from the management console:
Open the security domain’s detailed view.
- Click Configuration at the top of the screen.
- In a managed domain, select a profile to modify from the Profile selection box at the top left.
- Click on Subsystems, then Security.
- Click on the security domain to edit and click View.
Navigate to the auditing configuration.
Click on Audit on the left side of the screen.
The configuration area is divided into two areas: Provider Modules and Details. The provider module is the basic unit of configuration. A security domain can include several provider modules each of which can include attributes and options.
Add a provider module.
Click Add and fill in the Code section with the class name of the provider module. Also fill in the Name section with the desired name.
Verify that the module is working.
The goal of an audit module is to provide a way to monitor the events in the
security
subsystem. This monitoring can be done by means of writing to a log file, email notifications, or any other measurable auditing mechanism.For example, JBoss EAP includes the
org.jboss.security.audit.providers.LogAuditProvider
module by default. If enabled following the steps above, this audit module writes security notifications to anaudit.log
file in the log subfolder within theEAP_HOME
directory.To verify if the steps above have worked in the context of the
org.jboss.security.audit.providers.LogAuditProvider
, perform an action that is likely to trigger a notification and then check the audit log file.Optional: Add, edit, or remove module options.
To add options to your module, click its entry in the Modules list, and select the Module Options tab in the Details section of the page. Click Add, and provide the key and value for the option.
To edit an option that already exists, click Remove to remove it, and click Add to add it again with the correct options.
2.4. Configure One-way and Two-way SSL/TLS for Applications
2.4.1. Automatic Self-signed Certificate Creation for Applications
When using the legacy security realms, JBoss EAP provides automatic generation of self-signed certificate for development purposes.
Example: Server Log Showing Self-signed Certificate Creation
15:26:09,031 WARN [org.jboss.as.domain.management.security] (MSC service thread 1-7) WFLYDM0111: Keystore /path/to/jboss/standalone/configuration/application.keystore not found, it will be auto generated on first use with a self signed certificate for host localhost ... 15:26:10,076 WARN [org.jboss.as.domain.management.security] (MSC service thread 1-2) WFLYDM0113: Generated self signed certificate at /path/to/jboss/configuration/application.keystore. Please note that self signed certificates are not secure, and should only be used for testing purposes. Do not use this self signed certificate in production. SHA-1 fingerprint of the generated key is 00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33 SHA-256 fingerprint of the generated key is 00:11:22:33:44:55:66:77:88:99:00:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee ...
This certificate is created for testing purposes and is assigned to the HTTPS interface used by applications. The keystore containing the certificate will be generated if the file does not exist the first time the HTTPS interface is accessed.
Example: Default ApplicationRealm Using the Self-signed Certificate
<security-realm name="ApplicationRealm"> <server-identities> <ssl> <keystore path="application.keystore" relative-to="jboss.server.config.dir" keystore-password="password" alias="server" key-password="password" generate-self-signed-certificate-host="localhost"/> </ssl> </server-identities> ... </security-realm>
Example: Default HTTPS Interface Configuration
<subsystem xmlns="urn:jboss:domain:undertow:4.0"> ... <server name="default-server"> ... <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/> <host name="default-host" alias="localhost"> ...
If you want to disable the self-signed certificate creation, you will need to remove the generate-self-signed-certificate-host="localhost"
from the server keystore configuration. The generate-self-signed-certificate-host
attribute holds the host name for which the self-signed certificate should be generated.
This self-signed certificate is intended for testing purposes only and is not intended for use in production environments. For more information on configuring SSL/TLS for applications with Elytron, see the Enable One-way SSL/TLS for Applications using the Elytron Subsystem and Enable Two-way SSL/TLS for Applications using the Elytron Subsystem sections. For more information on configuring SSL/TLS for applications with legacy security, see the Enable One-way SSL/TLS for Applications Using Legacy Security Realms and Enable Two-way SSL/TLS for Applications Using Legacy Security Realms sections.
2.4.2. Using Elytron
2.4.2.1. Enable One-way SSL/TLS for Applications Using the Elytron Subsystem
In JBoss EAP, you can use the elytron
subsystem, along with the undertow
subsystem, to enable one-way SSL/TLS for deployed applications.
Obtain or generate your keystore.
Before enabling one-way SSL/TLS in JBoss EAP, you must obtain or generate the keystore you plan on using. To generate an example keystore in Red Hat Enterprise Linux 7:
$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore /path/to/keystore.jks -dname "CN=localhost" -keypass secret -storepass secret
Configure a
key-store
in JBoss EAP./subsystem=elytron/key-store=httpsKS:add(path=/path/to/keystore.jks, credential-reference={clear-text=secret}, type=JKS)
NoteThe previous command uses an absolute path to the keystore. Alternatively you can use the
relative-to
attribute to specify the base directory variable andpath
attribute to specify a relative path./subsystem=elytron/key-store=httpsKS:add(path=keystore.jks, relative-to=jboss.server.config.dir, credential-reference={clear-text=secret}, type=JKS)
Configure a
key-manager
that references yourkey-store
./subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS, algorithm="SunX509", credential-reference={clear-text=secret})
ImportantYou need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the
PKIX
andSunX509
algorithms.The example command above uses
SunX509
for the key manager algorithm.Configure a
server-ssl-context
that references yourkey-manager
./subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM, protocols=["TLSv1.2"])
ImportantYou need to determine what SSL/TLS protocols you want to support. The example command above uses
TLSv1.2
. You can use thecipher-suite-filter
argument to specify which cipher suites are allowed, and theuse-cipher-suites-order
argument to honor server cipher suite order. Theuse-cipher-suites-order
attribute by default is set totrue
. This differs from the legacysecurity
subsystem behavior, which defaults to honoring client cipher suite order.WarningRed Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages.
Check and see if the
https-listener
is configured to use a legacy security realm for its SSL configuration./subsystem=undertow/server=default-server/https-listener=https:read-attribute(name=security-realm) { "outcome" => "success", "result" => "ApplicationRealm" }
The above command shows that the
https-listener
is configured to use theApplicationRealm
legacy security realm for its SSL configuration. Undertow cannot reference both a legacy security realm and anssl-context
in Elytron at the same time so you must remove the reference to the legacy security realm.NoteIf the result is
undefined
, you do not need to remove the reference to the security realm in the next step.Remove the reference to the legacy security realm, and update the
https-listener
to use thessl-context
from Elytron.Notehttps-listener
must always have either asecurity-realm
orssl-context
configured. When changing between the two configurations, the commands must be executed as a single batch, as shown below.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=httpsSSC) run-batch
Reload the server.
reload
One-way SSL/TLS is now enabled for applications.
2.4.2.2. Enable Two-way SSL/TLS for Applications Using the Elytron Subsystem
In JBoss EAP, you can use the elytron
subsystem, along with the undertow
subsystem, to enable two-way SSL/TLS for deployed applications.
Obtain or generate your keystore.
Before enabling two-way SSL/TLS in JBoss EAP, you must obtain or generate the keystores, truststores and certificates you plan on using. To generate an example set of keystores, truststores, and certificates in Red Hat Enterprise Linux 7:
Example: Server and Client Keystores:
$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore server.keystore.jks -dname "CN=localhost" -keypass secret -storepass secret $ keytool -genkeypair -alias client -keyalg RSA -keysize 1024 -validity 365 -keystore client.keystore.jks -dname "CN=client" -keypass secret -storepass secret
Example: Export the Server and Client Certificates:
$ keytool -exportcert -keystore server.keystore.jks -alias localhost -keypass secret -storepass secret -file server.cer $ keytool -exportcert -keystore client.keystore.jks -alias client -keypass secret -storepass secret -file client.cer
Example: Import the Server and Client Certificates Into the Opposing Truststores:
$ keytool -importcert -keystore server.truststore.jks -storepass secret -alias client -trustcacerts -file client.cer $ keytool -importcert -keystore client.truststore.jks -storepass secret -alias localhost -trustcacerts -file server.cer
Configure a
key-store
for server keystore and truststore in JBoss EAP./subsystem=elytron/key-store=twoWayKS:add(path=/path/to/server.keystore.jks, credential-reference={clear-text=secret}, type=JKS) /subsystem=elytron/key-store=twoWayTS:add(path=/path/to/server.truststore.jks, credential-reference={clear-text=secret}, type=JKS)
NoteThe previous command uses an absolute path to the keystore. Alternatively you can use the
relative-to
attribute to specify the base directory variable andpath
attribute to specify a relative path./subsystem=elytron/key-store=myKS:add(path=keystore.jks, relative-to=jboss.server.config.dir, credential-reference={clear-text=secret}, type=JKS)
Configure a
key-manager
that references your keystorekey-store
./subsystem=elytron/key-manager=twoWayKM:add(key-store=twoWayKS, algorithm="SunX509", credential-reference={clear-text=secret})
ImportantYou need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the
PKIX
andSunX509
algorithms.The example command below uses
SunX509
for the key manager algorithm.Configure a
trust-manager
that references your truststorekey-store
./subsystem=elytron/trust-manager=twoWayTM:add(key-store=twoWayTS, algorithm="SunX509")
ImportantYou need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the
PKIX
andSunX509
algorithms.The example command above uses
SunX509
for the key manager algorithm.Configure a
server-ssl-context
that references yourkey-manager
,trust-manager
, and enables client authentication:/subsystem=elytron/server-ssl-context=twoWaySSC:add(key-manager=twoWayKM, protocols=["TLSv1.2"], trust-manager=twoWayTM, need-client-auth=true)
ImportantYou need to determine what SSL/TLS protocols you want to support. The example command above uses
TLSv1.2
. You can use thecipher-suite-filter
argument to specify which cipher suites are allowed, and theuse-cipher-suites-order
argument to honor server cipher suite order. Theuse-cipher-suites-order
attribute by default is set totrue
. This differs from the legacysecurity
subsystem behavior, which defaults to honoring client cipher suite order.WarningRed Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages.
Check and see if the
https-listener
is configured to use a legacy security realm for its SSL configuration./subsystem=undertow/server=default-server/https-listener=https:read-attribute(name=security-realm) { "outcome" => "success", "result" => "ApplicationRealm" }
The above command shows that the
https-listener
is configured to use theApplicationRealm
legacy security realm for its SSL configuration. Undertow cannot reference both a legacy security realm and anssl-context
in theelytron
subsystem at the same time. So you must remove the reference to the legacy security realm.NoteIf the result is
undefined
, you do not need to remove the reference to the security realm in the next step.Remove the reference to the legacy security realm, and update the
https-listener
to use thessl-context
from Elytron.Notehttps-listener
must always have either asecurity-realm
orssl-context
configured. When changing between the two configurations, the commands must be executed as a single batch, as shown below.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=twoWaySSC) run-batch
Reload the server.
reload
Configure your client to use the client certificate.
You need to configure your client to present the trusted client certificate to the server to complete the two-way SSL/TLS authentication. For example, if using a browser, you need to import the trusted certificate into the browser’s trust store.
This procedure forces a two-way SSL/TLS but it does not change the original authentication method of the application.
If you want to change the original authentication method, see Configure Authentication with Certificates in How to Configure Identity Management for JBoss EAP.
Two-way SSL/TLS is now enabled for applications.
2.4.3. Using Legacy Security Realms
As a prerequisite, an SSL/TLS encryption key and certificate should be created and placed in an accessible directory. Additionally, relevant information, such as keystore aliases and passwords, desired cipher suites, should also be accessible. For examples on generating SSL/TLS Keys and Certificates, see the first two steps in the Setting up Two-way SSL/TLS for the Management Interfaces section. For more information about the HTTPS listener, including cipher suites, see the HTTPS Listener Reference section.
2.4.3.1. Enable One-way SSL/TLS for Applications Using Legacy Security Realms
This example assumes that the keystore, identity.jks
, has been copied to the server configuration directory and configured with the given properties. Administrators should substitute their own values for the example ones.
The management CLI commands shown assume that you are running a JBoss EAP standalone server. For more details on using the management CLI for a JBoss EAP managed domain, see the JBoss EAP Management CLI Guide.
Add and configure an HTTPS security realm first. Once the HTTPS security realm has been configured, configure an
https-listener
in theundertow
subsystem that references the security realm:batch /core-service=management/security-realm=HTTPSRealm:add /core-service=management/security-realm=HTTPSRealm/server-identity=ssl:add(keystore-path=identity.jks, keystore-relative-to=jboss.server.config.dir, keystore-password=password1, alias=appserver) /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=security-realm, value=HTTPSRealm) run-batch
WarningRed Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages.
- Restart the JBoss EAP instance for the changes to take effect.
2.4.3.2. Enable Two-way SSL/TLS for Applications Using Legacy Security Realms
Setting up two-way SSL/TLS for applications follows many of the same procedures outlined in Setting up Two-way SSL/TLS for the Management Interfaces. To set up two-way SSL/TLS for applications, you need to do the following:
- Generate the stores for both the client and server
- Export the certificates for both the client and server
- Import the certificates into the opposing truststores
-
Define a security realm, for example
CertificateRealm
, on the server that uses the server’s keystore and truststore -
Update the
undertow
subsystem to use the security realm and require client verification
The first four steps are covered in Setting up Two-way SSL/TLS for the Management Interfaces.
If the server has not been reloaded since the new security realm has been added, you must reload the server before performing the next step.
Update the Undertow Subsystem
Once the keystores, certificates, truststores, and security realms have been created and configured, you need to add an HTTPS listener to the undertow
subsystem, use the security realm you created, and require client verification:
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=security-realm, value=CertificateRealm) /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=verify-client, value=REQUIRED)
You must reload the server for these changes to take effect.
Any client connecting to a JBoss EAP instance with two-way SSL/TLS enabled for applications must have access to a client certificate or keystore, in other words a client keystore whose certificate is included in the server’s truststore. If the client is using a browser to connect to the JBoss EAP instance, you need to import that certificate or keystore into the browser’s certificate manager.
More details on using certificate-based authentication in applications, in addition to two-way SSL/TLS with applications, can be found in the Configuring a Security Domain to Use Certificate-based Authentication section of the JBoss EAP How to Configure Identity Management Guide.
2.5. SASL Authentication Mechanisms
Simple Authentication and Security Layer (SASL) authentication mechanisms are used for defining the mechanisms for authenticating connections to a JBoss EAP server using the elytron
subsystem, and for clients connecting to servers. Clients can be other JBoss EAP instances, or Elytron Client. SASL authentication mechanisms in JBoss EAP are also significantly used in Elytron integration with the remoting
subsystem.
2.5.1. Choosing SASL Authentication Mechanisms
Although JBoss EAP and Elytron Client work with a variety of SASL authentication mechanisms, you must ensure that the mechanisms you use are supported. See this list for the support levels for SASL authentication mechanisms.
The authentication mechanisms you use depends on your environment and desired authentication method. The following list summarizes the use of some of the supported SASL authentication mechanisms:
ANONYMOUS
- Unauthenticated guest access.
DIGEST-MD5
- Uses HTTP digest authentication as a SASL mechanism.
EXTERNAL
- Uses authentication credentials that are implied in the context of the request. For example, IPsec or TLS authentication.
- Mechanisms beginning with
GS
- Authentication using Kerberos.
JBOSS-LOCAL-USER
- Provides authentication by testing that the client has the same file access as the local user that is running the JBoss EAP server. This is useful for other JBoss EAP instances running on the same machine.
OAUTHBEARER
- Uses authentication provided by OAuth as a SASL mechanism.
PLAIN
- Plain text username and password authentication.
- Mechanisms beginning with
SCRAM
- Salted Challenge Response Authentication Mechanism (SCRAM) that uses a specified hashing function.
- Mechanisms ending with
-PLUS
- Indicates a channel binding variant of a particular authentication mechanism. You should use these variants when the underlying connection uses SSL/TLS.
For more information on individual SASL authentication mechanisms, see the IANA SASL mechanism list and individual mechanism memos.
2.5.2. Configuring SASL Authentication Mechanisms on the Server Side
Configuring SASL authentication mechanisms on the server side is done using SASL authentication factories.
There are two levels of configuration required:
-
A
sasl-authentication-factory
, where you specify authentication mechanisms. -
A
configurable-sasl-server-factory
that aggregates one or more ofsasl-authentication-factory
, and configures mechanism properties as well as optionally applying filters to enable or disable certain authentication mechanisms.
The following example demonstrates creating a new configurable-sasl-server-factory
, and a sasl-authentication-factory
that uses DIGEST-MD5 as a SASL authentication mechanism for application clients.
/subsystem=elytron/configurable-sasl-server-factory=mySASLServerFactory:add(sasl-server-factory=elytron) /subsystem=elytron/sasl-authentication-factory=mySASLAuthFactory:add(sasl-server-factory=mySASLServerFactory,security-domain=ApplicationDomain,mechanism-configurations=[{mechanism-name=DIGEST-MD5,mechanism-realm-configurations=[{realm-name=ApplicationRealm}]}])
2.5.3. Specifying SASL Authentication Mechanisms on the Client Side
SASL authentication mechanisms used by a client are specified using a sasl-mechanism-selector
. You can specify any supported SASL authentication mechanisms that are exposed by the server that the client is connecting to.
A sasl-mechanism-selector
is defined in Elytron configurations where authentication is configured:
In the
elytron
subsystem, this is an attribute of anauthentication-configuration
. For example:/subsystem=elytron/authentication-configuration=myAuthConfig:write-attribute(name=sasl-mechanism-selector,value="DIGEST-MD5")
An example of using an
authentication-configuration
with asasl-mechanism-selector
can be seen in Configuring SSL/TLS Between Domain and Host Controllers Using Elytron.For Elytron Client, it is specified under the
configuration
element ofauthentication-configurations
in the client configuration file, usually namedwildfly-config.xml
. For example:<configuration> <authentication-client xmlns="urn:elytron:1.0.1"> <authentication-rules> <rule use-configuration="default" /> </authentication-rules> <authentication-configurations> <configuration name="default"> <sasl-mechanism-selector selector="#ALL" /> ... </configuration> </authentication-configurations> </authentication-client> </configuration>
See How to Configure Identity Management for more information on configuring client authentication with Elytron Client.
sasl-mechanism-selector
Grammar
The selector string for sasl-mechanism-selector
has a specific grammar.
In a simple form, individual mechanisms are specified by listing their names in order, separated by a spaces. For example, to specify DIGEST-MD5, SCRAM-SHA-1, and SCRAM-SHA-256 as allowed authentication mechanisms, use the following string: DIGEST-MD5 SCRAM-SHA-1 SCRAM-SHA-256
.
More advanced usage of the grammar can use the following special tokens:
-
#ALL
: All mechanisms. -
#FAMILY(NAME)
: Mechanisms belonging to the specified mechanism family. For example, the family could be DIGEST, EAP, GS2, SCRAM, or IEC-ISO-9798. -
#PLUS
: Mechanisms that use channel binding. For example, SCRAM-SHA-XXX-PLUS or GS2-XXX-PLUS. -
#MUTUAL
: Mechanisms that authenticate the server in some way, for example making the server prove that the server knows the password.#MUTUAL
includes families such as#FAMILY(SCRAM)
and#FAMILY(GS2)
. -
#HASH(ALGORITHM)
: Mechanisms that use the specified hash algorithm. For example, the algorithm could be MD5, SHA-1, SHA-256, SHA-384, or SHA-512.
The above tokens and names can also be used with the following operations and predicates:
-
-
: Forbids -
!
: Inverts -
&&
: And -
||
: Or -
==
: Equals -
?
: If -
#TLS
: Is true when TLS is active, otherwise false.
Below are some examples of sasl-mechanism-selector
strings and their meaning:
-
#TLS && !#MUTUAL
: When TLS is active, all mechanisms without mutual authentication. -
#ALL -ANONYMOUS
: All mechanisms, except for ANONYMOUS. -
SCRAM-SHA-1 SCRAM-SHA-256
: Adds those two mechanisms in that order. -
(SCRAM-SHA-1 || SCRAM-SHA-256)
: Adds the two mechanisms in the order that the provider or server presents them. -
!#HASH(MD5)
: Any mechanism that does not use the MD5 hashing algorithm. -
#FAMILY(DIGEST)
: Any digest mechanism.
2.5.4. Configuring SASL Authentication Mechanism Properties
You can configure authentication mechanism properties on both the server side and on the client side.
On the server side, you define authentication mechanism properties in the
configurable-sasl-server-factory
. The following example defines thecom.sun.security.sasl.digest.utf8
property with a value offalse
./subsystem=elytron/configurable-sasl-server-factory=mySASLServerFactory:map-put(name=properties,key=com.sun.security.sasl.digest.utf8,value=false)
On the client side, you define authentication mechanisms properties in the client’s authentication configuration:
In the
elytron
subsystem, define the authentication mechanism properties in yourauthentication-configuration
. The following example defines thewildfly.sasl.local-user.quiet-auth
property with a value oftrue
./subsystem=elytron/authentication-configuration=myAuthConfig:map-put(name=mechanism-properties,key=wildfly.sasl.local-user.quiet-auth,value=true)
For Elytron Client, authentication mechanism properties are specified under the
configuration
element ofauthentication-configurations
in the client configuration file, usually namedwildfly-config.xml
. For example:... <authentication-configurations> <configuration name="default"> <sasl-mechanism-selector selector="#ALL" /> <set-mechanism-properties> <property key="wildfly.sasl.local-user.quiet-auth" value="true" /> </set-mechanism-properties> ... </configuration> </authentication-configurations> ...
You can see a list of standard Java SASL authentication mechanism properties in the Java documentation. Other JBoss EAP-specific SASL authentication mechanism properties are listed in the Authentication Mechanisms Reference.
2.6. Elytron Integration with the ModCluster Subsystem
One of the security capabilities exposed by elytron
subsystem is a client ssl-context
that can be used to configure the modcluster
subsystem to communicate with a load balancer using SSL/TLS.
When protecting the communication between the application server and the load balancer, you need to define a client ssl-context
in order to:
- Define a truststore holding the certificate chain that will be used to validate load balancer’s certificate.
- Define a trust manager to perform validations against the load balancer’s certificate.
2.6.1. Defining a Client SSL Context and Configuring ModCluster Subsystem
The following procedure requires that a truststore and trust manager be configured. For information on creating these see Create an Elytron Truststore and Create an Elytron Trust Manager.
Create the client SSL context.
This SSL context is going to be used by the
modcluster
subsystem when connecting to the load balancer using SSL/TLS:/subsystem=elytron/client-ssl-context=modcluster-client-ssl-context:add(trust-manager=default-trust-manager)
Reference the newly created client SSL context using one of the following options.
Configure the
modcluster
subsystem by setting thessl-context
./subsystem=modcluster/mod-cluster-config=configuration:write-attribute(name=ssl-context, value=modcluster-client-ssl-context)
Configure the
undertow
subsystem by defining thessl-context
attribute of themod-cluster
filter./subsystem=undertow/configuration=filter/mod-cluster=modcluster:write-attribute(name=ssl-context,value=modcluster-client-ssl-context)
Reload the server.
reload
For configuring the modcluster
subsystem and using two-way authentication, along with the trust manager, the key manager also needs to be configured.
Create the keystore.
/subsystem=elytron/key-store=twoWayKS:add(path=/path/to/client.keystore.jks, credential-reference={clear-text=secret},type=JKS)
Configure the key manager.
/subsystem=elytron/key-manager=twoWayKM:add(key-store=twoWayKS, algorithm="SunX509", credential-reference={clear-text=secret})
Create the client SSL context.
/subsystem=elytron/client-ssl-context=modcluster-client-ssl-context:add(trust-manager=default-trust-manager, key-manager=twoWayKM)
NoteIf you already have an existing client SSL context, you can add the
key-manager
to it as follows:/subsystem=elytron/client-ssl-context=modcluster-client-ssl-context:write-attribute(name=key-manager, value=twoWayKM)
Reload the server.
reload
2.7. Elytron Integration with the JGroups Subsystem
Components in the elytron
subsystem may be referenced when defining authorization or encryption protocols in the jgroups
subsystem. Full instructions on configuring these protocols are found in the Securing a Cluster section of the Configuration Guide.
2.8. Elytron Integration with the Remoting Subsystem
2.8.1. Elytron Integration with Remoting Connectors
A remoting connector is specified by a SASL authentication factory, a socket binding, and an optional SSL context. In particular, the attributes for a connector are as follows:
sasl-authentication-factory
- A reference to the SASL authentication factory to use for authenticating requests to this connector. For more information on creating this factory, see Create an Elytron Authentication Factory.
socket-binding
- A reference to the socket binding, detailing the interface and port where the connector should listen for incoming requests.
ssl-context
- An optional reference to the server-side SSL Context to use for this connector. The SSL Context contains the server key manager and trust manager to be used, and should be defined in instances where SSL is desired.
For example, a connector can be added as follows, where SASL_FACTORY_NAME
is an already defined authentication factory and SOCKET_BINDING_NAME
is an existing socket binding.
/subsystem=remoting/connector=CONNECTOR_NAME:add(sasl-authentication-factory=SASL_FACTORY_NAME,socket-binding=SOCKET_BINDING_NAME)
If SSL is desired, a preconfigured server-ssl-context
may be referenced using the ssl-context
attribute, as seen below.
/subsystem=remoting/connector=CONNECTOR_NAME:add(sasl-authentication-factory=SASL_FACTORY_NAME,socket-binding=SOCKET_BINDING_NAME,ssl-context=SSL_CONTEXT_NAME)
Enable One-way SSL/TLS for Remoting Connectors Using the Elytron Subsystem
Before enabling one-way SSL/TLS in JBoss EAP, you must configure a key-store
, key-manager
, and a server-ssl-context
that references the defined key-manager
.
The following SASL mechanisms support channel binding to external secure channels, such as SSL/TLS:
- GS2-KRB5-PLUS
- SCRAM-SHA-1-PLUS
- SCRAM-SHA-256-PLUS
- SCRAM-SHA-384-PLUS
- SCRAM-SHA-512-PLUS
To use any of the above mechanisms, a custom SASL factory can be configured, or one of the predefined SASL authentication factories can be modified to offer any of these mechanisms. A SASL mechanism selector can be used on the client to specify the appropriate SASL mechanism.
Create a
socket-binding
for the connector. The following command defines theoneWayBinding
binding that listens on port11199
./socket-binding-group=standard-sockets/socket-binding=oneWayBinding:add(port=11199)
Create a connector that references the SASL authentication factory, the previously created socket binding, and the SSL context.
/subsystem=remoting/connector=oneWayConnector:add(sasl-authentication-factory=SASL_FACTORY,socket-binding=oneWayBinding,ssl-context=SSL_CONTEXT)
ImportantIn cases where you have both a
security-realm
andssl-context
defined, JBoss EAP will use the SSL/TLS configuration provided byssl-context
.-
Configure the client to trust the server certificate. A generic example client is found at Elytron Client Side One Way Example. This example configures an
ssl-context
using the clienttrust-store
.
Enable Two-way SSL/TLS for Remoting Connectors Using the Elytron Subsystem
Before enabling two-way SSL/TLS in JBoss EAP, you must configure a separate key-store
components for the client and server certificates, a key-manager
for the server key-store
, a trust-manager
for the server trust-store
, and a server-ssl-context
that references the defined key-manager
and trust-manager
.
The following SASL mechanisms support channel binding to external secure channels, such as SSL/TLS:
- GS2-KRB5-PLUS
- SCRAM-SHA-1-PLUS
- SCRAM-SHA-256-PLUS
- SCRAM-SHA-384-PLUS
- SCRAM-SHA-512-PLUS
To use any of the above mechanisms, a custom SASL factory can be configured, or one of the predefined SASL authentication factories can be modified to offer any of these mechanisms. A SASL mechanism selector can be used on the client to specify the appropriate SASL mechanism.
Create a
socket-binding
for the connector. The following command defines thetwoWayBinding
binding that listens on port11199
./socket-binding-group=standard-sockets/socket-binding=twoWayBinding:add(port=11199)
Create a connector that references the SASL authentication factory, the previously created socket binding, and the SSL context.
/subsystem=remoting/connector=twoWayConnector:add(sasl-authentication-factory=SASL_FACTORY,socket-binding=twoWayBinding,ssl-context=SSL_CONTEXT)
ImportantIn cases where you have both a
security-realm
andssl-context
defined, JBoss EAP will use the SSL/TLS configuration provided byssl-context
.Configure your client to trust the server certificate, and to present its certificate to the server.
You need to configure your client to present the trusted client certificate to the server to complete the two-way SSL/TLS authentication. For example, if using a browser, you need to import the trusted certificate into the browser’s truststore. A generic example client is found at Elytron Client Side Two Way Example. This example configures an
ssl-context
using the clienttrust-store
andkey-store
.
Two-way SSL/TLS is now enabled on the remoting connector.
2.8.2. Elytron Integration with Remoting HTTP Connectors
A remote HTTP connection is specified by referencing a connector in the undertow
system and a SASL authentication factory defined in the elytron
subsystem. The HTTP connector provides the configuration for the HTTP upgrade-based remoting connector, and connects to an HTTP listener specified by the connector-ref
attribute.
The attributes for a connector
are as follows:
connector-ref
-
A reference to a predefined
undertow
listener. sasl-authentication-factory
- A reference to the SASL authentication factory to use for authenticating requests to this connector. For more information on creating this factory, see Create an Elytron Authentication Factory.
For example, a http-connector
can be added as follows, where CONNECTOR_NAME
references the undertow
listener, and SASL_FACTORY_NAME
is an already defined authentication factory in the elytron
subsystem.
/subsystem=remoting/http-connector=HTTP_CONNECTOR_NAME:add(connector-ref=CONNECTOR_NAME,sasl-authentication-factory=SASL_FACTORY_NAME)
Enable One-Way SSL on the Remoting HTTP Connector
Before enabling one-way SSL/TLS in JBoss EAP, you must configure a key-store
, key-manager
, and a server-ssl-context
that references the defined key-manager
.
The following SASL mechanisms support channel binding to external secure channels, such as SSL/TLS:
- GS2-KRB5-PLUS
- SCRAM-SHA-1-PLUS
- SCRAM-SHA-256-PLUS
- SCRAM-SHA-384-PLUS
- SCRAM-SHA-512-PLUS
To use any of the above mechanisms, a custom SASL factory can be configured, or one of the predefined SASL authentication factories can be modified to offer any of these mechanisms. A SASL mechanism selector can be used on the client to specify the appropriate SASL mechanism.
Check whether the
https-listener
is configured to use a legacy security realm for its SSL configuration./subsystem=undertow/server=default-server/https-listener=https:read-attribute(name=security-realm) { "outcome" => "success", "result" => "ApplicationRealm" }
The above command shows that the
https-listener
is configured to use theApplicationRealm
legacy security realm for its SSL configuration. Undertow cannot reference both a legacy security realm and anssl-context
in Elytron at the same time so you must remove the reference to the legacy security realm.NoteIf the result is
undefined
, you do not need to remove the reference to the security realm in the next step.Remove the reference to the legacy security realm, and update the
https-listener
to use thessl-context
from Elytron.Notehttps-listener
must always have either asecurity-realm
orssl-context
configured. When changing between the two configurations, the commands must be executed as a single batch, as shown below.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=SERVER_SSL_CONTEXT) run-batch
Create an HTTP connector that references the HTTPS listener and the SASL authentication factory.
/subsystem=remoting/http-connector=ssl-http-connector:add(connector-ref=https,sasl-authentication-factory=SASL_FACTORY)
Reload the server.
reload
- Configure the client to trust the server certificate. For example, if using a browser, you need to import the trusted certificate into the browser’s truststore.
Enable Two-way SSL/TLS on the Remoting HTTP Connectors
Before enabling two-way SSL/TLS in JBoss EAP, you must configure separate key-store
components for the client and server certificates, a key-manager
for the server key-store
, a trust-manager
for the server trust-store
, and a server-ssl-context
that references the defined key-manager
and trust-manager
.
The following SASL mechanisms support channel binding to external secure channels, such as SSL/TLS:
- GS2-KRB5-PLUS
- SCRAM-SHA-1-PLUS
- SCRAM-SHA-256-PLUS
- SCRAM-SHA-384-PLUS
- SCRAM-SHA-512-PLUS
To use any of the above mechanisms, a custom SASL factory can be configured, or one of the predefined SASL authentication factories can be modified to offer any of these mechanisms. A SASL mechanism selector can be used on the client to specify the appropriate SASL mechanism.
Check whether the
https-listener
is configured to use a legacy security realm for its SSL configuration./subsystem=undertow/server=default-server/https-listener=https:read-attribute(name=security-realm) { "outcome" => "success", "result" => "ApplicationRealm" }
The above command shows that the
https-listener
is configured to use theApplicationRealm
legacy security realm for its SSL configuration. Undertow cannot reference both a legacy security realm and anssl-context
in Elytron at the same time so you must remove the reference to the legacy security realm.NoteIf the result is
undefined
, you do not need to remove the reference to the security realm in the next step.Remove the reference to the legacy security realm, and update the
https-listener
to use thessl-context
from Elytron.Notehttps-listener
must always have either asecurity-realm
orssl-context
configured. When changing between the two configurations, the commands must be executed as a single batch, as shown below.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=SERVER_SSL_CONTEXT) run-batch
Create an HTTP connector that references the HTTPS listener and the SASL authentication factory.
/subsystem=remoting/http-connector=ssl-http-connector:add(connector-ref=https,sasl-authentication-factory=SASL_FACTORY)
Reload the server.
reload
Configure your client to trust the server certificate, and to present its certificate to the server.
You need to configure your client to present the trusted client certificate to the server to complete the two-way SSL/TLS authentication. For example, if using a browser, you need to import the trusted certificate into the browser’s truststore.
Two-way SSL/TLS is now enabled on the remoting HTTP connector.
In cases where you have both a security-realm
and ssl-context
defined, JBoss EAP will use the SSL/TLS configuration provided by ssl-context
.
2.8.3. Elytron Integration with Remoting Outbound Connectors
A remote outbound connection is specified by an outbound socket binding and an authentication context. The authentication context provides all of the security information that is needed for the connection. In particular, the attributes for a remote-outbound-connection
are as follows:
-
outbound-socket-binding-ref
- The name of the outbound socket binding, which is used to determine the destination address and port for the connection. -
authentication-context
- A reference to the authentication context, which contains the authentication configuration and the defined SSL context, if one exists, required for the connection. For information on defining an authentication context, see Creating an Authentication Context.
For example, a remote-outbound-connection
can be added as follows, where OUTBOUND_SOCKET_BINDING_NAME is an already defined outbound-socket-binding
and AUTHENTICATION_CONTEXT_NAME is an authentication-context
that has already been defined in the elytron
subsystem configuration.
/subsystem=remoting/remote-outbound-connection=OUTBOUND_CONNECTION_NAME:add(authentication-context=AUTHENTICATION_CONTEXT_NAME, outbound-socket-binding-ref=OUTBOUND_SOCKET_BINDING_NAME)
2.9. Securing a Managed Domain
In addition to securing the management interfaces, you can also secure communication between JBoss EAP instances in a managed domain.
For information on concepts and general configuration for the managed domain operating mode, see the Domain Management section of the JBoss EAP Configuration Guide.
2.9.1. Configure Password Authentication Between Slaves and the Domain Controller Using Elytron
Add a user on the master domain controller.
A user needs to be added on the master domain controller for the slave controller to use for authentication. If you are using the default file based user and group authentication mechanism, this can be done by running
EAP_HOME/bin/adduser.sh
. Add the username, password and other configurations when prompted.The
add-user
utility can be used to manage both the users in theManagementRealm
and the users in theApplicationRealm
.NoteThe server caches the contents of the properties files in memory. However, the server does check the modified time of the properties files on each authentication request and reloads if the time has been updated. This means that all changes made by the
add-user
utility are immediately applied to any running server.The slave controller attemps to authenticate using the native interface. If the native interface has been secured with the
ManagementRealm
Elytron security realm, then you would need to add a user toManagementRealm
for the slave controller to use.NoteThe default name of the realm for management users is
ManagementRealm
. When theadd-user
utility prompts for the realm name, just accept the default unless you have switched to a different realm.The following example assumes the user
slave
with the passwordpassword1!
has been added toManagementRealm
.Add an
authentication-configuration
to the slave controller./host=slave/subsystem=elytron/authentication-configuration=slave:add(authentication-name=slave, credential-reference={clear-text=password1!})
Add an
authentication-context
to the slave controller./host=slave/subsystem=elytron/authentication-context=slave-context:add(match-rules=[{authentication-configuration=slave}])
Specify the domain controller location and
authentication-context
in the slave controller.<domain-controller> <remote protocol="remote" host="localhost" port="9999" authentication-context="slave-context"/> </domain-controller>
2.9.2. Configure Password Authentication Between Slaves and the Domain Controller Using Legacy Core Management Authentication
When configuring a managed domain, by default, the master domain controller is configured to require authentication for each slave controller that connects to it. To configure slave controllers with the proper credentials, you must do the following:
Add a user to the master domain controller
You need to add a user to the master domain controller using the
add-user
script. Specifically, you will need to ensure that the user is added to the same realm the master uses to secure its management interface, which by default isManagementRealm
. You also need to ensure you answeryes
to the Is this new user going to be used for one AS process to connect to another AS process? question.ImportantAfter adding the user, the script will output a <secret> element, which will be used in the next step. You must keep this value for use in the next step.
Example: Adding a Slave User
$ EAP_HOME/bin/add-user.sh What type of user do you wish to add? a) Management User (mgmt-users.properties) b) Application User (application-users.properties) (a): a Enter the details of the new user to add. Using realm 'ManagementRealm' as discovered from the existing property files. Username : slave-user Password recommendations are listed below. To modify these restrictions edit the add-user.properties configuration file. - The password should be different from the username - The password should not be one of the following restricted values {root, admin, administrator} - The password should contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), 1 non-alphanumeric symbol(s) Password : Re-enter Password : What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[ ]: About to add user 'slave-user' for realm 'ManagementRealm' Is this correct yes/no? yes Added user 'slave-user' to file '/home/user/EAP-7.1.0/standalone/configuration/mgmt-users.properties' Added user 'slave-user' to file '/home/user/EAP-7.1.0/domain/configuration/mgmt-users.properties' Added user 'slave-user' with groups to file '/home/user/EAP-7.1.0/standalone/configuration/mgmt-groups.properties' Added user 'slave-user' with groups to file '/home/user/EAP-7.1.0/domain/configuration/mgmt-groups.properties' Is this new user going to be used for one AS process to connect to another AS process? e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls. yes/no? yes To represent the user add the following to the server-identities definition <secret value="ABCzc3dv11Qx" />
Configure the slave controllers to use the credential.
Once you have created the user on the master domain controller, you will need to update each slave controller to use that credential in the host configuration file, for example
host.xml
orhost-slave.xml
. To do so, you need to add the user name to the<remote>
element in the domain controller configuration. You will also need to add the <secret> to theserver identities
of the realm used to secure the<remote>
element. Both the user name and <secret> were obtained when adding the user to the master domain controller in the previous step.Example: Configuring Slave Controllers
... <security-realm name="ManagementRealm"> <server-identities> <!-- Replace this with either a base64 password of your own, or use a vault with a vault expression --> <secret value="ABCzc3dv11Qx"/> </server-identities> ... <domain-controller> <remote security-realm="ManagementRealm" username="slave-user"> <discovery-options> <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote}" host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}"/> </discovery-options> </remote> </domain-controller>
2.9.3. Configuring SSL/TLS Between Domain and Host Controllers Using Elytron
When you configure SSL/TLS to be used between JBoss EAP instances in a managed domain, each instance can have a client or server role depending on the interaction. This includes all host controllers as well as domain controllers. As a result, it is recommended that you set up two-way SSL/TLS between endpoints.
You can configure JBoss EAP instances in a managed domain to use SSL/TLS when communicating with each other, in other words, between the master domain controller and host controllers. To do so using Elytron, use the following procedure.
Generate and configure all necessary certificates and keystores.
In order to set up two-way SSL/TLS between endpoints, you need to generate and configure certificates and keystores for the master domain controller as well as each host controller. You also need to import the certificate of the master domain controller into each host controller’s keystore as well as import each host controller’s certificate into the master domain controller’s keystore. The specifics of this process is covered in Enable Two-way SSL/TLS for the Management Interfaces Using the Elytron Subsystem.
Add a user on the master domain controller.
A user needs to be added on the master domain controller for the slave controller to use for authentication. If you are using the default file based user and group authentication mechanism, this can be done by running
EAP_HOME/bin/adduser.sh
. Add the username, password and other configurations when prompted.The
add-user
utility can be used to manage both the users in theManagementRealm
and the users in theApplicationRealm
.NoteThe server caches the contents of the properties files in memory. However, the server does check the modified time of the properties files on each authentication request and reloads if the time has been updated. This means that all changes made by the
add-user
utility are immediately applied to any running server.The slave controller attemps to authenticate using the native interface. If the native interface has been secured with the
ManagementRealm
Elytron security realm, then you would need to add a user toManagementRealm
for the slave controller to use.NoteThe default name of the realm for management users is
ManagementRealm
. When theadd-user
utility prompts for the realm name, just accept the default unless you have switched to a different realm.The following example assumes the user
slave
with the passwordpassword1!
has been added toManagementRealm
.Configure the master domain controller to use SSL/TLS.
The commands below configure the domain controller’s
key-store
,key-manager
,trust-manager
, andserver-ssl-context
for the server keystore and truststore./host=master/subsystem=elytron/key-store=twoWayKS:add(path=/path/to/server.keystore.jks,credential-reference={clear-text=secret},type=JKS) /host=master/subsystem=elytron/key-store=twoWayTS:add(path=/path/to/server.truststore.jks,credential-reference={clear-text=secret},type=JKS) /host=master/subsystem=elytron/key-manager=twoWayKM:add(key-store=twoWayKS,algorithm="SunX509",credential-reference={clear-text=secret}) /host=master/subsystem=elytron/trust-manager=twoWayTM:add(key-store=twoWayTS,algorithm="SunX509") /host=master/subsystem=elytron/server-ssl-context=twoWaySSC:add(key-manager=twoWayKM,protocols=["TLSv1.2"],trust-manager=twoWayTM,want-client-auth=true,need-client-auth=true) /host=master/core-service=management/management-interface=native-interface:write-attribute(name=ssl-context, value=twoWaySSC)
ImportantYou need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the
PKIX
andSunX509
algorithms. You also need to determine what HTTPS protocols you want to support. The example commands above useTLSv1.2
. You can use thecipher-suite-filter
argument to specify which cipher suites are allowed, and theuse-cipher-suites-order
argument to honor server cipher suite order. Theuse-cipher-suites-order
attribute by default is set totrue
. This differs from the legacysecurity
subsystem behavior, which defaults to honoring client cipher suite order.Configure an authentication context and domain controller location on each slave host controller.
The following example configuration assumes the domain controller exists on
localhost
. Ensure you specify the correct management user, password, and domain controller location for your environment./host=slave1/subsystem=elytron/authentication-context=slaveHostSSLContext:add() /host=slave1/subsystem=elytron/authentication-configuration=slaveHostSSLConfiguration:add() /host=slave1/subsystem=elytron/authentication-configuration=slaveHostSSLConfiguration:write-attribute(name=sasl-mechanism-selector,value=DIGEST-MD5) /host=slave1/subsystem=elytron/authentication-configuration=slaveHostSSLConfiguration:write-attribute(name=authentication-name,value=slave) /host=slave1/subsystem=elytron/authentication-configuration=slaveHostSSLConfiguration:write-attribute(name=realm,value=ManagementRealm) /host=slave1/subsystem=elytron/authentication-configuration=slaveHostSSLConfiguration:write-attribute(name=credential-reference,value={clear-text=password1!}) /host=slave1/subsystem=elytron/authentication-context=slaveHostSSLContext:write-attribute(name=match-rules,value=[{match-host=localhost,authentication-configuration=slaveHostSSLConfiguration}] /host=slave1:write-remote-domain-controller(host=localhost,port=9999,protocol=remote,authentication-context=slaveHostSSLContext)
Configure each slave host controller to use SSL/TLS.
The commands below configure a slave host controller’s
key-store
,key-manager
,trust-manager
,client-ssl-context
for the server keystore and truststore, as well as theauthentication-context
.The following example configuration assumes the domain controller exists on
localhost
. Ensure you specify the correct domain controller location for your environment./host=slave1/subsystem=elytron/key-store=twoWayKS:add(path=/path/to/client.keystore.jks,credential-reference={clear-text=secret},type=JKS) /host=slave1/subsystem=elytron/key-store=twoWayTS:add(path=/path/to/client.truststore.jks,credential-reference={clear-text=secret},type=JKS) /host=slave1/subsystem=elytron/key-manager=twoWayKM:add(key-store=twoWayKS,algorithm="SunX509",credential-reference={clear-text=secret}) /host=slave1/subsystem=elytron/trust-manager=twoWayTM:add(key-store=twoWayTS,algorithm="SunX509") /host=slave1/subsystem=elytron/client-ssl-context=twoWayCSC:add(key-manager=twoWayKM,protocols=["TLSv1.2"],trust-manager=twoWayTM) /host=slave1/subsystem=elytron/authentication-context=slaveHostSSLContext:write-attribute(name=match-rules,value=[{match-host=localhost,authentication-configuration=slaveHostSSLConfiguration,ssl-context=twoWayCSC}])
- Reload all the JBoss EAP hosts in your managed domain.
2.9.4. Configuring SSL/TLS Between Domain and Host Controllers Using Legacy Core Management Authentication
When you configure SSL/TLS to be used between JBoss EAP instances in a managed domain, each instance can have a client or server role depending on the interaction. This includes all host controllers as well as domain controllers. As a result, it is recommended that you set up two-way SSL/TLS between endpoints.
You can configure JBoss EAP instances in a managed domain to use SSL/TLS when communicating with each other, in other words, between the master domain controller and host controllers. To do so using legacy core management authentication, use the following procedure.
Generate and configure all necessary certificates and keystores.
In order to set up two-way SSL/TLS between endpoints, you need to generate and configure certificates and keystores for the master domain controller as well as each host controller. You also need to import the certificate of the master domain controller into each host controller’s keystore as well as import each host controller’s certificate into the master domain controller’s keystore. The specifics of this process is covered in Setting up Two-way SSL/TLS for the Management Interfaces with Legacy Core Management Authentication.
Configure the master domain controller to use SSL/TLS.
Once you have configured all certificates and keystores, you need to configure a security realm to use two-way SSL/TLS. This is done by configuring a security realm to use SSL/TLS and to require it for authentication. That security realm is then used to secure the management interface used for connecting between host controllers and the master domain controller.
NoteThe following commands below must either be run in batch mode, or the server must be reloaded after adding the ssl server identity. The example below is shown using batch mode.
batch /host=master/core-service=management/security-realm=CertificateRealm:add() /host=master/core-service=management/security-realm=CertificateRealm/server-identity=ssl:add(alias=domaincontroller,keystore-relative-to=jboss.domain.config.dir,keystore-path=domaincontroller.jks,keystore-password=secret) /host=master/core-service=management/security-realm=CertificateRealm/authentication=truststore:add(keystore-relative-to=jboss.domain.config.dir,keystore-path=domaincontroller.jks,keystore-password=secret) /host=master/core-service=management/security-realm=CertificateRealm/authentication=local:add(default-user=\$local) /host=master/core-service=management/security-realm=CertificateRealm/authentication=properties:add(relative-to=jboss.domain.config.dir,path=mgmt-users.properties) /host=master/core-service=management/management-interface=native-interface:write-attribute(name=security-realm,value=CertificateRealm) run-batch
Configure all host controllers to use SSL/TLS.
Once you have the master domain controller configured to use two-way SSL/TLS, you need to configure each host controller to use it as well. The process is very much the same as the master domain controller configuration, except you will need to use the keystore specific to each host.
NoteThe following commands below must either be run in batch mode, or the server must be reloaded after adding the ssl server identity. The example below is shown using batch mode.
batch /host=instance1/core-service=management/security-realm=CertificateRealm:add() /host=instance1/core-service=management/security-realm=CertificateRealm/server-identity=ssl:add(alias=instance1,keystore-relative-to=jboss.domain.config.dir,keystore-path=instance1.jks,keystore-password=secret) /host=instance1/core-service=management/security-realm=CertificateRealm/authentication=truststore:add(keystore-relative-to=jboss.domain.config.dir,keystore-path=instance1.jks,keystore-password=secret) /host=instance1/core-service=management/security-realm=CertificateRealm/authentication=local:add(default-user="\$local") /host=instance1/core-service=management/security-realm=CertificateRealm/authentication=properties:add(relative-to=jboss.domain.config.dir,path=mgmt-users.properties) /host=instance1/core-service=management/management-interface=native-interface:write-attribute(name=security-realm,value=CertificateRealm) run-batch
Additionally, you will need to update the security realm used when connecting the master domain controller. This change must be done directly in the host controller’s configuration file, for example
host.xml
orhost-slave.xml
, while the server is not running.Example: Host Controller Configuration File
<domain-controller> <remote security-realm="CertificateRealm" username="slave-user"> <discovery-options> <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote}" host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}"/> </discovery-options> </remote> </domain-controller>
WarningRed Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages.
2.10. Additional Elytron Components for SSL/TLS
The basic concepts behind configuring one-way SSL/TLS and two-way SSL/TLS are covered in the following:
Elytron also offers some additional components for configuring SSL/TLS.
2.10.1. Using an ldap-key-store
An ldap-key-store
allows you to use a keystore stored in an LDAP server. You can use an ldap-key-store
in the same way as you use a key-store
.
It is not possible to use a JMX ObjectName to decrypt the LDAP credentials. Instead, credentials can be secured by using a credential store.
To create and use an ldap-key-store
:
Configure a
dir-context
.To connect to the LDAP server from JBoss EAP, you need to configure a
dir-context
that provides the URL as well as the principal used to connect to the server.Example: dir-context
/subsystem=elytron/dir-context=exampleDC:add(url="ldap://127.0.0.1:10389", principal="uid=admin,ou=system", credential-reference={clear-text="secret"})
Configure an
ldap-key-store
.When you configure an
ldap-key-store
, you need to specify both thedir-context
used to connect to the LDAP server as well as how to locate the keystore stored in the LDAP server. At a minimum, this requires you to specify asearch-path
.Example: ldap-key-store
/subsystem=elytron/ldap-key-store=ldapKS:add(dir-context=exampleDC, search-path="ou=Keystores,dc=wildfly,dc=org")
Use the
ldap-key-store
.Once you have defined your
ldap-key-store
, you can use it in the same places where akey-store
could be used. For example, you could use anldap-key-store
when configuring One-way SSL/TLS and Two-way SSL/TLS for applications.
For the full list of attributes for ldap-key-store
as well as other Elytron components, see Elytron Subsystem Components Reference.
2.10.2. Using a filtering-key-store
A filtering-key-store
allows you to expose a subset of aliases from an existing key-store
, and use it in the same places you could use a key-store
. For example, if a keystore contained alias1
, alias2
, and alias3
, but you only wanted to expose alias1
and alias3
, a filtering-key-store
provides you several ways to do that.
To create a filtering-key-store
:
Configure a
key-store
./subsystem=elytron/key-store=myKS:add(path=keystore.jks, relative-to=jboss.server.config.dir, credential-reference={clear-text=secret}, type=JKS)
Configure a
filtering-key-store
.When you configure a
filtering-key-store
, you specify whichkey-store
you want to filter and thealias-filter
for filtering aliases from thekey-store
. The filter can be specified in one of the following formats:-
alias1,alias3
, which is a comma-delimited list of aliases to expose. -
ALL:-alias2
, which exposes all aliases in the keystore except the ones listed. NONE:+alias1:+alias3
, which exposes no aliases in the keystore except the ones listed.This example uses a comma-delimted list to expose
alias1
andalias3
./subsystem=elytron/filtering-key-store=filterKS:add(key-store=myKS, alias-filter="alias1,alias3")
NoteThe
alias-filter
attribute is case sensitive. Because the use of mixed-case or uppercase aliases, such aselytronAppServer
, might not be recognized by some keystore providers, it is recommended to use lowercase aliases, such aselytronappserver
.
-
Use the
filtering-key-store
.Once you have defined your
filtering-key-store
, you can use it in the same places where akey-store
could be used. For example, you could use afiltering-key-store
when configuring One-way SSL/TLS and Two-way SSL/TLS for applications.
For the full list of attributes for filtering-key-store
as well as other Elytron components, see Elytron Subsystem Components Reference.
2.10.3. Reload a Keystore
You can reload a keystore configured in JBoss EAP from the management CLI. This is useful in cases where you have made changes to certificates referenced by a keystore.
To reload a keystore:
/subsystem=elytron/key-store=httpsKS:load
2.10.4. Keystore Alias
The alias
denotes the stored secret or credential in the store. If you add a keystore to the elytron
subsystem using the key-store
component, you can check the keystore’s contents using the alias
related key-store
operations.
The different operations for alias manipulation are:
-
read-alias
- Read an alias from a keystore. -
read-aliases
- Read aliases from a keystore. -
remove-alias
- Remove an alias from a keystore.
For example, to read an alias:
/subsystem=elytron/key-store=httpsKS/:read-alias(alias=localhost)
2.10.5. Using a client-ssl-context
A client-ssl-context
is used for providing an SSL context when the JBoss EAP instance creates an SSL connection as a client, such as using SSL in remoting.
To create a client-ssl-context
:
Create
key-store
,key-manager
, andtrust-manager
components as needed.If establishing a two-way SSL/TLS connection, you need to create separate
key-store
components for the client and server certificates, akey-manager
for the clientkey-store
, and atrust-manager
for the serverkey-store
. Alternatively, if you are doing a one-way SSL/TLS connection, you need to create akey-store
for the server certificate and atrust-manager
that references it. Examples on creating keystores and truststores are available in the Enable Two-way SSL/TLS for Applications using the Elytron Subsystem section.Create a
client-ssl-context
.Create a
client-ssl-context
referencing keystores, truststores, as well as any other necessary configuration options.Example: client-ssl-context
/subsystem=elytron/client-ssl-context=exampleCSC:add(key-manager=clientKM, trust-manager=clientTM, protocols=["TLSv1.2"])
-
Reference the
client-ssl-context
.
For the full list of attributes for client-ssl-context
as well as other Elytron components, see Elytron Subsystem Components Reference.
2.10.6. Using a server-ssl-context
A server-ssl-context
is used for providing a server-side SSL context. In addition to the usual configuration for an SSL context, it is possible to configure additional items such as cipher suites and protocols. The SSL context will wrap any additional items that are configured.
Create
key-store
,key-manager
, andtrust-manager
components as needed.If establishing a two-way SSL/TLS connection, you need to create separate
key-store
components for the client and server certificates, akey-manager
for the serverkey-store
, and atrust-manager
for the servertrust-store
. Alternatively, if you are doing a one-way SSL/TLS connection, you need to create akey-store
for the server certificate and akey-manager
that references it. Examples on creating keystores and truststores are available in the Enable Two-way SSL/TLS for Applications Using the Elytron Subsystem section.Create a
server-ssl-context
.Create a
server-ssl-context
that references the key manager, trust manager, or any other desired configuration options using one of the options outlined below.
Add a Server SSL Context Using the Management CLI
/subsystem=elytron/server-ssl-context=newServerSSLContext:add(key-manager=KEY_MANAGER,protocols=["TLSv1.2"])
You need to determine what HTTPS protocols will be supported. The example commands above use TLSv1.2
. You can use the cipher-suite-filter
argument to specify which cipher suites are allowed, and the use-cipher-suites-order
argument to honor server cipher suite order. The use-cipher-suites-order
attribute by default is set to true
. This differs from the legacy security
subsystem behavior, which defaults to honoring client cipher suite order.
Add a Server SSL Context Using the Management Console
- Access the management console. For more information, see the Management Console section in the JBoss EAP Configuration Guide.
-
Navigate to Configuration
Subsystems Security - Elytron Other. - Click on View. The Server SSL Context tab lets you do all the server SSL context related configurations.
For the full list of attributes for server-ssl-context
as well as other Elytron components, see Elytron Subsystem Components Reference.
2.10.7. Custom Components
When configuring SSL/TLS in the elytron
subsystem, you can provide and use custom implementations of the following components:
-
key-store
-
key-manager
-
trust-manager
-
client-ssl-context
-
server-ssl-context
It is not recommended to provide custom implementations of any component outside of the trust-manager
without an intimate knowledge of the Java Secure Socket Extension (JSSE).
When using FIPS it is not possible to utilize a custom trust manager or key manager, as FIPS requires these managers be embedded in the JDK for security reasons. Similar behavior can be accomplished by implementing a SecurityRealm
that validates X509 evidences.
When creating custom implementations of Elytron components, they must present the appropriate capabilities and requirements. For more details on capabilities and requirements, see the Capabilities and Requirements section of the JBoss EAP Security Architecture guide. Implementation details for each component are provided by the JDK vendor.
2.10.7.1. Add a Custom Component to Elytron
The following steps describe adding a custom component within Elytron.
Add the JAR containing the provider for the custom component as a module into JBoss EAP, declaring any required dependencies, such as
javax.api
:module add --name=MODULE_NAME --resources=FACTORY_JAR --dependencies=javax.api,DEPENDENCY_LIST
ImportantUsing the
module
management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment. For more information, see the Create a Custom Module Manually and Remove a Custom Module Manually sections of the JBoss EAP Configuration Guide.Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.
When the component is added to the
elytron
subsystem thejava.util.ServiceLoader
will be used to discover the provider. Alternatively, a reference to the provider can be provided by defining aprovider-loader
. There are two methods of creating the loader, and only one should be implemented for each component.Reference the provider directly when defining the
provider-loader
:/subsystem=elytron/provider-loader=LOADER_NAME:add(class-names=[CLASS_NAME],module=MODULE_NAME)
Include a reference to the provider in
META-INF/services/java.security.Provider
. This reference is automatically created when using the@MetaInfServices
annotation inorg.kohsuke.metainf-services
. When using this method only the module needs to be referenced by theprovider-loader
, as seen below:/subsystem=elytron/provider-loader=LOADER_NAME:add(module=MODULE_NAME)
Add the custom component into Elytron’s configuration, using the appropriate element for the type to be added and referencing any defined providers.
/subsystem=elytron/COMPONENT_NAME=NEW_COMPONENT:add(providers=LOADER_NAME,...)
For instance, to define a trust manager, the
trust-manager
element would be used, as seen in the following command:Example: Adding a Custom Trust Manager
/subsystem=elytron/trust-manager=newTrustManager:add(algorithm=MyX509,providers=customProvider,key-store=sampleKeystore)
- Once defined, the component can be referenced from other elements.
2.10.7.2. Using Custom Trust Managers with Elytron
By implementing a custom trust manager, it is possible to extend the validation of certificates when using HTTPS in Undertow, LDAPS in a dir-context
, or any place where Elytron is used for SSL connections. This component is responsible for making trust decisions for the server, and it is strongly recommended that these be implemented if a custom trust manager is used.
When using FIPS it is not possible to utilize a custom trust manager, as FIPS requires this manager be embedded in the JDK for security reasons. Similar behavior can be accomplished by implementing a SecurityRealm
that validates X509 evidences.
Requirements for Implementing a Custom Trust Manager
When using a custom trust manager, the following must be implemented:
-
A trust manager that implements the
X509ExtendedTrustManager
interface. -
A trust manager factory that extends
TrustManagerFactorySpi
. - The provider of the trust manager factory.
The provider must be included in the JAR file to be added into JBoss EAP. Any implemented classes must be included in JBoss EAP as a module. Classes are not required to be in one module, and can be loaded from module dependencies.
Example Implementations
The following example demonstrates a provider that registers the custom trust manager factory as a service.
Example: Provider
import org.kohsuke.MetaInfServices; import javax.net.ssl.TrustManagerFactory; import java.security.Provider; import java.util.Collections; import java.util.List; import java.util.Map; @MetaInfServices(Provider.class) public class CustomProvider extends Provider { public CustomProvider() { super("CustomProvider", 1.0, "Demo provider"); System.out.println("CustomProvider initialization."); final List<String> emptyList = Collections.emptyList(); final Map<String, String> emptyMap = Collections.emptyMap(); putService(new Service(this, TrustManagerFactory.class.getSimpleName(),"CustomAlgorithm", CustomTrustManagerFactorySpi.class.getName(), emptyList, emptyMap)); } }
The following example demonstrates a custom trust manager. This trust manager contains overloaded methods on checking if a client or server is trusted.
Example: TrustManager
import javax.net.ssl.SSLEngine; import javax.net.ssl.X509ExtendedTrustManager; import java.net.Socket; import java.security.cert.CertificateException; import java.security.cert.X509Certificate; public class CustomTrustManager extends X509ExtendedTrustManager { public void checkClientTrusted(X509Certificate[] x509Certificates, String s, Socket socket) throws CertificateException { // Insert your code here } public void checkServerTrusted(X509Certificate[] x509Certificates, String s, Socket socket) throws CertificateException { // Insert your code here } public void checkClientTrusted(X509Certificate[] x509Certificates, String s, SSLEngine sslEngine) throws CertificateException { // Insert your code here } public void checkServerTrusted(X509Certificate[] x509Certificates, String s, SSLEngine sslEngine) throws CertificateException { // Insert your code here } public void checkClientTrusted(X509Certificate[] x509Certificates, String s) throws CertificateException { // Insert your code here } public void checkServerTrusted(X509Certificate[] x509Certificates, String s) throws CertificateException { // Insert your code here } public X509Certificate[] getAcceptedIssuers() { // Insert your code here } }
The following example is a factory used to return instances of the trust manager.
Example: TrustManagerFactorySpi
import javax.net.ssl.ManagerFactoryParameters; import javax.net.ssl.TrustManager; import javax.net.ssl.TrustManagerFactorySpi; import java.security.InvalidAlgorithmParameterException; import java.security.KeyStore; import java.security.KeyStoreException; public class CustomTrustManagerFactorySpi extends TrustManagerFactorySpi { protected void engineInit(KeyStore keyStore) throws KeyStoreException { // Insert your code here } protected void engineInit(ManagerFactoryParameters managerFactoryParameters) throws InvalidAlgorithmParameterException { // Insert your code here } protected CustomTrustManager[] engineGetTrustManagers() { // Insert your code here } }
Adding the Custom Trust Manager
Once the provider and trust manager have been created, add them to the elytron
subsystem by using the steps outlined in Add a Custom Component to Elytron.
2.10.8. Using a Certificate Revocation List
If you want to validate a certificate against a certificate revocation list (CRL), you can configure this using the certificate-revocation-list
attribute for a trust manager in the elytron
subsystem. For example:
/subsystem=elytron/trust-manager=TRUST_MANAGER:write-attribute(name=certificate-revocation-list,value={path=/path/to/CRL_FILE.crl.pem}
For more information on the available attributes for a trust manager, see the trust-manager
Attributes table.
Your truststore must contain the certificate chain in order to check the validity of both the certification revocation list and the certificate. The truststore should not contain end-entity certificates, just certificate authority and intermediate certificates.
You can instruct the trust manager to reload the certificate revocation list by using the reload-certificate-revocation-list
operation.
/subsystem=elytron/trust-manager=TRUST_MANAGER:reload-certificate-revocation-list