Security Guide
For Use with Red Hat JBoss Enterprise Application Platform 6
Abstract
Part I. Security for Red Hat JBoss Enterprise Application Platform 6
Chapter 1. Introduction
1.1. About Red Hat JBoss Enterprise Application Platform 6
1.2. About Securing JBoss EAP 6
Part II. Securing the Platform
Chapter 2. Java Security Manager
2.1. About the Java Security Manager
The Java Security Manager is a class that manages the external boundary of the Java Virtual Machine (JVM) sandbox, controlling how code executing within the JVM can interact with resources outside the JVM. When the Java Security Manager is activated, the Java API checks with the security manager for approval before executing a wide range of potentially unsafe operations.
2.2. About Java Security Manager Policies
A set of defined permissions for different classes of code. The Java Security Manager compares actions requested by applications against the security policy. If an action is allowed by the policy, the Security Manager will permit that action to take place. If the action is not allowed by the policy, the Security Manager will deny that action. The security policy can define permissions based on the location of code, on the code's signature, or based on the subject's principals.
java.security.manager
and java.security.policy
.
A security policy's entry consists of the following configuration elements, which are connected to the policytool
:
- CodeBase
- The URL location (excluding the host and domain information) where the code originates from. This parameter is optional.
- SignedBy
- The alias used in the keystore to reference the signer whose private key was used to sign the code. This can be a single value or a comma-separated list of values. This parameter is optional. If omitted, presence or lack of a signature has no impact on the Java Security Manager.
- Principals
- A list of
principal_type
/principal_name
pairs, which must be present within the executing thread's principal set. The Principals entry is optional. If it is omitted, it signifies that the principals of the executing thread will have no impact on the Java Security Manager. - Permissions
- A permission is the access which is granted to the code. Many permissions are provided as part of the Java Enterprise Edition 6 (Java EE 6) specification.
2.3. Run JBoss EAP 6 Within the Java Security Manager
domain.sh
or standalone.sh
scripts. The following procedure guides you through the steps of configuring your instance to run within a Java Security Manager policy.
Prerequisites
- Before you following this procedure, you need to write a security policy, using the
policytool
command which is included with your Java Development Kit (JDK). This procedure assumes that your policy is located atEAP_HOME/bin/server.policy
. As an alternative, write the security policy using any text editor and manually save it asEAP_HOME/bin/server.policy
- The domain or standalone server must be completely stopped before you edit any configuration files.
Procedure 2.1. Configure the Security Manager for JBoss EAP 6
Open the configuration file.
Open the configuration file for editing. This file is located in one of two places, depending on whether you use a managed domain or standalone server. This is not the executable file used to start the server or domain.Managed Domain
- For Linux:
EAP_HOME/bin/domain.conf
- For Windows:
EAP_HOME\bin\domain.conf.bat
Standalone Server
- For Linux:
EAP_HOME/bin/standalone.conf
- For Windows:
EAP_HOME\bin\standalone.conf.bat
Add the Java options to the file.
To ensure the Java options are used, add them to the code block that begins with:if [ "x$JAVA_OPTS" = "x" ]; then
You can modify the-Djava.security.policy
value to specify the exact location of your security policy. It should go onto one line only, with no line break. Using==
when setting the-Djava.security.policy
property specifies that the security manager will use only the specified policy file. Using=
specifies that the security manager will use the specified policy combined with the policy set in thepolicy.url
section ofJAVA_HOME/lib/security/java.security
.Important
JBoss Enterprise Application Platform releases from 6.2.2 onwards require that the system propertyjboss.modules.policy-permissions
is set to true.Example 2.1. domain.conf
JAVA_OPTS="$JAVA_OPTS -Djava.security.manager -Djava.security.policy==$PWD/server.policy -Djboss.home.dir=/path/to/EAP_HOME -Djboss.modules.policy-permissions=true"
Example 2.2. domain.conf.bat
set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.manager -Djava.security.policy==\path\to\server.policy -Djboss.home.dir=\path\to\EAP_HOME -Djboss.modules.policy-permissions=true"
Example 2.3. standalone.conf
JAVA_OPTS="$JAVA_OPTS -Djava.security.manager -Djava.security.policy==$PWD/server.policy -Djboss.home.dir=$JBOSS_HOME -Djboss.modules.policy-permissions=true"
Example 2.4. standalone.conf.bat
set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.manager -Djava.security.policy==\path\to\server.policy -Djboss.home.dir=%JBOSS_HOME% -Djboss.modules.policy-permissions=true"
Start the domain or server.
Start the domain or server as normal.
2.4. Write a Java Security Manager Policy
An application called policytool
is included with most JDK and JRE distributions, for the purpose of creating and editing Java Security Manager security policies. Detailed information about policytool
is linked from http://docs.oracle.com/javase/6/docs/technotes/tools/.
Procedure 2.2. Setup a new Java Security Manager Policy
Start
policytool
.Start thepolicytool
tool in one of the following ways.Red Hat Enterprise Linux
From your GUI or a command prompt, run/usr/bin/policytool
.Microsoft Windows Server
Runpolicytool.exe
from your Start menu or from thebin\
of your Java installation. The location can vary.
Create a policy.
To create a policy, select. Add the parameters you need, then click .Edit an existing policy
Select the policy from the list of existing policies, and select thebutton. Edit the parameters as needed.Delete an existing policy.
Select the policy from the list of existing policies, and select thebutton.
2.5. IBM JRE and the Java Security Manager
JAVA_HOME/jre/lib/security/java.security
file, and set the policy.provider
value to sun.security.provider.PolicyFile
.
policy.provider=sun.security.provider.PolicyFile
2.6. Debug Security Manager Policies
java.security.debug
option configures the level of security-related information reported. The command java -Djava.security.debug=help
will produce help output with the full range of debugging options. Setting the debug level to all
is useful when troubleshooting a security-related failure whose cause is completely unknown, but for general use it will produce too much information. A sensible general default is access:failure
.
Procedure 2.3. Enable general debugging
This procedure will enable a sensible general level of security-related debug information.
Add the following line to the server configuration file.- If the JBoss EAP 6 instance is running in a managed domain, the line is added to the
bin/domain.conf
file for Linux or thebin\domain.conf.bat
file for Windows. - If the JBoss EAP 6 instance is running as a standalone server, the line is added to the
bin/standalone.conf
file for Linux, or thebin\standalone.conf.bat
file for Windows.
Linux
JAVA_OPTS="$JAVA_OPTS -Djava.security.debug=access:failure"
Windows
set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.debug=access:failure"
A general level of security-related debug information has been enabled.
Chapter 3. Security Realms
3.1. About Security Realms
ManagementRealm
stores authentication information for the Management API, which provides the functionality for the Management CLI and web-based Management Console. It provides an authentication system for managing JBoss EAP 6 itself. You could also use theManagementRealm
if your application needed to authenticate with the same business rules you use for the Management API.ApplicationRealm
stores user, password, and role information for Web Applications and EJBs.
REALM-users.properties
stores usernames and hashed passwords.REALM-roles.properties
stores user-to-role mappings.mgmt-groups.properties
stores user-to-group mapping file forManagementRealm
. Only used when Role-based Access Control (RBAC) is enabled.
domain/configuration/
and standalone/configuration/
directories. The files are written simultaneously by the add-user.sh
or add-user.bat
command. When you run the command, the first decision you make is which realm to add your new user to.
3.2. Add a New Security Realm
Run the Management CLI.
Start thejboss-cli.sh
orjboss-cli.bat
command and connect to the server.Create the new security realm itself.
Run the following command to create a new security realm namedMyDomainRealm
on a domain controller or a standalone server.For a domain instance, use this command:/host=master/core-service=management/security-realm=MyDomainRealm:add()
For a standalone instance, use this command:/core-service=management/security-realm=MyDomainRealm:add()
Create the references to the properties file which will store information about the new role.
Run the following command to create a pointer a file namedmyfile.properties
, which will contain the properties pertaining to the new role.Note
The newly created properties file is not managed by the includedadd-user.sh
andadd-user.bat
scripts. It must be managed externally.For a domain instance, use this command:/host=master/core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path=myfile.properties)
For a standalone instance, use this command:/core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path=myfile.properties)
Your new security realm is created. When you add users and roles to this new realm, the information will be stored in a separate file from the default security realms. You can manage this new file using your own applications or procedures.
3.3. Add a User to a Security Realm
Run the
add-user.sh
oradd-user.bat
command.Open a terminal and change directories to theEAP_HOME/bin/
directory. If you run Red Hat Enterprise Linux or another UNIX-like operating system, runadd-user.sh
. If you run Microsoft Windows Server, runadd-user.bat
.Choose whether to add a Management User or Application User.
For this procedure, typeb
to add an Application User.Choose the realm the user will be added to.
By default, the only available realm isApplicationRealm
. If you have added a custom realm, you can type its name instead.Type the username, password, and roles, when prompted.
Type the desired username, password, and optional roles when prompted. Verify your choice by typingyes
, or typeno
to cancel the changes. The changes are written to each of the properties files for the security realm.
Chapter 4. Encrypt Network Traffic
4.1. Specify Which Network Interface JBoss EAP 6 Uses
Isolating services so that they are accessible only to the clients who need them increases the security of your network. JBoss EAP 6 includes two interfaces in its default configuration, both of which bind to the IP address 127.0.0.1
, or localhost
, by default. One of the interfaces is called management
, and is used by the Management Console, CLI, and API. The other is called public
, and is used to deploy applications. These interfaces are not special or significant, but are provided as a starting point.
management
interface uses ports 9990
and 9999
by default, and the public
interface uses port 8080
, or port 8443
if you use HTTPS.
Warning
Stop JBoss EAP 6.
Stop JBoss EAP 6 by sending an interrupt in the appropriate way for your operating system. If you are running JBoss EAP 6 as a foreground application, the typical way to do this is to press Ctrl+C.Restart JBoss EAP 6, specifying the bind address.
Use the-b
command-line switch to start JBoss EAP 6 on a specific interface.Example 4.1. Specify the public interface.
EAP_HOME/bin/domain.sh -b 10.1.1.1
Example 4.2. Specify the management interface.
EAP_HOME/bin/domain.sh -bmanagement=10.1.1.1
Example 4.3. Specify different addresses for each interface.
EAP_HOME/bin/domain.sh -bmanagement=127.0.0.1 -b 10.1.1.1
Example 4.4. Bind the public interface to all network interfaces.
EAP_HOME/bin/domain.sh -b 0.0.0.0
-b
command-line switch to specify an IP address at runtime, so this is not recommended. If you do decide to do this, be sure to stop JBoss EAP 6 completely before editing the XML file.
4.2. Configure Network Firewalls to Work with JBoss EAP 6
Most production environments use firewalls as part of an overall network security strategy. If you need multiple server instances to communicate with each other or with external services such as web servers or databases, your firewall must take this into account. A well-managed firewall only opens the ports which are necessary for operation, and limits access to the ports to specific IP addresses, subnets, and network protocols.
Prerequisites
- Determine the ports you need to open.
- An understanding of your firewall software is required. This procedure uses the
system-config-firewall
command in Red Hat Enterprise Linux 6. Microsoft Windows Server includes a built-in firewall, and several third-party firewall solutions are available for each platform. On Microsoft Windows Server, you can use PowerShell to configure the firewall.
This procedure configures a firewall in an environment with the following assumptions:
- The operating system is Red Hat Enterprise Linux 6.
- JBoss EAP 6 runs on host
10.1.1.2
. Optionally, the server has its own firewall. - The network firewall server runs on host
10.1.1.1
on interfaceeth0
, and has an external interfaceeth1
. - You want traffic on port
5445
(a port used by JMS) forwarded to JBoss EAP 6. No other traffic should be allowed through the network firewall.
Procedure 4.1. Manage Network Firewalls and JBoss EAP 6 to work together
Log into the Management Console.
Log into the Management Console. By default, it runs on http://localhost:9990/console/.Determine the socket bindings used by the socket binding group.
- Click the Configuration label at the top of the Management Console.
- Expand the General Configuration menu. Select the Socket Binding.
- The Socket Binding Declarations screen appears. Initially, the
standard-sockets
group is shown. Choose a different group by selecting it from the combo box on the right-hand side.
Note
If you use a standalone server, it has only one socket binding group.The list of socket names and ports is shown, eight values per page. You can go through the pages by using the arrow navigation below the table.Determine the ports you need to open.
Depending on the function of the particular port and the requirements of your environment, some ports may need to be opened on your firewall.Configure your firewall to forward traffic to JBoss EAP 6.
Perform these steps to configure your network firewall to allow traffic on the desired port.- Log into your firewall machine and access a command prompt, as the root user.
- Issue the command
system-config-firewall
to launch the firewall configuration utility. A GUI or command-line utility launches, depending on the way you are logged into the firewall system. This task makes the assumption that you are logged in via SSH and using the command-line interface. - Use the TAB key on your keyboard to navigate to the Trusted Services screen appears.button, and press the ENTER key. The
- Do not change any values, but use the TAB key to navigate to the Other Ports screen appears.button, and press ENTER to advanced to the next screen. The
- Use the TAB key to navigate to the <Add> button, and press ENTER. The Port and Protocol screen appears.
- Enter
5445
in the Port / Port Range field, then use the TAB key to move to the Protocol field, and entertcp
. Use the TAB key to navigate to the button, and press ENTER. - Use the TAB key to navigate to the Port Forwarding screen.button until you reach the
- Use the TAB key to navigate to the <Add> button, and press the ENTER key.
- Fill in the following values to set up port forwarding for port
5445
.- Source interface:
eth1
- Protocol:
tcp
- Port / Port Range:
5445
- Destination IP address:
10.1.1.2
- Port / Port Range:
5445
Use the TAB key to navigate to thebutton, and press ENTER. - Use the TAB key to navigate to thebutton, and press ENTER.
- Use the TAB key to navigate to thebutton, and press ENTER. To apply the changes, read the warning and click .
Configure a firewall on your JBoss EAP 6 host.
Some organizations choose to configure a firewall on the JBoss EAP 6 server itself, and close all ports that are not necessary for its operation. See Section 4.3, “Network Ports Used By JBoss EAP 6” and determine which ports to open, then close the rest. The default configuration of Red Hat Enterprise Linux 6 closes all ports except22
(used for Secure Shell (SSH) and5353
(used for multicast DNS). While you are configuring ports, ensure you have physical access to your server so that you do not inadvertently lock yourself out.
Your firewall is configured to forward traffic to your internal JBoss EAP 6 server in the way you specified in your firewall configuration. If you chose to enable a firewall on your server, all ports are closed except the ones needed to run your applications.
Procedure 4.2. Configuring Firewall on Microsoft Windows using PowerShell
- Switch off firewall for debug purpose to determine whether the current network behavior is related to the firewall configuration.
Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall set allprofiles state off"'
- Allow UDP connections on port 23364. For example:
Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall firewall add rule name="UDP Port 23364" dir=in action=allow protocol=UDP localport=23364"' Start-Process "$psHome\powershell.exe" -Verb Runas -ArgumentList '-command "NetSh Advfirewall firewall add rule name="UDP Port 23364" dir=out action=allow protocol=UDP localport=23364"'
Procedure 4.3. Configure the Firewall on Red Hat Enterprise Linux 7 to Allow mod_cluster Advertising
- To allow mod_cluster advertising on Red Hat Enterprise Linux 7, you must enable the UDP port in the firewall as follows:
firewall-cmd --permanent --zone=public --add-port=23364/udp
Note
224.0.1.105:23364 is the default address and port for mod_cluster balancer advertising UDP multicast.
4.3. Network Ports Used By JBoss EAP 6
- Whether your server groups use one of the default socket binding groups, or a custom group.
- The requirements of your individual deployments.
Note
8080
, and your server uses a port offset of 100
, its HTTP port is 8180
.
The default socket binding groups
full-ha-sockets
full-sockets
ha-sockets
standard-sockets
Name | Port | Multicast Port | Description | full-ha-sockets | full-sockets | ha-socket | standard-socket |
---|---|---|---|---|---|---|---|
ajp | 8009 | Apache JServ Protocol. Used for HTTP clustering and load balancing. | Yes | Yes | Yes | Yes | |
http | 8080 | The default port for deployed web applications. | Yes | Yes | Yes | Yes | |
https | 8443 | SSL-encrypted connection between deployed web applications and clients. | Yes | Yes | Yes | Yes | |
jacorb | 3528 | CORBA services for JTS transactions and other ORB-dependent services. | Yes | Yes | No | No | |
jacorb-ssl | 3529 | SSL-encrypted CORBA services. | Yes | Yes | No | No | |
jgroups-diagnostics | 7500 | Multicast. Used for peer discovery in HA clusters. Not configurable using the Management Interfaces. | Yes | No | Yes | No | |
jgroups-mping | 45700 | Multicast. Used to discover initial membership in a HA cluster. | Yes | No | Yes | No | |
jgroups-tcp | 7600 | Unicast peer discovery in HA clusters using TCP. | Yes | No | Yes | No | |
jgroups-tcp-fd | 57600 | Used for HA failure detection over TCP. | Yes | No | Yes | No | |
jgroups-udp | 55200 | 45688 | Multicast peer discovery in HA clusters using UDP. | Yes | No | Yes | No |
jgroups-udp-fd | 54200 | Used for HA failure detection over UDP. | Yes | No | Yes | No | |
messaging | 5445 | JMS service. | Yes | Yes | No | No | |
messaging-group | Referenced by HornetQ JMS broadcast and discovery groups. | Yes | Yes | No | No | ||
messaging-throughput | 5455 | Used by JMS Remoting. | Yes | Yes | No | No | |
mod_cluster | 23364 | Multicast port for communication between JBoss EAP 6 and the HTTP load balancer. | Yes | No | Yes | No | |
osgi-http | 8090 | Used by internal components which use the OSGi subsystem. Not configurable using the Management Interfaces. | Yes | Yes | Yes | Yes | |
remoting | 4447 | Used for remote EJB invocation. | Yes | Yes | Yes | Yes | |
txn-recovery-environment | 4712 | The JTA transaction recovery manager. | Yes | Yes | Yes | Yes | |
txn-status-manager | 4713 | The JTA / JTS transaction manager. | Yes | Yes | Yes | Yes |
In addition to the socket binding groups, each host controller opens two more ports for management purposes:
9990
- The Web Management Console port9999
- The port used by the Management Console and Management API
4.4. About Encryption
4.5. About SSL Encryption
Warning
4.6. Implement SSL Encryption for the JBoss EAP 6 Web Server
Many web applications require an SSL-encrypted connection between clients and server, also known as a HTTPS
connection. You can use this procedure to enable HTTPS
on your server or server group.
Warning
Prerequisites
- A set of SSL encryption keys and an SSL encryption certificate. You may purchase these from a certificate-signing authority, or you can generate them yourself using command-line utilities. To generate encryption keys using utilities available on Red Hat Enterprise Linux, see Section 4.7, “Generate a SSL Encryption Key and Certificate”.
- The following details about your specific environment and setup:
- The full directory name where the certificate files are stored.
- The encryption password for your encryption keys.
- Management CLI running and connected to your domain controller or standalone server.
- Select appropriate cipher suites.
There are a number of available cryptographic primitives used as building blocks to form cipher suites. The first table lists recommended cryptographic primitives. The second lists cryptographic primitives which, while they may be used for compatibility with existing software, are not considered as secure as those recommended.
Warning
cipher-suite
. Enabling weak ciphers is a significant security risk. Consult your JDK vendor's documentation before deciding on particular cipher suites as there may be compatibility issues.
RSA with 2048 bit keys and OAEP |
AES-128 in CBC mode |
SHA-256 |
HMAC-SHA-256 |
HMAC-SHA-1 |
RSA with key sizes larger than 1024 and legacy padding |
AES-192 |
AES-256 |
3DES (triple DES, with two or three 56 bit keys) |
RC4 (strongly discouraged) |
SHA-1 |
HMAC-MD5 |
Note
/profile=default
from the beginning of any management CLI commands.
Warning
Procedure 4.4. Configure the JBoss Web Server to use HTTPS
Add a new HTTPS connector.
Create a secure connector, named HTTPS, which uses thehttps
scheme, thehttps
socket binding (which defaults to8443
), and is set to be secure./profile=default/subsystem=web/connector=HTTPS/:add(socket-binding=https,scheme=https,protocol=HTTP/1.1,secure=true)
Configure the SSL encryption certificate and keys.
Configure your SSL certificate, substituting your own values for the example ones. This example assumes that the keystore is copied to the server configuration directory, which isEAP_HOME/domain/configuration/
for a managed domain./profile=default/subsystem=web/connector=HTTPS/ssl=configuration:add(name=https,certificate-key-file="${jboss.server.config.dir}/keystore.jks",password=SECRET, key-alias=KEY_ALIAS, cipher-suite=CIPHERS)
Set the protocol to
TLSv1
./profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=protocol,value=TLSv1)
Deploy an application.
Deploy an application to a server group which uses the profile you have configured. If you use a standalone server, deploy an application to your server. HTTPS requests to it use the new SSL-encrypted connection.
4.7. Generate a SSL Encryption Key and Certificate
Prerequisites
- You need the
keytool
utility, which is provided by any Java Development Kit implementation. OpenJDK on Red Hat Enterprise Linux installs this command to/usr/bin/keytool
. - Understand the syntax and parameters of the
keytool
command. This procedure uses extremely generic instructions, because further discussion of the specifics of SSL certificates or thekeytool
command are out of scope for this documentation.
Procedure 4.5. Generate a SSL Encryption Key and Certificate
Generate a keystore with public and private keys.
Run the following command to generate a keystore namedserver.keystore
with the aliasjboss
in your current directory.keytool -genkeypair -alias jboss -keyalg RSA -keystore server.keystore -storepass mykeystorepass --dname "CN=jsmith,OU=Engineering,O=mycompany.com,L=Raleigh,S=NC,C=US"
The following table describes the parameters used in the keytool command:Parameter Description -genkeypair
The keytool
command to generate a key pair containing a public and private key.-alias
The alias for the keystore. This value is arbitrary, but the alias jboss
is the default used by the JBoss Web server.-keyalg
The key pair generation algorithm. In this case it is RSA
.-keystore
The name and location of the keystore file. The default location is the current directory. The name you choose is arbitrary. In this case, the file will be named server.keystore
.-storepass
This password is used to authenticate to the keystore so that the key can be read. The password must be at least 6 characters long and must be provided when the keystore is accessed. In this case, we used mykeystorepass
. If you omit this parameter, you will be prompted to enter it when you execute the command.-keypass
This is the password for the actual key.Note
Due to an implementation limitation this must be the same as the store password.--dname
A quoted string describing the distinguished name for the key, for example: "CN=jsmith,OU=Engineering,O=mycompany.com,L=Raleigh,C=US". This string is a concatenation of the following components: CN
- The common name or host name. If the hostname is "jsmith.mycompany.com", theCN
is "jsmith".OU
- The organizational unit, for example "Engineering"O
- The organization name, for example "mycompany.com".L
- The locality, for example "Raleigh" or "London"S
- The state or province, for example "NC". This parameter is optional.C
- The 2 letter country code, for example "US" or "UK",
When you execute the above command, you are prompted for the following information:- If you did not use the
-storepass
parameter on the command line, you are asked to enter the keystore password. Re-enter the new password at the next prompt. - If you did not use the
-keypass
parameter on the command line, you are asked to enter the key password. Press Enter to set this to the same value as the keystore password.
When the command completes, the fileserver.keystore
now contains the single key with the aliasjboss
.Verify the key.
Verify that the key works properly by using the following command.keytool -list -keystore server.keystore
You are prompted for the keystore password. The contents of the keystore are displayed (in this case, a single key calledjboss
). Notice the type of thejboss
key, which isPrivateKeyEntry
. This indicates that the keystore contains both a public and private entry for this key.Generate a certificate signing request.
Run the following command to generate a certificate signing request using the public key from the keystore you created in step 1.keytool -certreq -keyalg RSA -alias jboss -keystore server.keystore -file certreq.csr
You are prompted for the password in order to authenticate to the keystore. Thekeytool
command then creates a new certificate signing request calledcertreq.csr
in the current working directory.Test the newly generated certificate signing request.
Test the contents of the certificate by using the following command.openssl req -in certreq.csr -noout -text
The certificate details are shown.Optional: Submit your certificate signing request to a Certificate Authority (CA).
A Certificate Authority (CA) can authenticate your certificate so that it is considered trustworthy by third-party clients. The CA supplies you with a signed certificate, and optionally with one or more intermediate certificates.Optional: Export a self-signed certificate from the keystore.
If you only need it for testing or internal purposes, you can use a self-signed certificate. You can export one from the keystore you created in step 1 as follows:keytool -export -alias jboss -keystore server.keystore -file server.crt
You are prompted for the password in order to authenticate to the keystore. A self-signed certificate, namedserver.crt
, is created in the current working directory.Import the signed certificate, along with any intermediate certificates.
Import each certificate, in the order that you are instructed by the CA. For each certificate to import, replaceintermediate.ca
orserver.crt
with the actual file name. If your certificates are not provided as separate files, create a separate file for each certificate, and paste its contents into the file.Note
Your signed certificate and certificate keys are valuable assets. Be cautious with how you transport them between servers.keytool -import -keystore server.keystore -alias intermediateCA -file intermediate.ca
keytool -importcert -alias jboss -keystore server.keystore -file server.crt
Test that your certificates imported successfully.
Run the following command, and enter the keystore password when prompted. The contents of your keystore are displayed, and the certificates are part of the list.keytool -list -keystore server.keystore
Your signed certificate is now included in your keystore and is ready to be used to encrypt SSL connections, including HTTPS web server communications.
4.8. SSL Connector Reference
default
. Change the profile name to the one you wish to configure, for a managed domain, or omit the /profile=default
portion of the command, for a standalone server.
Attribute | Description | CLI Command |
---|---|---|
name |
The display name of the SSL connector.
|
Attribute
name is read-only.
|
verify-client |
The possible values of
verify-client differ, based upon whether the HTTP/HTTPS connector is used, or the native APR connector is used.
HTTP/HTTPS Connector
Possible values are Native APR Connector
Possible values are |
The first example command uses the HTTPS connector.
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=verify-client,value=want)
The second example command uses the APR connector.
/profile=default/subsystem=web/connector=APR/ssl=configuration/:write-attribute(name=verify-client,value=require) |
verify-depth |
The maximum number of intermediate certificate issuers checked before deciding that the clients do not have a valid certificate. The default value is
10 .
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=verify-depth,value=10) |
certificate-key-file |
The full file path and file name of the keystore file where the signed server certificate is stored. With JSSE encryption, this certificate file will be the only one, while OpenSSL uses several files. The default value is the
.keystore file in the home directory of the user running JBoss EAP 6. If your keystoreType does not use a file, set the parameter to an empty string.
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=certificate-key-file,value=../domain/configuration/server.keystore) |
certificate-file |
If you use OpenSSL encryption, set the value of this parameter to the path to the file containing the server certificate.
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=certificate-file,value=server.crt) |
password |
The password for both the truststore and keystore. In the following example, replace PASSWORD with your own password.
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=password,value=PASSWORD) |
protocol |
The version of the SSL protocol to use. Supported values depend on the underlying SSL implementation (whether JSSE or OpenSSL). Refer to the Java SSE Documentation.
You can also specify a combination of protocols, which is comma separated. For example, TLSv1, TLSv1.1,TLSv1.2.
Warning
Red Hat recommends that you explicitly disable SSL in favor of TLSv1.1 or TLSv1.2 in all affected packages.
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=protocol,value=ALL) /profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=protocol,value="TLSv1, TLSv1.1,TLSv1.2") |
cipher-suite |
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 you only use one syntax.
The default is
HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5 .
The example only lists two possible ciphers, but real-world examples will likely use more.
Important
Using weak ciphers is a significant security risk. See http://www.nist.gov/manuscript-publication-search.cfm?pub_id=915295 for NIST recommendations on cipher suites.
For a list of available OpenSSL ciphers, see https://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS. Note that the following are not supported:
@SECLEVEL , SUITEB128 , SUITEB128ONLY , SUITEB192 .
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=cipher-suite, value="TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA") |
key-alias |
The alias used to for the server certificate in the keystore. In the following example, replace KEY_ALIAS with your certificate's alias.
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=key-alias,value=KEY_ALIAS) |
truststore-type |
The type of the truststore. Various types of truststores are available, including
PKCS12 and Java's standard JKS .
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=truststore-type,value=jks) |
keystore-type |
The type of the keystore, Various types of keystores are available, including
PKCS12 and Java's standard JKS .
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=keystore-type,value=jks) |
ca-certificate-file |
The file containing the CA certificates. This is the
truststoreFile , in the case of JSSE, and uses the same password as the keystore. The ca-certificate-file file is used to validate client certificates.
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=certificate-file,value=ca.crt) |
ca-certificate-password |
The Certificate password for the
ca-certificate-file . In the following example, replace the MASKED_PASSWORD with your own masked password.
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=ca-certificate-password,value=MASKED_PASSWORD) |
ca-revocation-url |
A file or URL which contains the revocation list. It refers to the
crlFile for JSSE or the SSLCARevocationFile for SSL.
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=ca-revocation-url,value=ca.crl) |
session-cache-size |
The size of the SSLSession cache. This attribute applies only to JSSE connectors. The default is
0 , which specifies an unlimited cache size.
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=session-cache-size,value=100) |
session-timeout |
The number of seconds before a cached SSLSession expires. This attribute applies only to JSSE connectors. The default is
86400 seconds, which is 24 hours.
|
/profile=default/subsystem=web/connector=HTTPS/ssl=configuration/:write-attribute(name=session-timeout,value=43200) |
4.9. FIPS 140-2 Compliant Encryption
4.9.1. About FIPS 140-2 Compliance
4.9.2. FIPS 140-2 Compliant Cryptography on IBM JDK
Key storage
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
Examine FIPS provider information
-Djavax.net.debug=true
to standalone.conf
or domain.conf
. Information about the FIPS provider is logged to server.log
, 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
4.9.3. FIPS 140-2 Compliant Passwords
- Must be at least seven (7) characters in length.
- Must include characters from at least three (3) of the following character classes:
- ASCII digits,
- lowercase ASCII,
- uppercase ASCII,
- non-alphanumeric ASCII, and
- non-ASCII.
4.9.4. Enable FIPS 140-2 Cryptography for SSL on Red Hat Enterprise Linux 6
Prerequisites
- Red Hat Enterprise Linux 6 must already be configured to be FIPS 140-2 compliant. Refer to https://access.redhat.com/knowledge/solutions/137833.
Procedure 4.6. Enable FIPS 140-2 Compliant Cryptography for SSL
Create the database
Create the NSS database in a directory own by thejboss
user.$ mkdir -p /usr/share/jboss-as/nssdb $ chown jboss /usr/share/jboss-as/nssdb $ modutil -create -dbdir /usr/share/jboss-as/nssdb
Create NSS configuration file
Create a new text file with the namenss_pkcsll_fips.cfg
in the/usr/share/jboss-as
directory with the following contents:name = nss-fips nssLibraryDirectory=/usr/lib64 nssSecmodDirectory=/usr/share/jboss-as/nssdb nssModule = fips
The NSS configuration file must specify:- a name,
- the directory where the NSS library is located, and
- the directory where the NSS database was created as per step 1.
If you are not running a 64bit version of Red Hat Enterprise Linux 6 then setnssLibraryDirectory
to/usr/lib
instead of/usr/lib64
.Enable SunPKCS11 provider
Edit thejava.security
configuration file for your JRE ($JAVA_HOME/jre/lib/security/java.security
) and add the following line:security.provider.1=sun.security.pkcs11.SunPKCS11 /usr/share/jboss-as/nss_pkcsll_fips.cfg
Note that the configuration file specified in this line is the file created in step 2.Any othersecurity.provider.X
lines in this file must have the value of their X increased by one to ensure that this provider is given priority.Enable FIPS mode for the NSS library
Run themodutil
command as shown to enable FIPS mode:modutil -fips true -dbdir /usr/share/jboss-as/nssdb
Note that the directory specified here is the one created in step 1.You may get a security library error at this point requiring you to regenerate the library signatures for some of the NSS shared objects.Change the password on the FIPS token
Set the password on the FIPS token using the following command. Note that the name of the token must beNSS FIPS 140-2 Certificate DB
.modutil -changepw "
NSS FIPS 140-2 Certificate DB
" -dbdir /usr/share/jboss-as/nssdbThe password used for the FIPS token must be a FIPS compliant password.Create certificate using NSS tools
Enter the following command to create a certificate using the NSS tools.certutil -S -k rsa -n jbossweb -t "u,u,u" -x -s "CN=localhost, OU=MYOU, O=MYORG, L=MYCITY, ST=MYSTATE, C=MY" -d /usr/share/jboss-as/nssdb
Configure the HTTPS connector to use the PKCS11 keystore
Add a HTTPS connector using the following command in the JBoss CLI Tool:/subsystem=web/connector=https/:add(socket-binding=https,scheme=https,protocol=HTTP/1.1,secure=true)
Then add the SSL configuration with the following command, replacing PASSWORD with the FIPS compliant password from step 5./subsystem=web/connector=https/ssl=configuration:add(name=https,password=PASSWORD,keystore-type=PKCS11, cipher-suite="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")
Verify
Verify that the JVM can read the private key from the PKCS11 keystore by running the following command:keytool -list -storetype pkcs11
Example 4.5. XML configuration for HTTPS connector using FIPS 140-2 compliance
<connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true"> <ssl name="https" password="****" cipher-suite="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" keystore-type="PKCS11"/> </connector>
cipher-suite
attribute has linebreaks inserted to make it easier to read.
Chapter 5. Secure the Management Interfaces
5.1. Default User Security Configuration
All management interfaces in JBoss EAP 6 are secured by default. This security takes two different forms:
- Local interfaces are secured by a SASL contract between local clients and the server they connect to. This security mechanism is based on the client's ability to access the local filesystem. This is because access to the local filesystem would allow the client to add a user or otherwise change the configuration to thwart other security mechanisms. This adheres to the principle that if physical access to the filesystem is achieved, other security mechanisms are superfluous. The mechanism happens in four steps:
Note
HTTP access is considered to be remote, even if you connect to the localhost using HTTP.- The client sends a message to the server which includes a request to authenticate with the local SASL mechanism.
- The server generates a one-time token, writes it to a unique file, and sends a message to the client with the full path of the file.
- The client reads the token from the file and sends it to the server, verifying that it has local access to the filesystem.
- The server verifies the token and then deletes the file.
- Remote clients, including local HTTP clients, use realm-based security. The default realm with the permissions to configure the JBoss EAP 6 instance remotely using the management interfaces is
ManagementRealm
. A script is provided which allows you to add users to this realm (or realms you create). For more information on adding users, see the Getting Started chapter of the JBoss EAP 6 Installation Guide. For each user, the username and a hashed password are stored in a file.- Managed domain
EAP_HOME/domain/configuration/mgmt-users.properties
- Standalone server
EAP_HOME/standalone/configuration/mgmt-users.properties
Even though the contents of themgmt-users.properties
are masked, the file must still be treated as a sensitive file. It is recommended that it be set to the file mode of600
, which gives no access other than read and write access by the file owner.
5.2. Overview of Advanced Management Interface Configuration
EAP_HOME/domain/configuration/host.xml
or EAP_HOME/standalone/configuration/standalone.xml
controls which network interfaces the host controller process binds to, which types of management interfaces are available at all, and which type of authentication system is used to authenticate users on each interface. This topic discusses how to configure the Management Interfaces to suit your environment.
<management>
element that includes the following four configurable child elements. The security realms and outbound connections are each first defined, and then applied to the management interfaces as attributes.
- <security-realms>
- <outbound-connections>
- <management-interfaces>
- <audit-log>
Note
The security realm is responsible for the authentication and authorization of users allowed to administer JBoss EAP 6 via the Management API, Management CLI, or web-based Management Console.
ManagementRealm
and ApplicationRealm
. Each of these security realms uses a -users.properties
file to store users and hashed passwords, and a -roles.properties
to store mappings between users and roles. Support is also included for an LDAP-enabled security realm.
Note
Some security realms connect to external interfaces, such as an LDAP server. An outbound connection defines how to make this connection. A pre-defined connection type, ldap-connection
, sets all of the required and optional attributes to connect to the LDAP server and verify the credential.
A management interface includes properties about how connect to and configure JBoss EAP. Such information includes the named network interface, port, security realm, and other configurable information about the interface. Two interfaces are included in a default installation:
http-interface
is the configuration for the web-based Management Console.native-interface
is the configuration for the command-line Management CLI and the REST-like Management API.
5.3. Disable the HTTP Management Interface
Note
console-enabled
attribute of the HTTP interface to false
, instead of disabling the interface completely.
/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=console-enabled,value=false)
Example 5.1. Read the Configuration of the HTTP Interface
/host=master/core-service=management/management-interface=http-interface/:read-resource(recursive=true,proxies=false,include-runtime=false,include-defaults=true)
{
"outcome" => "success",
"result" => {
"console-enabled" => true,
"interface" => "management",
"port" => expression "${jboss.management.http.port:9990}",
"secure-port" => undefined,
"security-realm" => "ManagementRealm"
}
}
Example 5.2. Remove the HTTP Interface
/host=master/core-service=management/management-interface=http-interface/:remove
Example 5.3. Re-Create the HTTP Interface
/host=master/core-service=management/management-interface=http-interface:add(console-enabled=true,interface=management,port="${jboss.management.http.port:9990}",security-realm=ManagementRealm)
5.4. Remove Silent Authentication from the Default Security Realm
The default installation of JBoss EAP 6 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 username or password authentication. This functionality is enabled as a convenience, and to assist local users running 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.
local
element within the security-realm
section of the configuration file. This applies to both the standalone.xml
for a Standalone Server instance, or host.xml
for a Managed Domain. You should only consider the removal of the local
element if you understand the impact that it might have on your particular server configuration.
local
element visible in the following example.
Example 5.4. Example of the local
element in the security-realm
<security-realms> <security-realm name="ManagementRealm"> <authentication> <local default-user="$local"/> <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/> </authentication> </security-realm> <security-realm name="ApplicationRealm"> <authentication> <local default-user="$local" allowed-users="*"/> <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>
Prerequisites
- Start the JBoss EAP 6 instance.
- Launch the Management CLI.
Procedure 5.1. Remove Silent Authentication from the Default Security Realm
Remove silent authentication with the Management CLI
Remove thelocal
element from the Management Realm and Application Realm as required.- Remove the
local
element from the Management Realm.For Standalone Servers
/core-service=management/security-realm=ManagementRealm/authentication=local:remove
For Managed Domains
/host=HOST_NAME/core-service=management/security-realm=ManagementRealm/authentication=local:remove
- Remove the
local
element from the Application Realm.For Standalone Servers
/core-service=management/security-realm=ApplicationRealm/authentication=local:remove
For Managed Domains
/host=HOST_NAME/core-service=management/security-realm=ApplicationRealm/authentication=local:remove
The silent authentication mode is removed from the ManagementRealm
and the ApplicationRealm
.
5.5. Disable Remote Access to the JMX Subsystem
/profile=default
prefix from the commands.
Note
Example 5.5. Remove the Remoting Connector from the JMX Subsystem
/profile=default/subsystem=jmx/remoting-connector=jmx/:remove
Example 5.6. Remove the JMX Subsystem
/profile=default/subsystem=jmx/:remove
5.6. Configure Security Realms for the Management Interfaces
The management interfaces are configured to use the ManagementRealm
security realm by default. The ManagementRealm stores its user password combinations in the file mgmt-users.properties
.
Example 5.7. Default ManagementRealm
/host=master/core-service=management/security-realm=ManagementRealm/:read-resource(recursive=true,proxies=false,include-runtime=false,include-defaults=true)
{
"outcome" => "success",
"result" => {
"authorization" => undefined,
"server-identity" => undefined,
"authentication" => {"properties" => {
"path" => "mgmt-users.properties",
"plain-text" => false,
"relative-to" => "jboss.domain.config.dir"
}}
}
}
The following commands create a new security realm called TestRealm
and set the directory for the relevant properties file.
Example 5.8. Create a new Security Realm
/host=master/core-service=management/security-realm=TestRealm/:add
/host=master/core-service=management/security-realm=TestRealm/authentication=properties/:add(path=TestUsers.properties, relative-to=jboss.domain.config.dir)
To use Security Domain to authenticate to the Management interfaces:
security-realm
attribute of the management interface:
Example 5.9. Specify a Security Realm to use for the HTTP Management Interface
/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=TestRealm)
5.7. Configure the Management Console for HTTPS
standalone
and domain
mode configurations. For domain
mode, prefix the management CLI commands with the name of the host, for example: /host=master
.
Procedure 5.2.
Create a keystore to secure the management console.
Note
This keystore must be in JKS format as the management console is not compatible with keystores in JCEKS format.In a terminal emulator, enter the following command. For the parametersalias
,keypass
,keystore
,storepass
anddname
, replace the example values with values of your choice.The parametervalidity
specifies for how many days the key is valid. A value of 730 equals two years.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 -vEnsure the Management Console Binds to HTTPS
Standalone Mode
Ensure the management console binds toHTTPS
for its interface by adding themanagement-https
configuration and removing themanagement-http
configuration.Ensure the JBoss EAP instance is running, then enter the following management CLI commands:/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)
The expected output from these commands is:{"outcome" => "success"}
Note
At this point the JBoss EAP log may display the following error message. This is to be expected because the SSL configuration is not yet completed.JBAS015103: A secure port has been specified for the HTTP interface but no SSL configuration in the realm.
Domain Mode
Change the socket element within the management-interface section by adding secure-port and removing port configuration.Ensure the JBoss EAP instance is running, then enter the following management CLI commands:/host=master/core-service=management/management-interface=http-interface:write-attribute(name=secure-port,value=9443)
/host=master/core-service=management/management-interface=http-interface:undefine-attribute(name=port)
Note
At this point the JBoss EAP log may display the following error message. This is to be expected because the SSL configuration is not yet completed.JBAS015103: A secure port has been specified for the HTTP interface but no SSL configuration in the realm.
Optional: Custom socket-binding group
If you are using a customsocket-binding
group, ensure themanagement-https
binding is defined (it is present by default, bound to port9443
). Edit the master configuration file - for examplestandalone.xml
- to match the following.<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}"> <socket-binding name="management-native" interface="management" port="${jboss.management.native.port:9999}"/> <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:9443}"/>
Create a new Security Realm
Enter the following commands to create a new security realm namedManagementRealmHTTPS
:/host=master/core-service=management/security-realm=ManagementRealmHTTPS/:add /host=master/core-service=management/security-realm=ManagementRealmHTTPS/authentication=properties/:add(path=ManagementUsers.properties, relative-to=jboss.domain.config.dir)
Configure Management Interface to use the new security realm
Enter the following commands:/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=ManagementRealmHTTPS)
Configure the management console to use the keystore.
Enter the following management CLI command. For the parametersfile
,password
andalias
their values must be copied from the step Create a keystore to secure the management console./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)The expected output from this command is:{ "outcome" => "success", "response-headers" => { "operation-requires-reload" => true, "process-state" => "reload-required" } }
Restart the JBoss EAP server.
On restarting the server the log should contain the following, just before the text which states the number of services that are started. The management console is now listening on port 9443, which confirms that the procedure was successful.14:53:14,720 INFO [org.jboss.as] (Controller Boot Thread) JBAS015962: Http management interface listening on https://127.0.0.1:9443/management 14:53:14,721 INFO [org.jboss.as] (Controller Boot Thread) JBAS015952: Admin console listening on https://127.0.0.1:9443
Note
5.8. Use Distinct Interfaces for HTTP and HTTPS connections to the Management Interface
secure-interface
attribute specifies the network interface on which the host's socket for HTTPS management communication should be opened, if a different interface should be used from that specified by the interface
attribute. If it is not specified then the interface specified by the interface
attribute is used.
secure-interface
attribute has no effect if the secure-port
attribute is not set.
EAP_HOME/domain/configuration/host.xml
configuration that sets the secure-interface
attribute to listen for HTTPS traffic on a distinct interface from HTTP traffic:
<?xml version='1.0' encoding='UTF-8'?> <host name="master" xmlns="urn:jboss:domain:3.0"> <management> <security-realms> <security-realm name="ManagementRealm"> <authentication> <local default-user="$local" /> <properties path="mgmt-users.properties" relative-to="jboss.domain.config.dir"/> </authentication> </security-realm> </security-realms> <management-interfaces> <native-interface security-realm="ManagementRealm"> <socket interface="management" port="${jboss.management.native.port:9999}"/> </native-interface> <http-interface security-realm="ManagementRealm"> <socket interface="management" port="${jboss.management.http.port:9990}" secure-port="${jboss.management.https.port:9943}" secure-interface="secure-management"/> </http-interface> </management-interfaces> </management> <domain-controller> <local/> <!-- Alternative remote domain controller configuration with a host and port --> <!-- <remote host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}" security-realm="ManagementRealm"/> --> </domain-controller> <interfaces> <interface name="management"> <inet-address value="${jboss.bind.address.management:127.0.0.1}"/> </interface> <interface name="secure-management"> <inet-address value="${jboss.bind.address:10.10.64.1}"/> </interface> </interfaces> </host>
5.9. Using 2-way SSL for the Management interface and the CLI
- 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 you are going to use a password vault to store the keystore and truststore passwords (recommended), the password vault should already be created. Refer to Section 7.1, “Password Vault System”.
Procedure 5.3.
- Generate the stores:
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 trust stores:
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 in the configuration for your installation (
host.xml
orstandalone.xml
) and point the interface to it:This can be done by manually editing the configuration file (not recommended) or by 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)
Important
The provided commands apply to standalone mode only. For domain mode, add/host=master
before each command. - Change the
security-realm
of the native-interface to the new Certificate Realm./host=master/core-service=management/management-interface=native-interface:write-attribute(name=security-realm,value=CertificateRealm)
- Add the SSL configuration for the CLI, which uses
EAP_HOME/bin/jboss-cli.xml
as a settings file. Either use a password vault to store the keystore and truststore passwords (recommended), or store them in plain text:- To store the keystore and truststore passwords in a password vault:Edit
EAP_HOME/bin/jboss-cli.xml
and add the SSL configuration (using the appropriate values for the variables). Also add the vault configuration, replacing each value with those of your 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="path-to/jboss-eap/vault/"/> </vault> <alias>$HOST2alias</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>
- To store the keystore and truststore passwords in plain text:Edit
EAP_HOME/bin/jboss-cli.xml
and add the SSL configuration (using the appropriate values for the variables):<ssl> <alias>$HOST2alias</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>
5.10. Secure the Management Interfaces via JAAS
/subsystem=security/security-domain=UsersLMDomain:add(cache-type=default) /subsystem=security/security-domain=UsersLMDomain/authentication=classic:add /subsystem=security/security-domain=UsersLMDomain/authentication=classic/login-module=UsersRoles:add()
/core-service=management/security-realm=SecurityDomainAuthnRealm:add /core-service=management/security-realm=SecurityDomainAuthnRealm/authentication=jaas:add(name=UsersLMDomain)
assign-groups
determines whether loaded user membership information from the Security Domain is used for group assignment in the Security Realm. When set to true
this group assignment is used for Role-Based Access Control (RBAC).
assign-groups
attribute can be set to true by this CLI command:
/core-service=management/security-realm=ManagementRealm/authentication=jaas:write-attribute(name=assign-groups,value=true)
5.11. LDAP
5.11.1. About LDAP
5.11.2. Use LDAP to Authenticate to the Management Interfaces
- Create an outbound connection to the LDAP server.
- Create an LDAP-enabled security realm.
- Reference the new security domain in the Management Interface.
The LDAP outbound connection allows the following attributes:
Attribute | Required | Description |
---|---|---|
url | yes |
The URL address of the directory server.
|
search-dn | no |
The fully distinguished name (DN) of the user authorized to perform searches.
|
search-credentials | no |
The password of the user authorized to perform searches.
|
initial-context-factory | no |
The initial context factory to use when establishing the connection. Defaults to
com.sun.jndi.ldap.LdapCtxFactory .
|
security-realm | no |
The security realm to reference to obtain a configured
SSLContext to use when establishing the connection.
|
Example 5.10. Add an LDAP Outbound Connection
- Search DN:
cn=search,dc=acme,dc=com
- Search Credential:
myPass
- URL:
ldap://127.0.0.1:389
/host=master/core-service=management/security-realm=ldap_security_realm:add
/host=master/core-service=management/ldap-connection=ldap_connection/:add(search-credential=myPass,url=ldap://127.0.0.1:389,search-dn="cn=search,dc=acme,dc=com")
The Management Interfaces can authenticate against LDAP server instead of the property-file based security realms configured by default. The LDAP authenticator operates by first establishing a connection to the remote directory server. It then performs a search using the username which the user passed to the authentication system, to find the fully-qualified distinguished name (DN) of the LDAP record. A new connection is established, using the DN of the user as the credential, and password supplied by the user. If this authentication to the LDAP server is successful, the DN is verified to be valid.
- connection
- The name of the connection defined in
outbound-connections
to use to connect to the LDAP directory. - advanced-filter
- The fully defined filter used to search for a user based on the supplied user ID. The filter must contain a variable in the following format:
{0}
. This is later replaced with the user name supplied by the user. - base-dn
- The distinguished name of the context to begin searching for the user.
- recursive
- Whether the search should be recursive throughout the LDAP directory tree, or only search the specified context. Defaults to
false
. - user-dn
- The attribute of the user that holds the distinguished name. This is subsequently used to test authentication as the user can complete. Defaults to
dn
. - username-attribute
- The name of the attribute to search for the user. This filter performs a simple search where the user name entered by the user matches the specified attribute.
- allow-empty-passwords
- This attribute determines whether an empty password is accepted. The default value for this attribute is
false
. - Either
username-filter
oradvanced-filter
must be specified - The
advanced-filter
attribute contains a filter query in the standard LDAP syntax, for example:(&(sAMAccountName={0})(memberOf=cn=admin,cn=users,dc=acme,dc=com))
Example 5.11. XML Representing an LDAP-enabled Security Realm
- connection -
ldap_connection
- base-dn -
cn=users,dc=acme,dc=com
. - username-filter -
attribute="sambaAccountName"
<security-realm name="ldap_security_realm"> <authentication> <ldap connection="ldap_connection" base-dn="cn=users,dc=acme,dc=com"> <username-filter attribute="sambaAccountName" /> </ldap> </authentication> </security-realm>
Warning
Example 5.12. Add an LDAP Security Realm
/host=master/core-service=management/security-realm=ldap_security_realm/authentication=ldap:add(base-dn="DC=mycompany,DC=org", recursive=true, username-attribute="MyAccountName", connection="ldap_connection")
After you create a security realm, you need to reference it in the configuration of your management interface. The management interface will use the security realm for HTTP digest authentication.
Example 5.13. Apply the Security Realm to the HTTP Interface
/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=ldap_security_realm)
Example 5.14. Apply the Security Realm to the Native Interface
/host=master/core-service=management/management-interface=native-interface/:write-attribute(name=security-realm,value=ldap_security_realm)
5.11.3. Using Outbound LDAP with 2-way SSL in the Management Interface and CLI
- An LDAP-enabled security realm must be created. See Section 5.11.2, “Use LDAP to Authenticate to the Management Interfaces” for details on creating the security realm.
Procedure 5.4. Configure Outbound LDAP with 2-way SSL
- Configure the security realm keystore and truststore. The security realm must contain a keystore configured with the key that the JBoss EAP 6 server will use to authenticate against the LDAP server. The security realm must also contain a truststore configured with the LDAP server's certificates. See Section 5.9, “Using 2-way SSL for the Management interface and the CLI” for instructions on configuring keystores and truststores.
- Add the outbound connection to the LDAP server, specifying the configured security realm:
/core-service=management/ldap-connection=LocalLdap:add(url="ldaps://LDAP_HOST:LDAP_PORT") /core-service=management/ldap-connection=LocalLdap:write-attribute(name=security-realm,value="LdapSSLRealm")
- Configure LDAP authentication within the security realm and the management interfaces as shown in Section 5.11.2, “Use LDAP to Authenticate to the Management Interfaces”.
Chapter 6. Secure the Management Interfaces with Role-Based Access Control
6.1. About Role-Based Access Control (RBAC)
6.2. Role-Based Access Control in the Management Console and CLI
- The Management Console
- In the management console some controls and views are disabled (greyed out) or not visible at all depending on the permissions of the role to which the user has been assigned.If you do not have read permissions to a resource attribute, that attribute will appear blank in the console. For example, most roles cannot read the username and password fields for datasources.If you do not have write permissions to a resource attribute, that attribute will be disabled (greyed-out) in the edit form for the resource. If you do not have write permissions to the resource, then the edit button for the resource will not appear.If a user does not have permissions to access a resource or attribute (it is "unaddressable" for that role), it will not appear in the console for that user. An example of that is the access control system itself which is only visible to a few roles by default.
- The Management CLI or API
- Users of the Management CLI or management API will encounter slightly different behavior in the API when RBAC is enabled.Resources and attributes that cannot be read are filtered from results. If the filtered items are addressable by the role, their names are listed as
filtered-attributes
in theresponse-headers
section of the result. If a resource or attribute is not addressable by the role, it is not listed.Attempting to access a resource that is not addressable will result in aresource not found
error.If a user attempts to write or read a resource that they can address but lack the appropriate write or read permissions, aPermission Denied
error is returned.
6.3. Supported Authentication Schemes
username/password
, client certificate
, and local user
.
- Username/Password
- Users are authenticated using a username and password combination which is verified against either the
mgmt-users.properties
file, or an LDAP server. - Client Certificate
- Using the Trust Store.
- Local User
jboss-cli.sh
authenticates automatically as Local User if the server that is running on the same machine. By default Local User is a member of theSuperUser
group.
mgmt-users.properties
file or an LDAP server, those systems can supply user group information. This information can also be used by JBoss EAP to assign roles to users.
6.4. The Standard Roles
- Monitor
- Users of the Monitor role have the fewest permissions and can only read the current configuration and state of the server. This role is intended for users who need to track and report on the performance of the server.Monitors cannot modify server configuration nor can they access sensitive data or operations.
- Operator
- The Operator role extends the Monitor role by adding the ability to modify the runtime state of the server. This means that Operators can reload and shutdown the server as well as pause and resume JMS destinations. The Operator role is ideal for users who are responsible for the physical or virtual hosts of the application server so they can ensure that servers can be shutdown and restarted corrected when needed.Operators cannot modify server configuration or access sensitive data or operations.
- Maintainer
- The Maintainer role has access to view and modify runtime state and all configuration except sensitive data and operations. The Maintainer role is the general purpose role that doesn't have access to sensitive data and operation. The Maintainer role allows users to be granted almost complete access to administer the server without giving those users access to passwords and other sensitive information.Maintainers cannot access sensitive data or operations.
- Administrator
- The Administrator role has unrestricted access to all resources and operations on the server except the audit logging system. The Administrator role has access to sensitive data and operations. This role can also configure the access control system. The Administrator role is only required when handling sensitive data or configuring users and roles.Administrators cannot access the audit logging system and cannot change themselves to the Auditor or SuperUser role.
- SuperUser
- The SuperUser role has no restrictions and has complete access to all resources and operations of the server including the audit logging system. This role is equivalent to the administrator users of earlier versions of JBoss EAP 6 (6.0 and 6.1). If RBAC is disabled, all management users have permissions equivalent to the SuperUser role.
- Deployer
- The Deployer role has the same permissions as the Monitor, but can modify configuration and state for deployments and any other resource type enabled as an application resource.
- Auditor
- The Auditor role has all the permissions of the Monitor role and can also view (but not modify) sensitive data, and has full access to the audit logging system. The Auditor role is the only role other than SuperUser that can access the audit logging system.Auditors cannot modify sensitive data or resources. Only read access is permitted.
6.5. About Role Permissions
Monitor
|
Operator
|
Maintainer
|
Deployer
|
Auditor
|
Administrator
|
SuperUser
| |
Read Config and State
|
X
|
X
|
X
|
X
|
X
|
X
|
X
|
Read Sensitive Data [2]
|
X
|
X
|
X
| ||||
Modify Sensitive Data [2]
|
X
|
X
| |||||
Read/Modify Audit Log
|
X
|
X
| |||||
Modify Runtime State
|
X
|
X
|
X[1]
|
X
|
X
| ||
Modify Persistent Config
|
X
|
X[1]
|
X
|
X
| |||
Read/Modify Access Control
|
X
|
X
|
6.6. About Constraints
- Application Constraints
- Application Constraints define sets of resources and attributes that can be accessed by users of the Deployer role. By default the only enabled Application Constraint is core which includes deployments, deployment overlays. Application Constraints are also included (but not enabled by default) for datasources, logging, mail, messaging, naming, resource-adapters and security. These constraints allow Deployer users to not only deploy applications but also configure and maintain the resources that are required by those applications.Application constraint configuration is in the Management API at
/core-service=management/access=authorization/constraint=application-classification
. - Sensitivity Constraints
- Sensitivity Constraints define sets of resources that are considered "sensitive". A sensitive resource is generally one that is either secret, like a password, or one that will have serious impact on the operation of the server, like networking, JVM configuration, or system properties. The access control system itself is also considered sensitive.The only roles permitted to write to sensitive resources are Administrator and SuperUser. The Auditor role is only able to read sensitive resources. No other roles have access.Sensitivity constraint configuration is in the Management API at
/core-service=management/access=authorization/constraint=sensitivity-classification
. - Vault Expression Constraint
- The Vault Expression constraint defines if reading or writing vault expressions is consider a sensitive operation. By default both reading and writing vault expressions is a sensitive operation.Vault Expression constraint configuration is in the Management API at
/core-service=management/access=authorization/constraint=vault-expression
.
6.7. About JMX and Role-Based Access Control
- The Management API of JBoss EAP 6 is exposed as JMX Management Beans. These Management Beans are referred to as "core mbeans" and access to them is controlled and filtered exactly the same as the underlying Management API itself.
- The JMX subsystem is configured with write permissions being "sensitive". This means only users of the Administrator and SuperUser roles can make changes to that subsystem. Users of the Auditor role can also read this subsystem configuration.
- By default Management Beans registered by deployed applications and services (non-core mbeans) can be accessed by all management users, but only users of the Maintainer, Operator, Administrator, SuperUser roles can write to them.
6.8. Configuring Role-Based Access Control
6.8.1. Overview of RBAC Configuration Tasks
- View and configure what roles are assigned to (or excluded from) each user
- View and configure what roles are assigned to (or excluded from) each group
- View group and user membership per role.
- Configure default membership per role.
- Create a scoped role
- Enable and disable RBAC
- Change permission combination policy
- Configuring Application Resource and Resource Sensitivity Constraints
6.8.2. Enabling Role-Based Access Control
simple
to rbac
. This can be done using the Management CLI or by editing the server configuration XML file if the server is offline. When RBAC is disabled or enabled on a running server, the server configuration must be reloaded before it takes effect.
SuperUser
role if it is run on the same machine as the server.
Procedure 6.1. Enabling RBAC
- To enable RBAC with the Management CLI, use the
write-attribute
operation of the access authorization resource to set the provider attribute torbac
./core-service=management/access=authorization:write-attribute(name=provider, value=rbac)
[standalone@localhost:9999 /] /core-service=management/access=authorization:write-attribute(name=provider, value=rbac) { "outcome" => "success", "response-headers" => { "operation-requires-reload" => true, "process-state" => "reload-required" } } [standalone@localhost:9999 /] /:reload { "outcome" => "success", "result" => undefined }
Procedure 6.2. Disabling RBAC
- To disable RBAC with the Management CLI, use the
write-attribute
operation of the access authorization resource to set the provider attribute tosimple
./core-service=management/access=authorization:write-attribute(name=provider, value=simple)
[standalone@localhost:9999 /] /core-service=management/access=authorization:write-attribute(name=provider, value=simple) { "outcome" => "success", "response-headers" => { "operation-requires-reload" => true, "process-state" => "reload-required" } } [standalone@localhost:9999 /] /:reload { "outcome" => "success", "result" => undefined }
provider
attribute of the access-control
element of the management element. Set the value to rbac
to enable, and simple
to disable.
<management> <access-control provider="rbac"> <role-mapping> <role name="SuperUser"> <include> <user name="$local"/> </include> </role> </role-mapping> </access-control> </management>
6.8.3. Changing the Permission Combination Policy
permissive
or rejecting
. The default is permissive
.
permissive
, if any role is assigned to the user that permits an action, then the action is allowed.
rejecting
, if multiple roles are assigned to a user, then no action is allowed. This means that when the policy is set to rejecting
each user should only be assigned one role. Users with multiple roles will not be able to use the Management Console or the Management CLI when the policy is set to rejecting
.
permission-combination-policy
attribute to either permissive
or rejecting
. This can be done using the Management CLI or by editing the server configuration XML file if the server is offline.
Procedure 6.3. Set the Permission Combination Policy
- Use the
write-attribute
operation of the access authorization resource to set thepermission-combination-policy
attribute to the required policy name./core-service=management/access=authorization:write-attribute(name=permission-combination-policy, value=POLICYNAME)
The valid policy names are rejecting and permissive.[standalone@localhost:9999 /] /core-service=management/access=authorization:write-attribute(name=permission-combination-policy, value=rejecting) {"outcome" => "success"} [standalone@localhost:9999 access=authorization]
permission-combination-policy
attribute of the access-control element.
<access-control provider="rbac" permission-combination-policy="rejecting"> <role-mapping> <role name="SuperUser"> <include> <user name="$local"/> </include> </role> </role-mapping> </access-control>
6.9. Managing Roles
6.9.1. About Role Membership
- The user is:
- listed as a user to be included in the role, or
- a member of a group that is listed to be included in the role.
- The user is not:
- listed as a user to exclude from the role, or
- a member of a group that is listed to be excluded from the role.
6.9.2. Configure User Role Assignment
SuperUser
or Administrator
roles can perform this configuration.
- Login to the Management Console.
- Click on thetab.
- Expand the Access Control menu and select .
- Select thetab.
Procedure 6.4. Create a new role assignment for a user
- Login to the Management console.
- Navigate to the Role Assignment section.tab of the
- Click the Add User dialog appears.button at the top right of the user list.
Figure 6.1. Add User Dialog
- Specify user name, and optionally realm.
- Set the type menu to include or exclude.
- Click the checkbox of the roles to include or exclude. To check multiple items, hold down the Control key (Command key on OSX).
- Clickto finish.When successful, the Add User dialog closes, and the list of users is updated to reflect the changes made. If unsuccessful a
Failed to save role assignment
message is displayed.
Procedure 6.5. Update the role assignment for a user
- Login to the Management console.
- Navigate to the Role Assignment section.tab of the
- Select user from the list.
- Click. The selection panel enters edit mode.
Figure 6.2. Selection Edit View
Here you can add and remove assigned and excluded roles for the user.- To add an assigned role, select the required role from the list of available roles on the left and click button with the right-facing arrow next to the assigned roles list. The role moves from the available list to the assigned list.
- To remove an assigned role, selected the required role from the assigned roles list on the right and click the button with the left-facing arrow next to the assigned roles list. The role moves from the assigned list to the available list.
- To add an excluded role, select the required role from the list of available roles on the left and click button with the right-facing arrow next to the excluded roles list. The role moves from the available list to the excluded list.
- To remove an excluded role, selected the required role from the excluded roles list on the right and click the button with the left-facing arrow next to the excluded roles list. The role moves from the excluded list to the available list.
- Clickto finish.When successful, the edit view closes, and the list of users is updated to reflect the changes made. If unsuccessful a
Failed to save role assignment
message is displayed.
Procedure 6.6. Remove role assignment for a user
- Login to the Management console.
- Navigate to thetab of the Role Assignment section.
- Select the user from the list.
- Click Remove Role Assignment confirmation prompt appears.. The
- Click.When successful, the user will no longer appear in the list of user role assignments.
Important
6.9.3. Configure User Role Assignment using the Management CLI
/core-service=management/access=authorization
as role-mapping
elements.
/core-service=management/access=authorization
location:
[standalone@localhost:9999] cd /core-service=management/access=authorization
Procedure 6.7. Viewing Role Assignment Configuration
- Use the :read-children-names operation to get a complete list of the configured roles:
/core-service=management/access=authorization:read-children-names(child-type=role-mapping)
[standalone@localhost:9999 access=authorization] :read-children-names(child-type=role-mapping) { "outcome" => "success", "result" => [ "Administrator", "Deployer", "Maintainer", "Monitor", "Operator", "SuperUser" ] }
- Use the
read-resource
operation of a specified role-mapping to get the full details of a specific role:/core-service=management/access=authorization/role-mapping=ROLENAME:read-resource(recursive=true)
[standalone@localhost:9999 access=authorization] ./role-mapping=Administrator:read-resource(recursive=true) { "outcome" => "success", "result" => { "include-all" => false, "exclude" => undefined, "include" => { "user-theboss" => { "name" => "theboss", "realm" => undefined, "type" => "USER" }, "user-harold" => { "name" => "harold", "realm" => undefined, "type" => "USER" }, "group-SysOps" => { "name" => "SysOps", "realm" => undefined, "type" => "GROUP" } } } } [standalone@localhost:9999 access=authorization]
Procedure 6.8. Add a new role
- Use the
add
operation to add a new role configuration./core-service=management/access=authorization/role-mapping=ROLENAME:add
ROLENAME is the name of the role that the new mapping is for.[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor:add {"outcome" => "success"} [standalone@localhost:9999 access=authorization]
Procedure 6.9. Add a user as included in a role
- Use the
add
operation to add a user entry to the includes list of the role./core-service=management/access=authorization/role-mapping=ROLENAME/include=ALIAS:add(name=USERNAME, type=USER)
ROLENAME is the name of the role being configured.ALIAS
is a unique name for this mapping. Red Hat recommends that you use a naming convention for your aliases such asuser-USERNAME
.USERNAME is the name of the user being added to the include list.[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/include=user-max:add(name=max, type=USER) {"outcome" => "success"} [standalone@localhost:9999 access=authorization]
Procedure 6.10. Add a user as excluded in a role
- Use the
add
operation to add a user entry to the excludes list of the role./core-service=management/access=authorization/role-mapping=ROLENAME/exclude=ALIAS:add(name=USERNAME, type=USER)
ROLENAME is the name of the role being configured.USERNAME is the name of the user being added to the exclude list.ALIAS
is a unique name for this mapping. Red Hat recommends that you use a naming convention for your aliases such asuser-USERNAME
.[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/exclude=user-max:add(name=max, type=USER) {"outcome" => "success"} [standalone@localhost:9999 access=authorization]
Procedure 6.11. Remove user role include configuration
- Use the
remove
operation to remove the entry./core-service=management/access=authorization/role-mapping=ROLENAME/include=ALIAS:remove
ROLENAME is the name of the role being configuredALIAS
is a unique name for this mapping. Red Hat recommends that you use a naming convention for your aliases such asuser-USERNAME
.[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/include=user-max:remove {"outcome" => "success"} [standalone@localhost:9999 access=authorization]
Removing the user from the list of includes does not remove the user from the system, nor does it guarantee that the role won't be assigned to the user. The role might still be assigned based on group membership.
Procedure 6.12. Remove user role exclude configuration
- Use the
remove
operation to remove the entry./core-service=management/access=authorization/role-mapping=ROLENAME/exclude=ALIAS:remove
ROLENAME is the name of the role being configured.ALIAS
is a unique name for this mapping. Red Hat recommends that you use a naming convention for your aliases such asuser-USERNAME
.[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/exclude=user-max:remove {"outcome" => "success"} [standalone@localhost:9999 access=authorization]
Removing the user from the list of excludes does not remove the user from the system, nor does it guarantee the role will be assigned to the user. Roles might still be excluded based on group membership.
6.9.4. About Roles and User Groups
mgmt-users.properties
file or an LDAP server, can be members of user groups. A user group is an arbitrary label that can be assigned to one or more users.
mgmt-users.properties
file, group information is stored in the mgmt-groups.properties
file. When using LDAP the group information is stored in the LDAP sever and maintained by those responsible for the LDAP server.
6.9.5. Configure Group Role Assignment
SuperUser
or Administrator
roles can perform this configuration.
- Login to the Management Console.
- Click on thetab.
- Expand themenu and select .
- Select thetab.
Procedure 6.13. Create a new role assignment for a group
- Login to the Management console
- Navigate to the Role Assignment section.tab of the
- Click the Add Group dialog appears.button at the top right of the user list.
Figure 6.3. Add Group Dialog
- Specify the group name, and optionally the realm.
- Set the type menu to include or exclude.
- Click the checkbox of the roles to include or exclude. To check multiple items, hold down the Control key (Command key on OSX).
- Clickto finish.When successful, the Add Group dialog closes, and the list of groups is updated to reflect the changes made. If unsuccessful a
Failed to save role assignment
message is displayed.
Procedure 6.14. Update a role assignment for a group
- Login to the Management console.
- Navigate to thetab of the Role Assignment section.
- Select the group from the list.
- Click Edit. The Selection view enters Edit mode.
Figure 6.4. Selection View Edit Mode
Here you can add and remove assigned and excluded roles from the group:- To add assigned role, select the required role from the list of available roles on the left and click button with the right-facing arrow next to the assigned roles list. The role moves from the available list to the assigned list.
- To remove an assigned role, selected the required role from the assigned roles list on the right and click the button with the left-facing arrow next to the assigned roles list. The role moves from the assigned list to the available list.
- To add an excluded role, select the required role from the list of available roles on the left and click button with the right-facing arrow next to the excluded roles list. The role moves from the available list to the excluded list.
- To remove an excluded role, selected the required role from the excluded roles list on the right and click the button with the left-facing arrow next to the excluded roles list. The role moves from the excluded list to the available list.
- Clickto finish.When successful, the edit view closes, and the list of groups is updated to reflect the changes made. If unsuccessful amessage is displayed.
Procedure 6.15. Remove role assignment for a group
- Login to the Management console.
- Navigate to thetab of the section.
- Select the group from the list.
- Click Remove Role Assignment confirmation prompt appears.. The
- Click.When successful, the role will no longer appear in the list of group role assignments.Removing the group from the list of role assignments does not remove the user group from the system, nor does it guarantee that no roles will be assigned to members of that group. Each group member might still have a role assigned to them directly.
6.9.6. Configure Group Role Assignment using the Management CLI
/core-service=management/access=authorization
as role-mapping elements.
/core-service=management/access=authorization
location:
[standalone@localhost:9999] cd /core-service=management/access=authorization
Procedure 6.16. Viewing Group Role Assignment Configuration
- Use the
read-children-names
operation to get a complete list of the configured roles:/core-service=management/access=authorization:read-children-names(child-type=role-mapping)
[standalone@localhost:9999 access=authorization] :read-children-names(child-type=role-mapping) { "outcome" => "success", "result" => [ "Administrator", "Deployer", "Maintainer", "Monitor", "Operator", "SuperUser" ] }
- Use the
read-resource
operation of a specified role-mapping to get the full details of a specific role:/core-service=management/access=authorization/role-mapping=ROLENAME:read-resource(recursive=true)
[standalone@localhost:9999 access=authorization] ./role-mapping=Administrator:read-resource(recursive=true) { "outcome" => "success", "result" => { "include-all" => false, "exclude" => undefined, "include" => { "user-theboss" => { "name" => "theboss", "realm" => undefined, "type" => "USER" }, "user-harold" => { "name" => "harold", "realm" => undefined, "type" => "USER" }, "group-SysOps" => { "name" => "SysOps", "realm" => undefined, "type" => "GROUP" } } } } [standalone@localhost:9999 access=authorization]
Procedure 6.17. Add a new role
- Use the
add
operation to add a new role configuration./core-service=management/access=authorization/role-mapping=ROLENAME:add
[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor:add {"outcome" => "success"} [standalone@localhost:9999 access=authorization]
Procedure 6.18. Add a Group as included in a role
- Use the
add
operation to add a Group entry to the includes list of the role./core-service=management/access=authorization/role-mapping=ROLENAME/include=ALIAS:add(name=GROUPNAME, type=GROUP)
ROLENAME is the name of the role being configured.GROUPNAME is the name of the group being added to the include list.ALIAS
is a unique name for this mapping. Red Hat recommends that you use a naming convention for your aliases such asgroup-GROUPNAME
.[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/include=group-investigators:add(name=investigators, type=GROUP) {"outcome" => "success"} [standalone@localhost:9999 access=authorization]
Procedure 6.19. Add a group as excluded in a role
- Use the
add
operation to add a group entry to the excludes list of the role./core-service=management/access=authorization/role-mapping=ROLENAME/exclude=ALIAS:add(name=GROUPNAME, type=GROUP)
ROLENAME is the name of the role being configuredGROUPNAME is the name of the group being added to the include listALIAS
is a unique name for this mapping. Red Hat recommends that you use a naming convention for your aliases such asgroup-GROUPNAME
.[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/exclude=group-supervisors:add(name=supervisors, type=GROUP) {"outcome" => "success"} [standalone@localhost:9999 access=authorization]
Procedure 6.20. Remove group role include configuration
- Use the
remove
operation to remove the entry./core-service=management/access=authorization/role-mapping=ROLENAME/include=ALIAS:remove
ROLENAME is the name of the role being configuredALIAS
is a unique name for this mapping. Red Hat recommends that you use a naming convention for your aliases such asgroup-GROUPNAME
.[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/include=group-investigators:remove {"outcome" => "success"} [standalone@localhost:9999 access=authorization]
Removing the group from the list of includes does not remove the group from the system, nor does it guarantee that the role won't be assigned to users in this group. The role might still be assigned to users in the group individually.
Procedure 6.21. Remove a user group exclude entry
- Use the
remove
operation to remove the entry./core-service=management/access=authorization/role-mapping=ROLENAME/exclude=ALIAS:remove
ROLENAME is the name of the role being configured.ALIAS
is a unique name for this mapping. Red Hat recommends that you use a naming convention for your aliases such asgroup-GROUPNAME
.[standalone@localhost:9999 access=authorization] ./role-mapping=Auditor/exclude=group-supervisors:remove {"outcome" => "success"} [standalone@localhost:9999 access=authorization]
Removing the group from the list of excludes does not remove the group from the system. It also does not guarantee the role will be assigned to members of the group. Roles might still be excluded based on group membership.
6.9.7. About Authorization and Group Loading with LDAP
memberOf
attributes; a group entity may map which users belong to it through uniqueMember
attributes; or both mappings may be maintained by the LDAP server.
force
attribute is set to "false". When force
is true, the search is performed again during authorization (while loading groups). This is typically done when different servers perform authentication and authorization.
<authorization> <ldap connection="..."> <!-- OPTIONAL --> <username-to-dn force="true"> <!-- Only one of the following. --> <username-is-dn /> <username-filter base-dn="..." recursive="..." user-dn-attribute="..." attribute="..." /> <advanced-filter base-dn="..." recursive="..." user-dn-attribute="..." filter="..." /> </username-to-dn> <group-search group-name="..." iterative="..." group-dn-attribute="..." group-name-attribute="..." > <!-- One of the following --> <group-to-principal base-dn="..." recursive="..." search-by="..."> <membership-filter principal-attribute="..." /> </group-to-principal> <principal-to-group group-attribute="..." /> </group-search> </ldap> </authorization>
Important
force
attribute. It is required, even when set to the default value of false
.
username-to-dn
username-to-dn
element specifies how to map the user name to the distinguished name of their entry in the LDAP directory. This element is only required when both of the following are true:
- The authentication and authorization steps are against different LDAP servers.
- The group search uses the distinguished name.
- 1:1 username-to-dn
- This specifies that the user name entered by the remote user is the user's distinguished name.
<username-to-dn force="false"> <username-is-dn /> </username-to-dn>
This defines a 1:1 mapping and there is no additional configuration. - username-filter
- The next option is very similar to the simple option described above for the authentication step. A specified attribute is searched for a match against the supplied user name.
<username-to-dn force="true"> <username-filter base-dn="dc=people,dc=harold,dc=example,dc=com" recursive="false" attribute="sn" user-dn-attribute="dn" /> </username-to-dn>
The attributes that can be set here are:base-dn
: The distinguished name of the context to begin the search.recursive
: Whether the search will extend to sub contexts. Defaults tofalse
.attribute
: The attribute of the users entry to try and match against the supplied user name. Defaults touid
.user-dn-attribute
: The attribute to read to obtain the users distinguished name. Defaults todn
.
- advanced-filter
- The final option is to specify an advanced filter, as in the authentication section this is an opportunity to use a custom filter to locate the users distinguished name.
<username-to-dn force="true"> <advanced-filter base-dn="dc=people,dc=harold,dc=example,dc=com" recursive="false" filter="sAMAccountName={0}" user-dn-attribute="dn" /> </username-to-dn>
For the attributes that match those in the username-filter example, the meaning and default values are the same. There is one new attribute:filter
: Custom filter used to search for a user's entry where the user name will be substituted in the{0}
place holder.
Important
The XML must remain valid after the filter is defined so if any special characters are used such as&
ensure the proper form is used. For example&
for the&
character.
The Group Search
Example 6.1. Principal to Group - LDIF example.
TestUserOne
who is a member of GroupOne
, GroupOne
is in turn a member of GroupFive
. The group membership is shown by the use of a memberOf
attribute which is set to the distinguished name of the group of which the user (or group) is a member.
memberOf
attributes set, one for each group of which the user is directly a member.
dn: uid=TestUserOne,ou=users,dc=principal-to-group,dc=example,dc=org objectClass: extensibleObject objectClass: top objectClass: groupMember objectClass: inetOrgPerson objectClass: uidObject objectClass: person objectClass: organizationalPerson cn: Test User One sn: Test User One uid: TestUserOne distinguishedName: uid=TestUserOne,ou=users,dc=principal-to-group,dc=example,dc=org memberOf: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=org memberOf: uid=Slashy/Group,ou=groups,dc=principal-to-group,dc=example,dc=org userPassword:: e1NTSEF9WFpURzhLVjc4WVZBQUJNbEI3Ym96UVAva0RTNlFNWUpLOTdTMUE9PQ== dn: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=org objectClass: extensibleObject objectClass: top objectClass: groupMember objectClass: group objectClass: uidObject uid: GroupOne distinguishedName: uid=GroupOne,ou=groups,dc=principal-to-group,dc=example,dc=org memberOf: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-to-group,dc=example,dc=org dn: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-to-group,dc=example,dc=org objectClass: extensibleObject objectClass: top objectClass: groupMember objectClass: group objectClass: uidObject uid: GroupFive distinguishedName: uid=GroupFive,ou=subgroups,ou=groups,dc=principal-to-group,dc=example,dc=org
Example 6.2. Group to Principal - LDIF Example
TestUserOne
who is a member of GroupOne
which is in turn a member of GroupFive
- however in this case it is an attribute uniqueMember
from the group to the user being used for the cross reference.
dn: uid=TestUserOne,ou=users,dc=group-to-principal,dc=example,dc=org objectClass: top objectClass: inetOrgPerson objectClass: uidObject objectClass: person objectClass: organizationalPerson cn: Test User One sn: Test User One uid: TestUserOne userPassword:: e1NTSEF9SjR0OTRDR1ltaHc1VVZQOEJvbXhUYjl1dkFVd1lQTmRLSEdzaWc9PQ== dn: uid=GroupOne,ou=groups,dc=group-to-principal,dc=example,dc=org objectClass: top objectClass: groupOfUniqueNames objectClass: uidObject cn: Group One uid: GroupOne uniqueMember: uid=TestUserOne,ou=users,dc=group-to-principal,dc=example,dc=org dn: uid=GroupFive,ou=subgroups,ou=groups,dc=group-to-principal,dc=example,dc=org objectClass: top objectClass: groupOfUniqueNames objectClass: uidObject cn: Group Five uid: GroupFive uniqueMember: uid=TestUserFive,ou=users,dc=group-to-principal,dc=example,dc=org uniqueMember: uid=GroupOne,ou=groups,dc=group-to-principal,dc=example,dc=org
General Group Searching
<group-search group-name="..." iterative="..." group-dn-attribute="..." group-name-attribute="..." > ... </group-search>
group-name
: This attribute is used to specify the form that should be used for the group name returned as the list of groups of which the user is a member. This can either be the simple form of the group name or the group's distinguished name. If the distinguished name is required this attribute can be set toDISTINGUISHED_NAME
. Defaults toSIMPLE
.iterative
: This attribute is used to indicate if, after identifying the groups a user is a member of, we should also iteratively search based on the groups to identify which groups the groups are a member of. If iterative searching is enabled we keep going until either we reach a group that is not a member if any other groups or a cycle is detected. Defaults tofalse
.
Important
group-dn-attribute
: On an entry for a group which attribute is its distinguished name. Defaults todn
.group-name-attribute
: On an entry for a group which attribute is its simple name. Defaults touid
.
Example 6.3. Principal to Group Example Configuration
memberOf
attribute on the user.
<authorization> <ldap connection="LocalLdap"> <username-to-dn> <username-filter base-dn="ou=users,dc=principal-to-group,dc=example,dc=org" recursive="false" attribute="uid" user-dn-attribute="dn" /> </username-to-dn> <group-search group-name="SIMPLE" iterative="true" group-dn-attribute="dn" group-name-attribute="uid"> <principal-to-group group-attribute="memberOf" /> </group-search> </ldap> </authorization>
principal-to-group
element has been added with a single attribute.
group-attribute
: The name of the attribute on the user entry that matches the distinguished name of the group the user is a member of. Defaults tomemberOf
.
Example 6.4. Group to Principal Example Configuration
<authorization> <ldap connection="LocalLdap"> <username-to-dn> <username-filter base-dn="ou=users,dc=group-to-principal,dc=example,dc=org" recursive="false" attribute="uid" user-dn-attribute="dn" /> </username-to-dn> <group-search group-name="SIMPLE" iterative="true" group-dn-attribute="dn" group-name-attribute="uid"> <group-to-principal base-dn="ou=groups,dc=group-to-principal,dc=example,dc=org" recursive="true" search-by="DISTINGUISHED_NAME"> <membership-filter principal-attribute="uniqueMember" /> </group-to-principal> </group-search> </ldap> </authorization>
group-to-principal
is added. This element is used to define how searches for groups that reference the user entry will be performed. The following attributes are set:
base-dn
: The distinguished name of the context to use to begin the search.recursive
: Whether sub-contexts also be searched. Defaults tofalse
.search-by
: The form of the role name used in searches. Valid values areSIMPLE
andDISTINGUISHED_NAME
. Defaults toDISTINGUISHED_NAME
.
principal-attribute
: The name of the attribute on the group entry that references the user entry. Defaults tomember
.
6.9.8. About Scoped Roles
- A unique name.
- Which of the standard roles it is based on.
- If it applies to Server Groups or Hosts
- The list of server groups or hosts that it is restricted to.
- If all users are automatically include. This defaults to false.
- Host-scoped roles
- A role that is host-scoped restricts the permissions of that role to one or more hosts. This means access is provided to the relevant
/host=*/
resource trees but resources that are specific to other hosts are hidden. - Server-Group-scoped roles
- A role that is server-group-scoped restricts the permissions of that role to one or more server groups. Additionally the role permissions will also apply to the profile, socket binding group, server config and server resources that are associated with the specified server-groups. Any sub-resources within any of those that are not logically related to the server-group will not be visible to the user.
6.9.9. Creating Scoped Roles
SuperUser
or Administrator
roles can perform this configuration.
- Login to the Management Console
- Click on thetab
- Expand themenu and select .
- Selecttab, and then the tab within it.
Procedure 6.22. Add a New Scoped Role
- Login to the Management Console
- Navigate to thearea of the tab.
- Click Add Scoped Role dialog appears.. The
- Specify the following details:
- Name, the unique name for the new scoped role.
- Base Role, the role which this role will base its permissions on.
- Type, whether this role will be restricted to hosts or server groups.
- Scope, the list of hosts or server groups that the role is restricted to. Multiple entries can be selected.
- Include All, should this role automatically include all users. Defaults to no.
- Clickand the dialog will close and the newly created role will appear in the table.
Procedure 6.23. Edit a Scoped Role
- Login to the Management Console
- Navigate to thearea of the tab.
- Click on the scoped role you want to edit in the table. The details of that role appears in the Selection panel below the table.
- Click Selection panel. The Selection panel enters edit mode.in the
- Update the details you need to change and click the Selection panel returns to its previous state. Both the Selection panel and table show the newly updated details.button. The
Procedure 6.24. View Scoped Role Members
- Login to the Management Console
- Navigate to the Scoped Roles area of the tab.
- Click on the scoped role in the table that you want to view theof, then click . The dialog appears. It shows users and groups that are included or excluded from the role.
- Clickwhen you have finished reviewing this information.
Procedure 6.25. Delete a Scoped Role
Important
- Login to the Management Console
- Navigate to thearea of the tab.
- Select the scoped role to be removed in the table.
- Click the Remove Scoped Role dialog appears.button. The
- Click.The dialog closes and the role is removed.
6.10. Configuring Constraints
6.10.1. Configure Sensitivity Constraints
/core-service=management/access=authorization/constraint=sensitivity-classification
.
classification
. The classifications are then grouped into types
. There are 39 included classifications that are arranged into 13 types.
write-attribute
operation to set the configured-requires-read
, configured-requires-write
, or configured-requires-addressable
attribute. To make that type of operation sensitive set the value of the attribute to true
, otherwise to make it nonsensitive set it to false
. By default these attributes are not set and the values of default-requires-read
, default-requires-write
, and default-requires-addressable
are used. Once the configured attribute is set it is that value that is used instead of the default. The default values cannot be changed.
Example 6.5. Make reading system properties a sensitive operation
[domain@localhost:9999 /] cd /core-service=management/access=authorization/constraint=sensitivity-classification/type=core/classification=system-property [domain@localhost:9999 classification=system-property] :write-attribute(name=configured-requires-read, value=true) { "outcome" => "success", "result" => undefined, "server-groups" => {"main-server-group" => {"host" => {"master" => { "server-one" => {"response" => {"outcome" => "success"}}, "server-two" => {"response" => {"outcome" => "success"}} }}}} } [domain@localhost:9999 classification=system-property] :read-resource { "outcome" => "success", "result" => { "configured-requires-addressable" => undefined, "configured-requires-read" => true, "configured-requires-write" => undefined, "default-requires-addressable" => false, "default-requires-read" => false, "default-requires-write" => true, "applies-to" => { "/host=master/system-property=*" => undefined, "/host=master/core-service=platform-mbean/type=runtime" => undefined, "/server-group=*/system-property=*" => undefined, "/host=master/server-config=*/system-property=*" => undefined, "/host=master" => undefined, "/system-property=*" => undefined, "/" => undefined } } } [domain@localhost:9999 classification=system-property]
Value | requires-read | requires-write | requires-addressable |
---|---|---|---|
true
|
Read is sensitive.
Only
Auditor , Administrator , SuperUser can read.
|
Write is sensitive.
Only
Administrator and SuperUser can write
|
Addressing is sensitive.
Only
Auditor , Administrator , SuperUser can address.
|
false
|
Read is not sensitive.
Any management user can read.
|
Write is not sensitive.
Only
Maintainer , Administrator and SuperUser can write. Deployers can also write the resource is an application resource.
|
Addressing is not sensitive.
Any management user can address.
|
6.10.2. Configure Application Resource Constraints
/core-service=management/access=authorization/constraint=application-classification/
.
classification
. The classifications are then grouped into types
. There are 14 included classifications that are arranged into 8 types. Each classification has an applies-to
element which is a list of resource path patterns to which the classifications configuration applies.
core
. Core includes deployments, deployment overlays, and the deployment operations.
write-attribute
operation to set the configured-application attribute
of the classification to true
. To disable an Application Resource, set this attribute to false
. By default these attributes are not set and the value of default-application attribute
is used. The default value cannot be changed.
Example 6.6. Enabling the logger-profile application resource classification
[domain@localhost:9999 /] cd /core-service=management/access=authorization/constraint=application-classification/type=logging/classification=logging-profile [domain@localhost:9999 classification=logging-profile] :write-attribute(name=configured-application, value=true) { "outcome" => "success", "result" => undefined, "server-groups" => {"main-server-group" => {"host" => {"master" => { "server-one" => {"response" => {"outcome" => "success"}}, "server-two" => {"response" => {"outcome" => "success"}} }}}} } [domain@localhost:9999 classification=logging-profile] :read-resource { "outcome" => "success", "result" => { "configured-application" => true, "default-application" => false, "applies-to" => {"/profile=*/subsystem=logging/logging-profile=*" => undefined} } } [domain@localhost:9999 classification=logging-profile]
Important
Deployer
user access to one datasource resource but not another. If this level of separation is required then it is recommended to configure the resources in different server groups and create different scoped Deployer
roles for each group.
6.10.3. Configure the Vault Expression Constraint
/core-service=management/access=authorization/constraint=vault-expression
.
write-attribute
operation to set the attributes of configured-requires-write
and configured-requires-read
to true
or false
. By default these are not set and the values of default-requires-read
and default-requires-write
are used. The default values cannot be changed.
Example 6.7. Making writing to vault expressions a nonsensitive operation
[domain@localhost:9999 /] cd /core-service=management/access=authorization/constraint=vault-expression [domain@localhost:9999 constraint=vault-expression] :write-attribute(name=configured-requires-write, value=false) { "outcome" => "success", "result" => undefined, "server-groups" => {"main-server-group" => {"host" => {"master" => { "server-one" => {"response" => {"outcome" => "success"}}, "server-two" => {"response" => {"outcome" => "success"}} }}}} } [domain@localhost:9999 constraint=vault-expression] :read-resource { "outcome" => "success", "result" => { "configured-requires-read" => undefined, "configured-requires-write" => false, "default-requires-read" => true, "default-requires-write" => true } } [domain@localhost:9999 constraint=vault-expression]
Value | requires-read | requires-write |
---|---|---|
true
|
Read operation is sensitive.
Only
Auditor , Administrator , and SuperUser can read.
|
Write operation is sensitive.
Only
Administrator , and SuperUser can write.
|
false
|
Read operation is not sensitive.
All management users can read.
|
Write operation is not sensitive.
Monitor , Administrator , and SuperUser can write. Deployers can also write if the vault expression is in an Application Resource.
|
6.11. Constraints Reference
6.11.1. Application Resource Constraints Reference
Type: core
- Classification: deployment-overlay
- default: true
- PATH: /deployment-overlay=*
- PATH: /deployment=*
- PATH: /Operation:upload-deployment-stream, full-replace-deployment, upload-deployment-url, upload-deployment-bytes
Type: datasources
- Classification: datasource
- default: false
- PATH: /deployment=*/subdeployment=*/subsystem=datasources/data-source=*
- PATH: /subsystem=datasources/data-source=*
- PATH: /subsystem=datasources/data-source=ExampleDS
- PATH: /deployment=*/subsystem=datasources/data-source=*
- Classification: jdbc-driver
- default: false
- PATH: /subsystem=datasources/jdbc-driver=*
- Classification: xa-data-source
- default: false
- PATH: /subsystem=datasources/xa-data-source=*
- PATH: /deployment=*/subsystem=datasources/xa-data-source=*
- PATH: /deployment=*/subdeployment=*/subsystem=datasources/xa-data-source=*
Type: logging
- Classification: logger
- default: false
- PATH: /subsystem=logging/logger=*
- PATH: /subsystem=logging/logging-profile=*/logger=*
- Classification: logging-profile
- default: false
- PATH: /subsystem=logging/logging-profile=*
Type: mail
- Classification: mail-session
- default: false
- PATH: /subsystem=mail/mail-session=*
Type: naming
- Classification: binding
- default: false
- PATH: /subsystem=naming/binding=*
Type: resource-adapters
- Classification: resource-adapters
- default: false
- PATH: /subsystem=resource-adapters/resource-adapter=*
Type: security
- Classification: security-domain
- default: false
- PATH: /subsystem=security/security-domain=*
6.11.2. Sensitivity Constraints Reference
Type: core
- Classification: access-control
- requires-addressable: true
- requires-read: true
- requires-write: true
- PATH: /core-service=management/access=authorization
- PATH: /subsystem=jmx ATTRIBUTE: non-core-mbean-sensitivity
- Classification: credential
- requires-addressable: false
- requires-read: true
- requires-write: true
- PATH: /subsystem=mail/mail-session=*/server=pop3 ATTRIBUTE: username , password
- PATH: /subsystem=mail/mail-session=*/server=imap ATTRIBUTE: username , password
- PATH: /subsystem=datasources/xa-data-source=* ATTRIBUTE: user-name, recovery-username, password, recovery-password
- PATH: /subsystem=mail/mail-session=*/custom=* ATTRIBUTE: username, password
- PATH: /subsystem=datasources/data-source=*" ATTRIBUTE: user-name, password
- PATH: /subsystem=remoting/remote-outbound-connection=*" ATTRIBUTE: username
- PATH: /subsystem=mail/mail-session=*/server=smtp ATTRIBUTE: username, password
- PATH: /subsystem=web/connector=*/configuration=ssl ATTRIBUTE: key-alias, password
- PATH: /subsystem=resource-adapters/resource-adapter=*/connection-definitions=*" ATTRIBUTE: recovery-username, recovery-password
- Classification: domain-controller
- requires-addressable: false
- requires-read: false
- requires-write: true
- Classification: domain-names
- requires-addressable: false
- requires-read: false
- requires-write: true
- Classification: extensions
- requires-addressable: false
- requires-read: false
- requires-write: true
- PATH: /extension=*
- Classification: jvm
- requires-addressable: false
- requires-read: false
- requires-write: true
- PATH: /core-service=platform-mbean/type=runtime ATTRIBUTE: input-arguments, boot-class-path, class-path, boot-class-path-supported, library-path
- Classification: management-interfaces
- requires-addressable: false
- requires-read: false
- requires-write: true
- /core-service=management/management-interface=native-interface
- /core-service=management/management-interface=http-interface
- Classification: module-loading
- requires-addressable: false
- requires-read: false
- requires-write: true
- PATH: /core-service=module-loading
- Classification: patching
- requires-addressable: false
- requires-read: false
- requires-write: true
- PATH: /core-service=patching/addon=*
- PATH: /core-service=patching/layer=*"
- PATH: /core-service=patching
- Classification: read-whole-config
- requires-addressable: false
- requires-read: true
- requires-write: true
- PATH: / OPERATION: read-config-as-xml
- Classification: security-domain
- requires-addressable: true
- requires-read: true
- requires-write: true
- PATH: /subsystem=security/security-domain=*
- Classification: security-domain-ref
- requires-addressable: true
- requires-read: true
- requires-write: true
- PATH: /subsystem=datasources/xa-data-source=* ATTRIBUTE: security-domain
- PATH: /subsystem=datasources/data-source=* ATTRIBUTE: security-domain
- PATH: /subsystem=ejb3 ATTRIBUTE: default-security-domain
- PATH: /subsystem=resource-adapters/resource-adapter=*/connection-definitions=* ATTRIBUTE: security-domain, recovery-security-domain, security-application, security-domain-and-application
- Classification: security-realm
- requires-addressable: true
- requires-read: true
- requires-write: true
- PATH: /core-service=management/security-realm=*
- Classification: security-realm-ref
- requires-addressable: true
- requires-read: true
- requires-write: true
- PATH: /subsystem=remoting/connector=* ATTRIBUTE: security-realm
- PATH: /core-service=management/management-interface=native-interface ATTRIBUTE: security-realm
- PATH: /core-service=management/management-interface=http-interface ATTRIBUTE: security-realm
- PATH: /subsystem=remoting/remote-outbound-connection=* ATTRIBUTE: security-realm
- Classification: security-vault
- requires-addressable: false
- requires-read: false
- requires-write: true
- PATH: /core-service=vault
- Classification: service-container
- requires-addressable: false
- requires-read: false
- requires-write: true
- PATH: /core-service=service-container
- Classification: snapshots
- requires-addressable: false
- requires-read: false
- requires-write: false
- PATH: / ATTRIBUTE: take-snapshot, list-snapshots, delete-snapshot
- Classification: socket-binding-ref
- requires-addressable: false
- requires-read: false
- requires-write: false
- PATH: /subsystem=mail/mail-session=*/server=pop3 ATTRIBUTE: outbound-socket-binding-ref
- PATH: /subsystem=mail/mail-session=*/server=imap ATTRIBUTE: outbound-socket-binding-ref
- PATH: /subsystem=remoting/connector=* ATTRIBUTE: socket-binding
- PATH: /subsystem=web/connector=* ATTRIBUTE: socket-binding
- PATH: /subsystem=remoting/local-outbound-connection=* ATTRIBUTE: outbound-socket-binding-ref
- PATH: /socket-binding-group=*/local-destination-outbound-socket-binding=* ATTRIBUTE: socket-binding-ref
- PATH: /subsystem=remoting/remote-outbound-connection=* ATTRIBUTE: outbound-socket-binding-ref
- PATH: /subsystem=mail/mail-session=*/server=smtp ATTRIBUTE: outbound-socket-binding-ref
- PATH: /subsystem=transactions ATTRIBUTE: process-id-socket-binding, status-socket-binding, socket-binding
- Classification: socket-config
- requires-addressable: false
- requires-read: false
- requires-write: true
- PATH: /interface=* OPERATION: resolve-internet-address
- PATH: /core-service=management/management-interface=native-interface ATTRIBUTE: port, interface, socket-binding
- PATH: /socket-binding-group=*
- PATH: /core-service=management/management-interface=http-interface ATTRIBUTE: port, secure-port, interface, secure-socket-binding, socket-binding
- PATH: / OPERATION: resolve-internet-address
- PATH: /subsystem=transactions ATTRIBUTE: process-id-socket-max-ports
- Classification: system-property
- requires-addressable: false
- requires-read: false
- requires-write: true
- PATH: /core-service=platform-mbean/type=runtime ATTRIBUTE: system-properties
- PATH: /system-property=*
- PATH: / OPERATION: resolve-expression
Type: datasources
- Classification: data-source-security
- requires-addressable: false
- requires-read: true
- requires-write: true
- PATH: /subsystem=datasources/xa-data-source=* ATTRIBUTE: user-name, security-domain, password
- PATH: /subsystem=datasources/data-source=* ATTRIBUTE: user-name, security-domain, password
Type: jdr
- Classification: jdr
- requires-addressable: false
- requires-read: false
- requires-write: true
- PATH: /subsystem=jdr OPERATION: generate-jdr-report
Type: jmx
- Classification: jmx
- requires-addressable: false
- requires-read: false
- requires-write: true
- PATH: /subsystem=jmx
Type: mail
- Classification: mail-server-security
- requires-addressable: false
- requires-read: false
- requires-write: true
- PATH: /subsystem=mail/mail-session=*/server=pop3 ATTRIBUTE: username, tls, ssl, password
- PATH: /subsystem=mail/mail-session=*/server=imap ATTRIBUTE: username, tls, ssl, password
- PATH: /subsystem=mail/mail-session=*/custom=* ATTRIBUTE: username, tls, ssl, password
- PATH: /subsystem=mail/mail-session=*/server=smtp ATTRIBUTE: username, tls, ssl, password
Type: naming
- Classification: jndi-view
- requires-addressable: false
- requires-read: true
- requires-write: true
- PATH: /subsystem=naming OPERATION: jndi-view
- Classification: naming-binding
- requires-addressable: false
- requires-read: false
- requires-write: false
- PATH: /subsystem=naming/binding=*
Type: remoting
- Classification: remoting-security
- requires-addressable: false
- requires-read: true
- requires-write: true
- PATH: /subsystem=remoting/connector=* ATTRIBUTE: authentication-provider, security-realm
- PATH: /subsystem=remoting/remote-outbound-connection=* ATTRIBUTE: username, security-realm
- PATH: /subsystem=remoting/connector=*/security=sasl
Type: resource-adapters
- Classification: resource-adapter-security
- requires-addressable: false
- requires-read: true
- requires-write: true
- PATH: /subsystem=resource-adapters/resource-adapter=*/connection-definitions=* ATTRIBUTE: security-domain, recovery-username, recovery-security-domain, security-application, security-domain-and-application, recovery-password
Type: security
- Classification: misc-security
- requires-addressable: false
- requires-read: true
- requires-write: true
- PATH: /subsystem=security ATTRIBUTE: deep-copy-subject-mode
Type: web
- Classification: web-access-log
- requires-addressable: false
- requires-read: false
- requires-write: false
- PATH: /subsystem=web/virtual-server=*/configuration=access-log
- Classification: web-connector
- requires-addressable: false
- requires-read: false
- requires-write: false
- PATH: /subsystem=web/connector=*
- Classification: web-ssl
- requires-addressable: false
- requires-read: true
- requires-write: true
- PATH: /subsystem=web/connector=*/configuration=ssl
- Classification: web-sso
- requires-addressable: false
- requires-read: true
- requires-write: true
- PATH: /subsystem=web/virtual-server=*/configuration=sso
- Classification: web-valve
- requires-addressable: false
- requires-read: false
- requires-write: false
- PATH: /subsystem=web/valve=*
Chapter 7. Secure Passwords and Other Sensitive Strings with Password Vault
7.1. Password Vault System
7.2. Create a Java Keystore to Store Sensitive Strings
Prerequisites
- The
keytool
command must be available to use. It is provided by the Java Runtime Environment (JRE). Locate the path for the file. In Red Hat Enterprise Linux, it is installed to/usr/bin/keytool
.
Warning
vault.keystore
using the keytool
from the same vendor as the JDK you use.
keytool
from one vendor's JDK in an EAP instance running on a JDK from a different vendor results in the following exception:
java.io.IOException: com.sun.crypto.provider.SealedObjectForKeyProtector
Procedure 7.1. Setup a Java Keystore
Create a directory to store your keystore and other encrypted information.
Create a directory to hold your keystore and other important information. The rest of this procedure assumes that the directory isEAP_HOME/vault/
. Since this directory will contain sensitive information it should be accessible to only limited users. At a minimum the user account under which JBoss EAP is running requires read-write access.Determine the parameters to use with
keytool
.Determine the following parameters:- alias
- The alias is a unique identifier for the vault or other data stored in the keystore. The alias in the example command at the end of this procedure is
vault
. Aliases are case-insensitive. - keyalg
- The algorithm to use for encryption. The example in this procedure uses
AES
. Use the documentation for your JRE and operating system to see which other choices may be available to you. - keysize
- The size of an encryption key impacts how difficult it is to decrypt through brute force. The example in this procedure uses
128
. For information on appropriate values, see the documentation distributed with thekeytool
. - keystore
- The keystore is a database which holds encrypted information and the information about how to decrypt it. If you do not specify a keystore, the default keystore to use is a file called
.keystore
in your home directory. The first time you add data to a keystore, it is created. The example in this procedure uses thevault.keystore
keystore.
Thekeytool
command has many other options. See the documentation for your JRE or your operating system for more details.Determine the answers to questions the
keystore
command will ask.Thekeystore
needs the following information in order to populate the keystore entry:- Keystore password
- When you create a keystore, you must set a password. In order to work with the keystore in the future, you need to provide the password. Create a strong password that you will remember. The keystore is only as secure as its password and the security of the file system and operating system where it resides.
- Key password (optional)
- In addition to the keystore password, you can specify a password for each key it holds. In order to use such a key, the password needs to be given each time it is used. Usually, this facility is not used.
- First name (given name) and last name (surname)
- This, and the rest of the information in the list, helps to uniquely identify the key and place it into a hierarchy of other keys. It does not necessarily need to be a name at all, but it should be two words, and must be unique to the key. The example in this procedure uses
Accounting Administrator
. In directory terms, this becomes the common name of the certificate. - Organizational unit
- This is a single word that identifies who uses the certificate. It may be the application or the business unit. The example in this procedure uses
AccountingServices
. Typically, all keystores used by a group or application use the same organizational unit. - Organization
- This is usually a single-word representation of your organization's name. This typically remains the same across all certificates used by an organization. This example uses
MyOrganization
. - City or municipality
- Your city.
- State or province
- Your state or province, or the equivalent for your locality.
- Country
- The two-letter code for your country.
All of this information together will create a hierarchy for your keystores and certificates, ensuring that they use a consistent naming structure but are unique.Run the
keytool
command, supplying the information that you gathered.Example 7.1. Example input and output of
keystore
command$ keytool -genseckey -alias vault -storetype jceks -keyalg AES -keysize 128 -storepass vault22 -keypass vault22 -validity 730 -keystore
EAP_HOME/vault/
vault.keystore Enter keystore password: vault22 Re-enter new password:vault22 What is your first and last name? [Unknown]:Accounting Administrator
What is the name of your organizational unit? [Unknown]:AccountingServices
What is the name of your organization? [Unknown]:MyOrganization
What is the name of your City or Locality? [Unknown]:Raleigh
What is the name of your State or Province? [Unknown]:NC
What is the two-letter country code for this unit? [Unknown]:US
Is CN=Accounting Administrator, OU=AccountingServices, O=MyOrganization, L=Raleigh, ST=NC, C=US correct? [no]:yes
Enter key password for <vault> (RETURN if same as keystore password):
A file named vault.keystore
is created in the EAP_HOME/vault/
directory. It stores a single key, called vault
, which will be used to store encrypted strings, such as passwords, for JBoss EAP 6.
7.3. Mask the Keystore Password and Initialize the Password Vault
Run the
vault.sh
command.RunEAP_HOME/bin/vault.sh
. Start a new interactive session by typing0
.Enter the directory where encrypted files will be stored.
This directory should be accessible to only limited users. At a minimum the user account under which JBoss EAP is running requires read-write access. If you followed Section 7.2, “Create a Java Keystore to Store Sensitive Strings”, your keystore is in a directory calledEAP_HOME/vault/
.Note
Do not forget to include the trailing slash on the directory name. Either use/
or\
, depending on your operating system.Enter the path to the keystore.
Enter the full path to the keystore file. This example usesEAP_HOME/vault/vault.keystore
.Encrypt the keystore password.
The following steps encrypt the keystore password, so that you can use it in configuration files and applications securely.Enter the keystore password.
When prompted, enter the keystore password.Enter a salt value.
Enter an 8-character salt value. The salt value, together with the iteration count (below), are used to create the hash value.Enter the iteration count.
Enter a number for the iteration count.Make a note of the masked password information.
The masked password, the salt, and the iteration count are printed to standard output. Make a note of them in a secure location. An attacker could use them to decrypt the password.Enter the alias of the vault.
When prompted, enter the alias of the vault. If you followed Section 7.2, “Create a Java Keystore to Store Sensitive Strings” to create your vault, the alias isvault
.
Exit the interactive console.
Type2
to exit the interactive console.
Your keystore password has been masked for use in configuration files and deployments. In addition, your vault is fully configured and ready to use.
7.4. Configure JBoss EAP 6 to Use the Password Vault
Before you can mask passwords and other sensitive attributes in configuration files, you need to make JBoss EAP 6 aware of the password vault which stores and decrypts them. Follow this procedure to enable this functionality.
Prerequisites
Procedure 7.2. Setup a Password Vault
Determine the correct values for the command.
Determine the values for the following parameters, which are determined by the commands used to create the keystore itself. For information on creating a keystore, refer the following topics: Section 7.2, “Create a Java Keystore to Store Sensitive Strings” and Section 7.3, “Mask the Keystore Password and Initialize the Password Vault”.Parameter Description KEYSTORE_URL The file system path or URI of the keystore file, usually called something likevault.keystore
KEYSTORE_PASSWORD The password used to access the keystore. This value should be masked.KEYSTORE_ALIAS The name of the keystore alias.SALT The salt used to encrypt and decrypt keystore values.ITERATION_COUNT The number of times the encryption algorithm is run.ENC_FILE_DIR The path to the directory from which the keystore commands are run. Typically the directory containing the password vault.host (managed domain only) The name of the host you are configuringUse the Management CLI to enable the password vault.
Run one of the following commands, depending on whether you use a managed domain or standalone server configuration. Substitute the values in the command with the ones from the first step of this procedure.Note
If you use Microsoft Windows Server, in the CLI command, escape each\
character in a directory path with an additional\
character. For example,C:\\data\\vault\\vault.keystore
. This is because single\
character is used for character escaping.Managed Domain
/host=YOUR_HOST/core-service=vault:add(vault-options=[("KEYSTORE_URL" => "PATH_TO_KEYSTORE"), ("KEYSTORE_PASSWORD" => "MASKED_PASSWORD"), ("KEYSTORE_ALIAS" => "ALIAS"), ("SALT" => "SALT"),("ITERATION_COUNT" => "ITERATION_COUNT"), ("ENC_FILE_DIR" => "ENC_FILE_DIR")])
Standalone Server
/core-service=vault:add(vault-options=[("KEYSTORE_URL" => "PATH_TO_KEYSTORE"), ("KEYSTORE_PASSWORD" => "MASKED_PASSWORD"), ("KEYSTORE_ALIAS" => "ALIAS"), ("SALT" => "SALT"),("ITERATION_COUNT" => "ITERATION_COUNT"), ("ENC_FILE_DIR" => "ENC_FILE_DIR")])
The following is an example of the command with hypothetical values:/core-service=vault:add(vault-options=[("KEYSTORE_URL" => "/home/user/vault/vault.keystore"), ("KEYSTORE_PASSWORD" => "MASK-3y28rCZlcKR"), ("KEYSTORE_ALIAS" => "vault"), ("SALT" => "12438567"),("ITERATION_COUNT" => "50"), ("ENC_FILE_DIR" => "/home/user/vault/")])
JBoss EAP 6 is configured to decrypt masked strings using the password vault. To add strings to the vault and use them in your configuration, refer to the following topic: Section 7.6, “Store and Retrieve Encrypted Sensitive Strings in the Java Keystore”.
7.5. Configure JBoss EAP 6 to Use a Custom Implementation of the Password Vault
You can use your own implementation of SecurityVault
to mask passwords and other sensitive attributes in configuration files.
Procedure 7.3. Use a Custom Implementation of the Password Vault
- Create a class that implements the interface
SecurityVault
. - Create a module containing the class from the previous step, and specify a dependency on
org.picketbox
where the interface isSecurityVault
. - Enable the custom Password Vault in the JBoss EAP server configuration by adding the vault element with the following attributes:
- code
- The fully qualified name of class that implements
SecurityVault
. - module
- The name of the module that contains the custom class.
Optionally, you can usevault-options
parameters to initialize the custom class for a Password Vault. For example:/core-service=vault:add(code="custom.vault.implementation.CustomSecurityVault", module="custom.vault.module", vault-options=[("KEYSTORE_URL" => "PATH_TO_KEYSTORE"), ("KEYSTORE_PASSWORD" => "MASKED_PASSWORD"), ("KEYSTORE_ALIAS" => "ALIAS"), ("SALT" => "SALT"),("ITERATION_COUNT" => "ITERATION_COUNT"), ("ENC_FILE_DIR" => "ENC_FILE_DIR")])
JBoss EAP 6 is configured to decrypt masked strings using a custom implementation of the password vault.
7.6. Store and Retrieve Encrypted Sensitive Strings in the Java Keystore
Including passwords and other sensitive strings in plain-text configuration files is insecure. JBoss EAP 6 includes the ability to store and mask these sensitive strings in an encrypted keystore, and use masked values in configuration files.
Prerequisites
- The
EAP_HOME/bin/vault.sh
application must be accessible via a command-line interface.
Procedure 7.4. Setup the Java Keystore
Run the
vault.sh
command.RunEAP_HOME/bin/vault.sh
. Start a new interactive session by typing0
.Enter the directory where encrypted files will be stored.
If you followed Section 7.2, “Create a Java Keystore to Store Sensitive Strings”, your keystore is in the directoryEAP_HOME/vault
. In most cases, it makes sense to store all of your encrypted information in the same place as the key store. Since this directory will contain sensitive information it should be accessible to only limited users. At a minimum the user account under which JBoss EAP is running requires read-write access.Note
Do not forget to include the trailing slash on the directory name. Either use/
or\
, depending on your operating system.Enter the path to the keystore.
Enter the full path to the keystore file. This example usesEAP_HOME/vault/vault.keystore
.Enter the keystore password, vault name, salt, and iteration count.
When prompted, enter the keystore password, vault name, salt, and iteration count. A handshake is performed.Select the option to store a password.
Select option0
to store a password or other sensitive string.Enter the value.
When prompted, enter the value twice. If the values do not match, you are prompted to try again.Enter the vault block.
Enter the vault block, which is a container for attributes which pertain to the same resource. An example of an attribute name would beds_ExampleDS
. This will form part of the reference to the encrypted string, in your datasource or other service definition.Enter the attribute name.
Enter the name of the attribute you are storing. An example attribute name would bepassword
.ResultA message such as the one below shows that the attribute has been saved.
Secured attribute value has been stored in vault.
Make note of the information about the encrypted string.
A message prints to standard output, showing the vault block, attribute name, shared key, and advice about using the string in your configuration. Make note of this information in a secure location. Example output is shown below.******************************************** Vault Block:ds_ExampleDS Attribute Name:password Configuration should be done as follows: VAULT::ds_ExampleDS::password::1 ********************************************
Use the encrypted string in your configuration.
Use the string from the previous step in your configuration, in place of a plain-text string. A datasource using the encrypted password above is shown below.... <subsystem xmlns="urn:jboss:domain:datasources:1.0"> <datasources> <datasource jndi-name="java:jboss/datasources/ExampleDS" enabled="true" use-java-context="true" pool-name="H2DS"> <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url> <driver>h2</driver> <pool></pool> <security> <user-name>sa</user-name> <password>${VAULT::ds_ExampleDS::password::1}</password> </security> </datasource> <drivers> <driver name="h2" module="com.h2database.h2"> <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class> </driver> </drivers> </datasources> </subsystem> ...
You can use an encrypted string anywhere in your domain or standalone configuration file where expressions are allowed.Note
To check if expressions are allowed within a particular subsystem, run the following CLI command against that subsystem:/host=master/core-service=management/security-realm=TestRealm:read-resource-description(recursive=true)
From the output of running this command, look for the value for theexpressions-allowed
parameter. If this is true, then you can use expressions within the configuration of this particular subsystem.After you store your string in the keystore, use the following syntax to replace any clear-text string with an encrypted one.${VAULT::VAULT_BLOCK::ATTRIBUTE_NAME::ENCRYPTED_VALUE}
Here is a sample real-world value, where the vault block isds_ExampleDS
and the attribute ispassword
.<password>${VAULT::ds_ExampleDS::password::1}</password>
7.7. Store and Resolve Sensitive Strings In Your Applications
Configuration elements of JBoss EAP 6 support the ability to resolve encrypted strings against values stored in a Java Keystore, via the Security Vault mechanism. You can add support for this feature to your own applications.
Before performing this procedure, make sure that the directory for storing your vault files exists. It does not matter where you place them, as long as the user who executes JBoss EAP 6 has permission to read and write the files. This example places the vault/
directory into the /home/USER/vault/
directory. The vault itself is a file called vault.keystore
inside the vault/
directory.
Example 7.2. Adding the Password String to the Vault
EAP_HOME/bin/vault.sh
command. The full series of commands and responses is included in the following screen output. Values entered by the user are emphasized. Some output is removed for formatting. In Microsoft Windows, the name of the command is vault.bat
. Note that in Microsoft Windows, file paths use the \
character as a directory separator, rather than the /
character.
[user@host bin]$ ./vault.sh ********************************** **** JBoss Vault ******** ********************************** Please enter a Digit:: 0: Start Interactive Session 1: Remove Interactive Session 2: Exit0
Starting an interactive session Enter directory to store encrypted files:/home/user/vault/
Enter Keystore URL:/home/user/vault/vault.keystore
Enter Keystore password:...
Enter Keystore password again:...
Values match Enter 8 character salt:12345678
Enter iteration count as a number (Eg: 44):25
Enter Keystore Alias:vault
Vault is initialized and ready for use Handshake with Vault complete Please enter a Digit:: 0: Store a password 1: Check whether password exists 2: Exit0
Task: Store a password Please enter attribute value:sa
Please enter attribute value again:sa
Values match Enter Vault Block:DS
Enter Attribute Name:thePass
Secured attribute value has been stored in vault. Please make note of the following: ******************************************** Vault Block:DS Attribute Name:thePass Configuration should be done as follows: VAULT::DS::thePass::1 ******************************************** Please enter a Digit:: 0: Store a password 1: Check whether password exists 2: Exit2
VAULT
.
Example 7.3. Servlet Using a Vaulted Password
package vaulterror.web; import java.io.IOException; import java.io.Writer; import javax.annotation.Resource; import javax.annotation.sql.DataSourceDefinition; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import javax.sql.DataSource; /*@DataSourceDefinition( name = "java:jboss/datasources/LoginDS", user = "sa", password = "sa", className = "org.h2.jdbcx.JdbcDataSource", url = "jdbc:h2:tcp://localhost/mem:test" )*/ @DataSourceDefinition( name = "java:jboss/datasources/LoginDS", user = "sa", password = "VAULT::DS::thePass::1", className = "org.h2.jdbcx.JdbcDataSource", url = "jdbc:h2:tcp://localhost/mem:test" ) @WebServlet(name = "MyTestServlet", urlPatterns = { "/my/" }, loadOnStartup = 1) public class MyTestServlet extends HttpServlet { private static final long serialVersionUID = 1L; @Resource(lookup = "java:jboss/datasources/LoginDS") private DataSource ds; @Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { Writer writer = resp.getWriter(); writer.write((ds != null) + ""); } }
Chapter 8. Web, HTTP Connectors, and HTTP Clustering
8.1. Configure a mod_cluster Worker Node
A mod_cluster worker node is an application server that participates in a load-balanced cluster. Requests from users are received by a web server, which then forwards these requests to a pool of mod_cluster worker nodes. A worker node can be part of a server group in a Managed Domain, or a standalone server. For an overview of web server load balancing, refer to Overview of HTTP Connectors in the Administration and Configuration Guide.
mod_cluster
subsystem. To configure the mod_cluster
subsystem, refer to Configure the mod_cluster Subsystem in the Administration and Configuration Guide.
Worker Node Configuration
- A standalone server must be started with the
standalone-ha
orstandalone-full-ha
profile. - A server group in a managed domain must use the
ha
orfull-ha
profile, and theha-sockets
orfull-ha-sockets
socket binding group. JBoss EAP 6 ships with a cluster-enabled server group calledother-server-group
which meets these requirements.
Note
/profile=full-ha
portion of the commands.
Procedure 8.1. Configure a Worker Node
Configure the network interfaces.
By default, the network interfaces all default to127.0.0.1
. Every physical host that hosts either a standalone server or one or more servers in a server group needs its interfaces to be configured to use its public IP address, which the other servers can see.To change the IP address of a JBoss EAP 6 host, you need to shut it down and edit its configuration file directly. This is because the Management API which drives the Management Console and Management CLI relies on a stable management address.Follow these steps to change the IP address on each server in your cluster to the master's public IP address.- Start the JBoss EAP server using the profile described earlier in this topic.
- Launch the Management CLI, using the
EAP_HOME/bin/jboss-cli.sh
command in Linux or theEAP_HOME\bin\jboss-cli.bat
command in Microsoft Windows Server. Typeconnect
to connect to the domain controller on the localhost, orconnect IP_ADDRESS
to connect to a domain controller on a remote server. - Modify the external IP address for the
management
,public
andunsecure
interfaces by typing the following commands. Be sure to replaceEXTERNAL_IP_ADDRESS
in the command with the actual external IP address of the host.
You should see the following result for each command./interface=management:write-attribute(name=inet-address,value="${jboss.bind.address.management:EXTERNAL_IP_ADDRESS}"
/interface=public:write-attribute(name=inet-address,value="${jboss.bind.address.public:EXTERNAL_IP_ADDRESS}"
/interface=unsecure:write-attribute(name=inet-address,value="${jboss.bind.address.unsecure:EXTERNAL_IP_ADDRESS}"
:reload
"outcome" => "success"
- For hosts that participate in a managed domain but are not the master, you must change the host name from
master
to a unique name. This name must be unique across slaves and will be used for the slave to identify to the cluster, so make a note of the name you use.- Start the JBoss EAP slave host using the following syntax:
For example:bin/domain.sh --host-config=HOST_SLAVE_XML_FILE_NAME
bin/domain.sh --host-config=host-slave01.xml
- Launch the Management CLI.
- Use the following syntax to replace the host name:
For example:/host=master:write-attribute(name="name",value=UNIQUE_HOST_SLAVE_NAME)
You should see the following result./host=master:write-attribute(name="name",value="host-slave01")
"outcome" => "success"
This modifies the XML in thehost-slave01.xml
file as follows:<host name="host-slave01" xmlns="urn:jboss:domain:1.6">
- For newly configured hosts that need to join a managed domain, you must remove the
local
element and add theremote
elementhost
attribute that points to the domain controller. This step does not apply for a standalone server.- Start the JBoss EAP slave host using the following syntax:
For example:bin/domain.sh --host-config=HOST_SLAVE_XML_FILE_NAME
bin/domain.sh --host-config=host-slave01.xml
- Launch the Management CLI.
- Use the following syntax specify the domain controller:
For example:/host=UNIQUE_HOST_SLAVE_NAME/:write-remote-domain-controller(host=DOMAIN_CONTROLLER_IP_ADDRESS,port=${jboss.domain.master.port:9999},security-realm="ManagementRealm")
You should see the following result./host=host-slave01/:write-remote-domain-controller(host="192.168.1.200",port=${jboss.domain.master.port:9999},security-realm="ManagementRealm")
"outcome" => "success"
This modifies the XML in thehost-slave01.xml
file as follows:<domain-controller> <remote host="192.168.1.200" port="${jboss.domain.master.port:9999}" security-realm="ManagementRealm"/> </domain-controller>
Configure authentication for each slave server.
Each slave server needs a username and password created in the domain controller's or standalone master'sManagementRealm
. On the domain controller or standalone master, run theEAP_HOME/bin/add-user.sh
command. Add a user with the same username as the slave, to theManagementRealm
. When asked if this user will need to authenticate to an external JBoss AS instance, answeryes
. An example of the input and output of the command is below, for a slave calledslave1
, with passwordchangeme
.user:bin user$ ./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. Realm (ManagementRealm) : Username :slave1
Password :changeme
Re-enter Password :changeme
About to add user 'slave1' for realm 'ManagementRealm' Is this correct yes/no?yes
Added user 'slave1' to file '/home/user/jboss-eap-6.0/standalone/configuration/mgmt-users.properties' Added user 'slave1' to file '/home/user/jboss-eap-6.0/domain/configuration/mgmt-users.properties' Is this new user going to be used for one AS process to connect to another AS process e.g. slave domain controller? yes/no? yes To represent the user add the following to the server-identities definition <secret value="Y2hhbmdlbWU=" />Copy the Base64-encoded
<secret>
element from theadd-user.sh
output.If you plan to specify the Base64-encoded password value for authentication, copy the<secret>
element value from the last line of theadd-user.sh
output as you will need it in the step below.Modify the slave host's security realm to use the new authentication.
You can specify the secret value in one of the following ways:Specify the Base64-encoded password value in the server configuration file using the Management CLI.
- Launch the Management CLI, using the
EAP_HOME/bin/jboss-cli.sh
command in Linux or theEAP_HOME\bin\jboss-cli.bat
command in Microsoft Windows Server. Typeconnect
to connect to the domain controller on the localhost, orconnect IP_ADDRESS
to connect to a domain controller on a remote server. - Specify the secret value by typing the following command. Be sure to replace the
SECRET_VALUE
with the secret value returned from theadd-user
output from the previous step.
You should see the following result for each command./core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="SECRET_VALUE")
:reload
"outcome" => "success"
Configure the host to get the password from the vault.
- Use the
vault.sh
script to generate a masked password. It will generate a string like the following:VAULT::secret::password::ODVmYmJjNGMtZDU2ZC00YmNlLWE4ODMtZjQ1NWNmNDU4ZDc1TElORV9CUkVBS3ZhdWx0
.You can find more information on the vault in the Password Vaults for Sensitive Strings section of this guide starting here: Section 7.1, “Password Vault System”. - Launch the Management CLI, using the
EAP_HOME/bin/jboss-cli.sh
command in Linux or theEAP_HOME\bin\jboss-cli.bat
command in Microsoft Windows Server. Typeconnect
to connect to the domain controller on the localhost, orconnect IP_ADDRESS
to connect to a domain controller on a remote server. - Specify the secret value by typing the following command. Be sure to replace the
SECRET_VALUE
with the masked password generated in the previous step.
You should see the following result for each command./core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="${VAULT::secret::password::SECRET_VALUE}")
:reload
"outcome" => "success"
Note
When creating a password in the vault, it must be specified in plain text, not Base64-encoded.
Specify the password as a system property.
The following examples useserver.identity.password
as the system property name for the password.- Specify the system property for the password in the server configuration file using the Management CLI.
- Launch the Management CLI, using the
EAP_HOME/bin/jboss-cli.sh
command in Linux or theEAP_HOME\bin\jboss-cli.bat
command in Microsoft Windows Server. Typeconnect
to connect to the domain controller on the localhost, orconnect IP_ADDRESS
to connect to a domain controller on a remote server. - Type the following command to configure the secret identity to use the system property.
You should see the following result for each command./core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="${server.identity.password}")
:reload
"outcome" => "success"
- When you specify the password as a system property, you can configure the host in either of the following ways:
- Start the server entering the password in plain text as a command line argument, for example:
-Dserver.identity.password=changeme
Note
The password must be entered in plain text and will be visible to anyone who issues aps -ef
command. - Place the password in a properties file and pass the properties file URL as a command line argument.
- Add the key/value pair to a properties file. For example:
server.identity.password=changeme
- Start the server with the command line arguments
--properties=URL_TO_PROPERTIES_FILE
.
Restart the server.
The slave will now authenticate to the master using its host name as the username and the encrypted string as its password.
Your standalone server, or servers within a server group of a managed domain, are now configured as mod_cluster worker nodes. If you deploy a clustered application, its sessions are replicated to all cluster nodes for failover, and it can accept requests from an external Web server or load balancer. Each node of the cluster discovers the other nodes using automatic discovery, by default.To configure automatic discovery, and the other specific settings of the mod_cluster
subsystem, see Configure the mod_cluster Subsystem in the Administration and Configuration Guide. To configure the Apache HTTP Server, see Use an External Web Server as the Web Front-end for JBoss EAP 6 Applications in the Administration and Configuration Guide.
Chapter 9. Patch Installation
9.1. About Patches and Upgrades
9.2. About Patching Mechanisms
Important
- Asynchronous updates: individual patches which are released outside the normal update cycle of the existing product. These may include security patches, as well as other individual patches provided by Red Hat Global Support Services (GSS) to fix specific issues.
- Planned updates: These include cumulative patches, as well as micro, minor or major upgrades of an existing product. Cumulative patches include all previously developed updates for that version of the product.
Important
EAP_HOME/modules/system/layers/base/.overlays/$PATCH_ID/$MODULE
directory. The original files are left in EAP_HOME/modules/system/layers/base/$MODULE
. The patching mechanism cripples the original jar files for security reasons. This means that if you apply a patch which updates a module, the original module's jar files are altered to be unusable. If the patch is rolled back, the original files will be reverted back to a usable state. This also means that the proper rollback procedure must be used to rollback any applied patch. See Section 9.4.3, “Rollback the Application of a Patch in Zip Form Using the Patch Management System” for the proper rollback procedure.
9.3. Subscribe to Patch Mailing Lists
The JBoss team at Red Hat maintains a mailing list for security announcements for Red Hat JBoss Middleware products. This section covers what you need to do to subscribe to this list.
Prerequisites
- None
Procedure 9.1. Subscribe to the JBoss Watch List
- Click the following link to go to the JBoss Watch mailing list page: JBoss Watch Mailing List.
- Enter your email address in the Subscribing to Jboss-watch-list section.
- [You may also wish to enter your name and select a password. Doing so is optional but recommended.]
- Press thebutton to start the subscription process.
- You can browse the archives of the mailing list by going to: JBoss Watch Mailing List Archives.
After confirmation of your email address, you will be subscribed to receive security related announcements from the JBoss patch mailing list.
9.4. Install Patches in Zip Form
9.4.1. The Patch Management System
patch
command, or through the Management Console. The patch management system cannot be used to automatically patch JBoss EAP 6 server instances across a managed domain, but individual server instances in a managed domain can be patched independently.
Important
Note
patch
command.
Argument or Switch | Description |
---|---|
apply | Applies a patch. |
--override-all | If there is a conflict, the patch operation overrides any user modifications. |
--override-modules | If there is a conflict as a result of any modified modules, this switch overrides those modifications with the contents of the patch operation. |
--override=path(,path) | For specified miscellaneous files only, this will override the conflicting modified files with the files in the patch operation. |
--preserve=path(,path) | For specified miscellaneous files only, this will preserve the conflicting modified files. |
--host=HOST_NAME | Available in domain mode, this specifies the host that the patch operation will be performed on. |
info | Returns information on currently installed patches. |
history | Returns information on the patching history. |
rollback | Rollsback the application of a patch. |
--patch-id=PATCH_ID | Required for rollback, the ID of the patch to rollback. |
--reset-configuration=TRUE|FALSE | Required for rollback, this specifies whether to restore the server configuration files as part of the rollback operation. |
--rollback-to | If the patch to rollback is an individual (one-off) patch, using this argument specifies that the rollback operation will also rollback all other one-off patches that have been applied on top of the specified patch. |
9.4.2. Installing Patches in Zip Form Using the Patch Management System
Patches that are in the zip format can be installed using the JBoss EAP 6 patch management system via either the Management CLI or the Management Console.
Important
Prerequisites
- Valid access and subscription to the Red Hat Customer Portal.
- A current subscription to a JBoss product installed in zip format.
- Access to the Management CLI or the Management Console for the JBoss EAP 6 server to be updated. Refer to Launch the Management CLI or Log in to the Management Console in the Administration and Configuration Guide.
Warning
Procedure 9.2. Apply a zip patch to a JBoss EAP 6 server instance using the Management CLI
- Download the patch zip file from the Customer Portal at https://access.redhat.com/downloads/
- From the Management CLI, apply the patch with the following command including the appropriate path to the patch file:
[standalone@localhost:9999 /]
patch apply /path/to/downloaded-patch.zip
Thepatch
tool will warn if there are any conflicts in attempting the apply the patch. Refer to Section 9.4.1, “The Patch Management System” for availablepatch
command switches to re-run the command to resolve any conflicts. - Restart the JBoss EAP 6 server for the patch to take effect:
[standalone@localhost:9999 /]
shutdown --restart=true
Procedure 9.3. Apply a zip patch to a JBoss EAP 6 server instance using the Management Console
- Download the patch zip file from the Customer Portal at https://access.redhat.com/downloads/
- In the Management Console:
- For a standalone server: click on the Runtime tab at the top of the screen, then click Patch Management.
- For a managed domain: click on the Domain tab at the top of the screen, select the host you want to patch from the Host drop-down menu, then click Patch Management.
- Click.
- If you are patching a managed domain host, on the next screen select whether to shutdown the servers on the host, and click.
- Click thebutton, select the downloaded patch you want to apply, and then click .
- If there are any conflicts in attempting to apply the patch, a warning will be displayed. Click View error details to see the detail of the conflicts. If there is a conflict, you can either cancel the operation, or select the Override all conflicts check box and click . Overriding conflicts will result in the content of the patch overriding any user modifications.
- After the patch has been successfully applied, select whether to restart the JBoss EAP 6 server now for the patch to take effect, and click.
The JBoss EAP 6 server instance is patched with the latest update.
9.4.3. Rollback the Application of a Patch in Zip Form Using the Patch Management System
The JBoss EAP 6 patch management system can be used to rollback the application of a previously applied zip patch, via either the Management CLI or the Management Console.
Warning
Important
Prerequisites
- A patch that was previously applied using the JBoss EAP 6 patch management system.
- Access to the Management CLI or the Management Console for the JBoss EAP 6 server. Refer to Launch the Management CLI or Log in to the Management Console in the Administration and Configuration Guide.
Warning
Reset Configuration
option:
TRUE
, the patch rollback process will also rollback the JBoss EAP 6 server configuration files to their pre-patch state. Any changes that were made to the JBoss EAP 6 server configuration files after the patch was applied will be lost.
FALSE
, the server configuration files will not be rolled back. In this situation, it is possible that the server will not start after the rollback, as the patch may have altered configurations, such as namespaces, which may no longer be valid and have to be fixed manually.
Procedure 9.4. Rollback a patch from a JBoss EAP 6 server instance using the Management CLI
- From the Management CLI, use the
patch info
command to find the ID of the patch that is to be rolled back.- For cumulative patches, the patch ID is the value of the first
cumulative-patch-id
shown in thepatch info
output. - Individual security or bug fix patch IDs are listed as the value of the first
patches
shown in thepatch info
output, with the most recently applied individual patch listed first.
- From the Management CLI, rollback the patch with the appropriate patch ID from the previous step.
[standalone@localhost:9999 /]
patch rollback --patch-id=PATCH_ID --reset-configuration=TRUE
Thepatch
tool will warn if there are any conflicts in attempting the rollback the patch. Refer to Section 9.4.1, “The Patch Management System” for availablepatch
command switches to re-run the command to resolve any conflicts. - Restart the JBoss EAP 6 server for the patch rollback to take effect:
[standalone@localhost:9999 /]
shutdown --restart=true
Procedure 9.5. Rollback a patch from a JBoss EAP 6 server instance using the Management Console
- In the Management Console:
- For a standalone server: click on the Runtime tab at the top of the screen, then click Patch Management.
- For a managed domain: click on the Domain tab at the top of the screen, select the relevant host from the Host drop-down menu, then click Patch Management.
- In the Recent Patch History table, select the patch that you want to rollback, then click .
- For a managed domain host, on the next screen select whether to shutdown the servers on the host, and click.
- Choose your options for the rollback process, then click.
- Confirm the options and the patch to be rolled back, then click.
- If the Override all option was not selected and there are any conflicts in attempting to rollback the patch, a warning will be displayed. Click View error details to see the detail of the conflicts. If there is a conflict, you can either cancel the operation, or click and try the operation again with the Override all check box selected. Overriding conflicts will result in the rollback operation overriding any user modifications.
- After the patch has been successfully rolled back, select whether to restart the JBoss EAP 6 server now for the changes to take effect, and click.
The patch, and optionally also the server configuration files, are rolled back on the JBoss EAP 6 server instance.
9.5. Patching an RPM Installation
JBoss patches are distributed in two forms: ZIP (for all products) and RPM (for a subset of products). This task describes the steps you need to take to install the patches via the RPM format.
Prerequisites
- A valid subscription to the Red Hat Network.
- A current subscription to a JBoss product installed via an RPM package.
Procedure 9.6. Apply a patch to a JBoss product via the RPM method
yum
.
Warning
- Get notified about the security patch either via being a subscriber to the JBoss watch mailing list or by browsing the JBoss watch mailing list archives.
- Read the errata for the security patch and confirm that it applies to a JBoss product in your environment.
- If the security patch applies to a JBoss product in your environment, then follow the link to download the updated RPM package which is included in the errata.
- Use
to install the patch.yum update
Important
When updating an RPM installation, your JBoss product is updated cumulatively with all RPM-released fixes.
The JBoss product is patched with the latest update using the RPM format.
9.6. Severity and Impact Rating of JBoss Security Patches
Severity | Description |
---|---|
Critical |
This rating is given to flaws that could be easily exploited by a remote unauthenticated attacker and lead to system compromise (arbitrary code execution) without requiring user interaction. These are the types of vulnerabilities that can be exploited by worms. Flaws that require an authenticated remote user, a local user, or an unlikely configuration are not classed as critical impact.
|
Important |
This rating is given to flaws that can easily compromise the confidentiality, integrity, or availability of resources. These are the types of vulnerabilities that allow local users to gain privileges, allow unauthenticated remote users to view resources that should otherwise be protected by authentication, allow authenticated remote users to execute arbitrary code, or allow local or remote users to cause a denial of service.
|
Moderate |
This rating is given to flaws that may be more difficult to exploit but could still lead to some compromise of the confidentiality, integrity, or availability of resources, under certain circumstances. These are the types of vulnerabilities that could have had a critical impact or important impact but are less easily exploited based on a technical evaluation of the flaw, or affect unlikely configurations.
|
Low |
This rating is given to all other issues that have a security impact. These are the types of vulnerabilities that are believed to require unlikely circumstances to be able to be exploited, or where a successful exploit would give minimal consequences.
|
Example 9.1. CVSS v2 Impact Score
C:N/I:P/A:C
9.7. Manage Security Updates for Dependencies Bundled Inside the Applications Deployed on JBoss EAP
Tools and Data Sources
- JBoss patch mailing lists
- Subscribing to the JBoss patch mailing lists will keep you informed regarding security flaws that have been fixed in JBoss products, allowing you to check whether your deployed applications are bundling vulnerable versions of the affected components.
- Security advisory page for bundled components.
- Many open source components have their own security advisory page. For example, Struts 2 is a commonly-used component with many known security issues that is not provided as part of the JBoss EAP distribution. The Struts 2 project maintains an upstream security advisory page, which should be monitored if your deployed applications bundle Struts 2. Many commercially-provided components also maintain security advisory pages.
- Regularly scan your deployed applications for known vulnerabilities
- There are several commercial tools available to do this. There is also an open source tool called Victims, which is developed by Red Hat employees, but comes with no support or warranty. Victims provides plugins for several build and integration tools, which automatically scan applications for bundling known-vulnerable dependencies. Plugins are available for Maven, Ant and Jenkins. For more information about the Victims tool, see https://victi.ms/about.html.
Part III. Developing Secure Applications
Chapter 10. Security Overview
10.1. About Application Security
10.2. Declarative Security
10.2.1. Java EE Declarative Security Overview
ejb-jar.xml
and web.xml
deployment descriptors.
10.2.2. Security References
Figure 10.1. Security Roles Reference Model
role-nameType
attribute value as an argument to the isCallerInRole(String)
method. By using the isCallerInRole
method, a component can verify whether the caller is in a role that has been declared with a <security-role-ref> or <role-name> element. The <role-name> element value must link to a <security-role> element through the <role-link> element. The typical use of isCallerInRole
is to perform a security check that cannot be defined by using the role-based <method-permissions> elements.
Example 10.1. ejb-jar.xml descriptor fragment
<!-- A sample ejb-jar.xml fragment --> <ejb-jar> <enterprise-beans> <session> <ejb-name>ASessionBean</ejb-name> ... <security-role-ref> <role-name>TheRoleICheck<role-name> <role-link>TheApplicationRole</role-link> </security-role-ref> </session> </enterprise-beans> ... </ejb-jar>
Note
Example 10.2. web.xml descriptor fragment
<web-app> <servlet> <servlet-name>AServlet</servlet-name> ... <security-role-ref> <role-name>TheServletRole</role-name> <role-link>TheApplicationRole</role-link> </security-role-ref> </servlet> ... </web-app>
10.2.3. Security Identity
Figure 10.2. Java EE Security Identity Data Model
EJBContext.getCallerPrincipal()
method. Rather, the caller's security roles are set to the single role specified by the <run-as> or <role-name> element value.
<ejb-jar> <enterprise-beans> <session> <ejb-name>ASessionBean</ejb-name> <!-- ... --> <security-identity> <use-caller-identity/> </security-identity> </session> <session> <ejb-name>RunAsBean</ejb-name> <!-- ... --> <security-identity> <run-as> <description>A private internal role</description> <role-name>InternalRole</role-name> </run-as> </security-identity> </session> </enterprise-beans> <!-- ... --> </ejb-jar>
anonymous
is assigned to all outgoing calls. If you want another principal to be associated with the call, you must associate a <run-as-principal> with the bean in the jboss-ejb3.xml
file. The following fragment associates a principal named internal
with RunAsBean
from the prior example.
<session> <ejb-name>RunAsBean</ejb-name> <security-identity> <run-as-principal>internal</run-as-principal> </security-identity> </session>
web.xml
file. The following example shows how to assign the role InternalRole
to a servlet:
<servlet> <servlet-name>AServlet</servlet-name> <!-- ... --> <run-as> <role-name>InternalRole</role-name> </run-as> </servlet>
principal
. The <run-as-principal> element is available in the jboss-web.xml
file to assign a specific principal to go along with the run-as
role. The following fragment shows how to associate a principal named internal
to the servlet above.
<servlet> <servlet-name>AServlet</servlet-name> <run-as-principal>internal</run-as-principal> </servlet>
10.2.4. Security Roles
security-role-ref
or security-identity
element needs to map to one of the application's declared roles. An application assembler defines logical security roles by declaring security-role
elements. The role-name
value is a logical application role name like Administrator, Architect, SalesManager, etc.
security-role
element is only used to map security-role-ref/role-name
values to the logical role that the component role references. The user's assigned roles are a dynamic function of the application's security manager. JBoss does not require the definition of security-role
elements in order to declare method permissions. However, the specification of security-role
elements is still a recommended practice to ensure portability across application servers and for deployment descriptor maintenance.
Example 10.3. An ejb-jar.xml descriptor fragment that illustrates the security-role element usage.
<!-- A sample ejb-jar.xml fragment --> <ejb-jar> <assembly-descriptor> <security-role> <description>The single application role</description> <role-name>TheApplicationRole</role-name> </security-role> </assembly-descriptor> </ejb-jar>
Example 10.4. An example web.xml descriptor fragment that illustrates the security-role element usage.
<!-- A sample web.xml fragment --> <web-app> <security-role> <description>The single application role</description> <role-name>TheApplicationRole</role-name> </security-role> </web-app>
10.2.5. EJB Method Permissions
Figure 10.3. Java EE Method Permissions Element
method-permission
element contains one or more role-name child elements that define the logical roles that are allowed to access the EJB methods as identified by method child elements. You can also specify an unchecked
element instead of the role-name
element to declare that any authenticated user can access the methods identified by method child elements. In addition, you can declare that no one should have access to a method that has the exclude-list
element. If an EJB has methods that have not been declared as accessible by a role using a method-permission
element, the EJB methods default to being excluded from use. This is equivalent to defaulting the methods into the exclude-list
.
Figure 10.4. Java EE Method Element
<method> <ejb-name>EJBNAME</ejb-name> <method-name>*</method-name> </method>
<method> <ejb-name>EJBNAME</ejb-name> <method-name>METHOD</method-name> </method>
<method> <ejb-name>EJBNAME</ejb-name> <method-name>METHOD</method-name> <method-params> <method-param>PARAMETER_1</method-param> <!-- ... --> <method-param>PARAMETER_N</method-param> </method-params> </method>
method-intf
element can be used to differentiate methods with the same name and signature that are defined in both the home and remote interfaces of an enterprise bean.
method-permission
element usage.
Example 10.5. An ejb-jar.xml descriptor fragment that illustrates the method-permission element usage.
<ejb-jar> <assembly-descriptor> <method-permission> <description>The employee and temp-employee roles may access any method of the EmployeeService bean </description> <role-name>employee</role-name> <role-name>temp-employee</role-name> <method> <ejb-name>EmployeeService</ejb-name> <method-name>*</method-name> </method> </method-permission> <method-permission> <description>The employee role may access the findByPrimaryKey, getEmployeeInfo, and the updateEmployeeInfo(String) method of the AardvarkPayroll bean </description> <role-name>employee</role-name> <method> <ejb-name>AardvarkPayroll</ejb-name> <method-name>findByPrimaryKey</method-name> </method> <method> <ejb-name>AardvarkPayroll</ejb-name> <method-name>getEmployeeInfo</method-name> </method> <method> <ejb-name>AardvarkPayroll</ejb-name> <method-name>updateEmployeeInfo</method-name> <method-params> <method-param>java.lang.String</method-param> </method-params> </method> </method-permission> <method-permission> <description>The admin role may access any method of the EmployeeServiceAdmin bean </description> <role-name>admin</role-name> <method> <ejb-name>EmployeeServiceAdmin</ejb-name> <method-name>*</method-name> </method> </method-permission> <method-permission> <description>Any authenticated user may access any method of the EmployeeServiceHelp bean</description> <unchecked/> <method> <ejb-name>EmployeeServiceHelp</ejb-name> <method-name>*</method-name> </method> </method-permission> <exclude-list> <description>No fireTheCTO methods of the EmployeeFiring bean may be used in this deployment</description> <method> <ejb-name>EmployeeFiring</ejb-name> <method-name>fireTheCTO</method-name> </method> </exclude-list> </assembly-descriptor> </ejb-jar>
10.2.6. Enterprise Beans Security Annotations
@DeclareRoles
- Declares each security role declared in the code. For information about configuring roles, refer to the Java EE 6 Tutorial Specifying Authorized Users by Declaring Security Roles.
@RolesAllowed
,@PermitAll
, and@DenyAll
- Specifies method permissions for annotations. For information about configuring annotation method permissions, refer to the Java EE 6 Tutorial Specifying Authorized Users by Declaring Security Roles.
@RunAs
- Configures the propagated security identity of a component. For information about configuring propagated security identities using annotations, refer to the Java EE 6 Tutorial Propagating a Security Identity (Run-As).
10.2.7. Web Content Security Constraints
web.xml
security-constraint element.
Figure 10.5. Web Content Security Constraints
NONE
, INTEGRAL
, and CONFIDENTIAL
. A value of NONE
means that the application does not require any transport guarantees. A value of INTEGRAL
means that the application requires the data sent between the client and server to be sent in such a way that it can not be changed in transit. A value of CONFIDENTIAL
means that the application requires the data to be transmitted in a fashion that prevents other entities from observing the contents of the transmission. In most cases, the presence of the INTEGRAL
or CONFIDENTIAL
flag indicates that the use of SSL is required.
Figure 10.6. Web Login Configuration
BASIC
, DIGEST
, FORM
, SPNEGO
, and CLIENT-CERT
. The <realm-name> child element specifies the realm name to use in HTTP basic and digest authorization. The <form-login-config> child element specifies the log in as well as error pages that should be used in form-based log in. If the <auth-method> value is not FORM
, then form-login-config
and its child elements are ignored.
/restricted
path requires an AuthorizedUser
role. There is no required transport guarantee and the authentication method used for obtaining the user identity is BASIC HTTP authentication.
Example 10.6. web.xml Descriptor Fragment
<web-app> <security-constraint> <web-resource-collection> <web-resource-name>Secure Content</web-resource-name> <url-pattern>/restricted/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>AuthorizedUser</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </security-constraint> <!-- ... --> <login-config> <auth-method>BASIC</auth-method> <realm-name>The Restricted Zone</realm-name> </login-config> <!-- ... --> <security-role> <description>The role required to access restricted content </description> <role-name>AuthorizedUser</role-name> </security-role> </web-app>
10.2.8. Enable Form-based Authentication
<auth-method>FORM</auth-method>
in the <login-config> element of the deployment descriptor, web.xml
. The login and error pages are also defined in <login-config>, as follows:
<login-config> <auth-method>FORM</auth-method> <form-login-config> <form-login-page>/login.html</form-login-page> <form-error-page>/error.html</form-error-page> </form-login-config> </login-config>
FormAuthenticator
to direct users to the appropriate page. JBoss EAP maintains a session pool so that authentication information does not need to be present for each request. When FormAuthenticator
receives a request, it queries org.apache.catalina.session.Manager
for an existing session. If no session exists, a new session is created. FormAuthenticator
then verifies the credentials of the session.
Note
/dev/urandom
(Linux) by default, and hashed with MD5. Checks are performed at session ID creation to ensure that the ID created is unique.
JSESSIONID
. Its value is a hex-string of the session ID. This cookie is configured to be non-persistent. This means that on the client side it will be deleted when the browser exits. On the server side, sessions expire after 30 minutes of inactivity, at which time session objects and their credential information are deleted.
FormAuthenticator
caches the request, creates a new session if necessary, and redirects the user to the login page defined in login-config
. (In the previous example code, the login page is login.html
.) The user then enters their user name and password in the HTML form provided. User name and password are passed to FormAuthenticator
via the j_security_check
form action.
FormAuthenticator
then authenticates the user name and password against the realm attached to the web application context. In JBoss Enterprise Application Platform, the realm is JBossWebRealm
. When authentication is successful, FormAuthenticator
retrieves the saved request from the cache and redirects the user to their original request.
Note
/j_security_check
and at least the j_username
and j_password
parameters exist.
10.2.9. Enable Declarative Security
Chapter 11. Application Security
11.1. Datasource Security
11.1.1. About Datasource Security
- Security domains: Section 12.3.3.1, “About Security Domains”.
- Password vaults: Section 7.1, “Password Vault System”.
Example 11.1. Security Domain Example
<security-domain name="DsRealm" cache-type="default"> <authentication> <login-module code="ConfiguredIdentity" flag="required"> <module-option name="userName" value="sa"/> <module-option name="principal" value="sa"/> <module-option name="password" value="sa"/> </login-module> </authentication> </security-domain>
<datasources> <datasource jndi-name="java:jboss/datasources/securityDs" pool-name="securityDs"> <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url> <driver>h2</driver> <new-connection-sql>select current_user()</new-connection-sql> <security> <security-domain>DsRealm</security-domain> </security> </datasource> </datasources>
Example 11.2. Password Vault Example
<security> <user-name>admin</user-name> <password>${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}</password> </security>
11.2. EJB Application Security
11.2.1. Security Identity
11.2.1.1. About EJB Security Identity
11.2.1.2. Set the Security Identity of an EJB
<security-identity>
tag in the security configuration.
<security-identity>
tag is present - the EJB's own caller identity is used.
Example 11.3. Set the security identity of an EJB to be the same as its caller
<security-identity>
element declaration.
<ejb-jar> <enterprise-beans> <session> <ejb-name>ASessionBean</ejb-name> <!-- ... --> <security-identity> <use-caller-identity/> </security-identity> </session> <!-- ... --> </enterprise-beans> </ejb-jar>
Example 11.4. Set the security identity of an EJB to a specific role
<run-as>
and <role-name>
tags inside the <security-identity>
tag.
<ejb-jar> <enterprise-beans> <session> <ejb-name>RunAsBean</ejb-name> <!-- ... --> <security-identity> <run-as> <description>A private internal role</description> <role-name>InternalRole</role-name> </run-as> </security-identity> </session> </enterprise-beans> <!-- ... --> </ejb-jar>
<run-as>
, a principal named anonymous
is assigned to outgoing calls. To assign a different principal, uses the <run-as-principal>
.
<session> <ejb-name>RunAsBean</ejb-name> <security-identity> <run-as-principal>internal</run-as-principal> </security-identity> </session>
Note
<run-as>
and <run-as-principal>
elements inside a servlet element.
See also:
11.2.2. EJB Method Permissions
11.2.2.1. About EJB Method Permissions
<method-permission>
element declaration specifies the roles that can invoke the EJB's interface methods. You can specify permissions for the following combinations:
- All home and component interface methods of the named EJB
- A specified method of the home or component interface of the named EJB
- A specified method within a set of methods with an overloaded name
11.2.2.2. Use EJB Method Permissions
The <method-permission>
element defines the logical roles that are allowed to access the EJB methods defined by <method>
elements. Several examples demonstrate the syntax of the XML. Multiple method permission statements may be present, and they have a cumulative effect. The <method-permission>
element is a child of the <assembly-descriptor>
element of the <ejb-jar>
descriptor.
Example 11.5. Allow roles to access all methods of an EJB
<method-permission> <description>The employee and temp-employee roles may access any method of the EmployeeService bean </description> <role-name>employee</role-name> <role-name>temp-employee</role-name> <method> <ejb-name>EmployeeService</ejb-name> <method-name>*</method-name> </method> </method-permission>
Example 11.6. Allow roles to access only specific methods of an EJB, and limiting which method parameters can be passed.
<method-permission> <description>The employee role may access the findByPrimaryKey, getEmployeeInfo, and the updateEmployeeInfo(String) method of the AcmePayroll bean </description> <role-name>employee</role-name> <method> <ejb-name>AcmePayroll</ejb-name> <method-name>findByPrimaryKey</method-name> </method> <method> <ejb-name>AcmePayroll</ejb-name> <method-name>getEmployeeInfo</method-name> </method> <method> <ejb-name>AcmePayroll</ejb-name> <method-name>updateEmployeeInfo</method-name> <method-params> <method-param>java.lang.String</method-param> </method-params> </method> </method-permission>
Example 11.7. Allow any authenticated user to access methods of EJBs
<unchecked/>
element allows any authenticated user to use the specified methods.
<method-permission> <description>Any authenticated user may access any method of the EmployeeServiceHelp bean</description> <unchecked/> <method> <ejb-name>EmployeeServiceHelp</ejb-name> <method-name>*</method-name> </method> </method-permission>
Example 11.8. Completely exclude specific EJB methods from being used
<exclude-list> <description>No fireTheCTO methods of the EmployeeFiring bean may be used in this deployment</description> <method> <ejb-name>EmployeeFiring</ejb-name> <method-name>fireTheCTO</method-name> </method> </exclude-list>
Example 11.9. A complete <assembly-descriptor>
containing several <method-permission>
blocks
<ejb-jar> <assembly-descriptor> <method-permission> <description>The employee and temp-employee roles may access any method of the EmployeeService bean </description> <role-name>employee</role-name> <role-name>temp-employee</role-name> <method> <ejb-name>EmployeeService</ejb-name> <method-name>*</method-name> </method> </method-permission> <method-permission> <description>The employee role may access the findByPrimaryKey, getEmployeeInfo, and the updateEmployeeInfo(String) method of the AcmePayroll bean </description> <role-name>employee</role-name> <method> <ejb-name>AcmePayroll</ejb-name> <method-name>findByPrimaryKey</method-name> </method> <method> <ejb-name>AcmePayroll</ejb-name> <method-name>getEmployeeInfo</method-name> </method> <method> <ejb-name>AcmePayroll</ejb-name> <method-name>updateEmployeeInfo</method-name> <method-params> <method-param>java.lang.String</method-param> </method-params> </method> </method-permission> <method-permission> <description>The admin role may access any method of the EmployeeServiceAdmin bean </description> <role-name>admin</role-name> <method> <ejb-name>EmployeeServiceAdmin</ejb-name> <method-name>*</method-name> </method> </method-permission> <method-permission> <description>Any authenticated user may access any method of the EmployeeServiceHelp bean</description> <unchecked/> <method> <ejb-name>EmployeeServiceHelp</ejb-name> <method-name>*</method-name> </method> </method-permission> <exclude-list> <description>No fireTheCTO methods of the EmployeeFiring bean may be used in this deployment</description> <method> <ejb-name>EmployeeFiring</ejb-name> <method-name>fireTheCTO</method-name> </method> </exclude-list> </assembly-descriptor> </ejb-jar>
11.2.3. EJB Security Annotations
11.2.3.1. About EJB Security Annotations
javax.annotation.security
annotations are defined in JSR250.
- @DeclareRoles
- Declares which roles are available.
- @RunAs
- Configures the propagated security identity of a component.
11.2.3.2. Use EJB Security Annotations
You can use either XML descriptors or annotations to control which security roles are able to call methods in your Enterprise JavaBeans (EJBs). For information on using XML descriptors, refer to Section 11.2.2.2, “Use EJB Method Permissions”.
Annotations for Controlling Security Permissions of EJBs
- @DeclareRoles
- Use @DeclareRoles to define which security roles to check permissions against. If no @DeclareRoles is present, the list is built automatically from the @RolesAllowed annotation. For information about configuring roles, refer to the Java EE 6 Tutorial Specifying Authorized Users by Declaring Security Roles.
- @RolesAllowed, @PermitAll, @DenyAll
- Use
@RolesAllowed
to list which roles are allowed to access a method or methods. Use@PermitAll
or@DenyAll
to either permit or deny all roles from using a method or methods. For information about configuring annotation method permissions, refer to the Java EE 6 Tutorial Specifying Authorized Users by Declaring Security Roles. - @RunAs
- Use
@RunAs
to specify a role a method uses when making calls from the annotated method. For information about configuring propagated security identities using annotations, refer to the Java EE 6 Tutorial Propagating a Security Identity (Run-As).
Example 11.10. Security Annotations Example
@Stateless @RolesAllowed({"admin"}) @SecurityDomain("other") public class WelcomeEJB implements Welcome { @PermitAll public String WelcomeEveryone(String msg) { return "Welcome to " + msg; } @RunAs("tempemployee") public String GoodBye(String msg) { return "Goodbye, " + msg; } public String GoodbyeAdmin(String msg) { return "See you later, " + msg; } }
WelcomeEveryone
. The GoodBye
method uses the tempemployee
role when making calls. Only the admin
role can access method GoodbyeAdmin
, and any other methods with no security annotation.
11.2.4. Remote Access to EJBs
11.2.4.1. About Remote Method Access
Supported Transport Types
- Socket / Secure Socket
- RMI / RMI over SSL
- HTTP / HTTPS
- Servlet / Secure Servlet
- Bisocket / Secure Bisocket
Warning
The Remoting system also provides data marshalling and unmarshalling services. Data marshalling refers to the ability to safely move data across network and platform boundaries, so that a separate system can perform work on it. The work is then sent back to the original system and behaves as though it were handled locally.
When you design a client application which uses Remoting, you direct your application to communicate with the server by configuring it to use a special type of resource locator called an InvokerLocator
, which is a simple String with a URL-type format. The server listens for requests for remote resources on a connector
, which is configured as part of the remoting
subsystem. The connector
hands the request off to a configured ServerInvocationHandler
. Each ServerInvocationHandler
implements a method invoke(InvocationRequest)
, which knows how to handle the request.
JBoss Remoting Framework Layers
- The user interacts with the outer layer. On the client side, the outer layer is the
Client
class, which sends invocation requests. On the server side, it is the InvocationHandler, which is implemented by the user and receives invocation requests. - The transport is controlled by the invoker layer.
- The lowest layer contains the marshaller and unmarshaller, which convert data formats to wire formats.
11.2.4.2. About Remoting Callbacks
InvocationRequest
to the client. Your server-side code works the same regardless of whether the callback is synchronous or asynchronous. Only the client needs to know the difference. The server's InvocationRequest sends a responseObject
to the client. This is the payload that the client has requested. This may be a direct response to a request or an event notification.
m_listeners
object. It contains a list of all listeners that have been added to your server handler. The ServerInvocationHandler
interface includes methods that allow you to manage this list.
org.jboss.remoting.InvokerCallbackHandler
, which processes the callback data. After implementing the callback handler, you either add yourself as a listener for a pull callback, or implement a callback server for a push callback.
For a pull callback, your client adds itself to the server's list of listeners using the Client.addListener()
method. It then polls the server periodically for synchronous delivery of callback data. This poll is performed using the Client.getCallbacks()
.
A push callback requires your client application to run its own InvocationHandler. To do this, you need to run a Remoting service on the client itself. This is referred to as a callback server. The callback server accepts incoming requests asynchronously and processes them for the requester (in this case, the server). To register your client's callback server with the main server, pass the callback server's InvokerLocator
as the second argument to the addListener
method.
11.2.4.3. About Remoting Server Detection
11.2.4.4. Configure the Remoting Subsystem
JBoss Remoting has three top-level configurable elements: the worker thread pool, one or more connectors, and a series of local and remote connection URIs. This topic presents an explanation of each configurable item, example CLI commands for how to configure each item, and an XML example of a fully-configured subsystem. This configuration only applies to the server. Most people will not need to configure the Remoting subsystem at all, unless they use custom connectors for their own applications. Applications which act as Remoting clients, such as EJBs, need separate configuration to connect to a specific connector.
Note
The CLI commands are formulated for a managed domain, when configuring the default
profile. To configure a different profile, substitute its name. For a standalone server, omit the /profile=default
part of the command.
There are a few configuration aspects which are outside of the remoting
subsystem:
- Network Interface
- The network interface used by the
remoting
subsystem is theunsecure
interface defined in thedomain/configuration/domain.xml
orstandalone/configuration/standalone.xml
.<interfaces> <interface name="management"/> <interface name="public"/> <interface name="unsecure"/> </interfaces>
The per-host definition of theunsecure
interface is defined in thehost.xml
in the same directory as thedomain.xml
orstandalone.xml
. This interface is also used by several other subsystems. Exercise caution when modifying it.<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> <interface name="unsecure"> <!-- Used for IIOP sockets in the standard configuration. To secure JacORB you need to setup SSL --> <inet-address value="${jboss.bind.address.unsecure:127.0.0.1}"/> </interface> </interfaces>
- socket-binding
- The default socket-binding used by the
remoting
subsystem binds to TCP port 4777. Refer to the documentation about socket bindings and socket binding groups for more information if you need to change this. - Remoting Connector Reference for EJB
- The EJB subsystem contains a reference to the remoting connector for remote method invocations. The following is the default configuration:
<remote connector-ref="remoting-connector" thread-pool-name="default"/>
- Secure Transport Configuration
- Remoting transports use StartTLS to use a secure (HTTPS, Secure Servlet, etc) connection if the client requests it. The same socket binding (network port) is used for secured and unsecured connections, so no additional server-side configuration is necessary. The client requests the secure or unsecured transport, as its needs dictate. JBoss EAP 6 components which use Remoting, such as EJBs, the ORB, and the JMS provider, request secured interfaces by default.
Warning
The worker thread pool is the group of threads which are available to process work which comes in through the Remoting connectors. It is a single element <worker-thread-pool>
, and takes several attributes. Tune these attributes if you get network timeouts, run out of threads, or need to limit memory usage. Specific recommendations depend on your specific situation. Contact Red Hat Global Support Services for more information.
Attribute | Description | CLI Command |
---|---|---|
read-threads |
The number of read threads to create for the remoting worker. Defaults to
1 .
| /profile=default/subsystem=remoting/:write-attribute(name=worker-read-threads,value=1)
|
write-threads |
The number of write threads to create for the remoting worker. Defaults to
1 .
| /profile=default/subsystem=remoting/:write-attribute(name=worker-write-threads,value=1)
|
task-keepalive |
The number of milliseconds to keep non-core remoting worker task threads alive. Defaults to
60 .
| /profile=default/subsystem=remoting/:write-attribute(name=worker-task-keepalive,value=60)
|
task-max-threads |
The maximum number of threads for the remoting worker task thread pool. Defaults to
16 .
| /profile=default/subsystem=remoting/:write-attribute(name=worker-task-max-threads,value=16)
|
task-core-threads |
The number of core threads for the remoting worker task thread pool. Defaults to
4 .
| /profile=default/subsystem=remoting/:write-attribute(name=worker-task-core-threads,value=4)
|
task-limit |
The maximum number of remoting worker tasks to allow before rejecting. Defaults to
16384 .
| /profile=default/subsystem=remoting/:write-attribute(name=worker-task-limit,value=16384)
|
The connector is the main Remoting configuration element. Multiple connectors are allowed. Each consists of a element <connector>
element with several sub-elements, as well as a few possible attributes. The default connector is used by several subsystems of JBoss EAP 6. Specific settings for the elements and attributes of your custom connectors depend on your applications, so contact Red Hat Global Support Services for more information.
Attribute | Description | CLI Command |
---|---|---|
socket-binding | The name of the socket binding to use for this connector. | /profile=default/subsystem=remoting/connector=remoting-connector/:write-attribute(name=socket-binding,value=remoting)
|
authentication-provider |
The Java Authentication Service Provider Interface for Containers (JASPIC) module to use with this connector. The module must be in the classpath.
| /profile=default/subsystem=remoting/connector=remoting-connector/:write-attribute(name=authentication-provider,value=myProvider)
|
security-realm |
Optional. The security realm which contains your application's users, passwords, and roles. An EJB or Web Application can authenticate against a security realm.
ApplicationRealm is available in a default JBoss EAP 6 installation.
| /profile=default/subsystem=remoting/connector=remoting-connector/:write-attribute(name=security-realm,value=ApplicationRealm)
|
Attribute | Description | CLI Command |
---|---|---|
sasl |
Enclosing element for Simple Authentication and Security Layer (SASL) authentication mechanisms
| N/A
|
properties |
Contains one or more
<property> elements, each with a name attribute and an optional value attribute.
| /profile=default/subsystem=remoting/connector=remoting-connector/property=myProp/:add(value=myPropValue)
|
You can specify three different types of outbound connection:
- Outbound connection to a URI.
- Local outbound connection – connects to a local resource such as a socket.
- Remote outbound connection – connects to a remote resource and authenticates using a security realm.
<outbound-connections>
element. Each of these connection types takes an outbound-socket-binding-ref
attribute. The outbound-connection takes a uri
attribute. The remote outbound connection takes optional username
and security-realm
attributes to use for authorization.
Attribute | Description | CLI Command |
---|---|---|
outbound-connection | Generic outbound connection. | /profile=default/subsystem=remoting/outbound-connection=my-connection/:add(uri=http://my-connection)
|
local-outbound-connection | Outbound connection with a implicit local:// URI scheme. | /profile=default/subsystem=remoting/local-outbound-connection=my-connection/:add(outbound-socket-binding-ref=remoting2)
|
remote-outbound-connection |
Outbound connections for remote:// URI scheme, using basic/digest authentication with a security realm.
| /profile=default/subsystem=remoting/remote-outbound-connection=my-connection/:add(outbound-socket-binding-ref=remoting,username=myUser,security-realm=ApplicationRealm)
|
Before defining the SASL child elements, you need to create the initial SASL element. Use the following command:
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:add
Attribute | Description | CLI Command |
---|---|---|
include-mechanisms |
Contains a
value attribute, which is a space-separated list of SASL mechanisms.
|
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=include-mechanisms,value=["DIGEST","PLAIN","GSSAPI"]) |
qop |
Contains a
value attribute, which is a space-separated list of SASL Quality of protection values, in decreasing order of preference.
|
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=qop,value=["auth"]) |
strength |
Contains a
value attribute, which is a space-separated list of SASL cipher strength values, in decreasing order of preference.
|
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=strength,value=["medium"]) |
reuse-session |
Contains a
value attribute which is a boolean value. If true, attempt to reuse sessions.
|
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=reuse-session,value=false) |
server-auth |
Contains a
value attribute which is a boolean value. If true, the server authenticates to the client.
|
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=server-auth,value=false) |
policy |
An enclosing element which contains zero or more of the following elements, which each take a single
value .
|
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:add /profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=forward-secrecy,value=true) /profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=no-active,value=false) /profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=no-anonymous,value=false) /profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=no-dictionary,value=true) /profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=no-plain-text,value=false) /profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=pass-credentials,value=true) |
properties |
Contains one or more
<property> elements, each with a name attribute and an optional value attribute.
|
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/property=myprop:add(value=1) /profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/property=myprop2:add(value=2) |
Example 11.11. Example Configurations
<subsystem xmlns="urn:jboss:domain:remoting:1.1"> <connector name="remoting-connector" socket-binding="remoting" security-realm="ApplicationRealm"/> </subsystem>
<subsystem xmlns="urn:jboss:domain:remoting:1.1"> <worker-thread-pool read-threads="1" task-keepalive="60" task-max-threads="16" task-core-thread="4" task-limit="16384" write-threads="1" /> <connector name="remoting-connector" socket-binding="remoting" security-realm="ApplicationRealm"> <sasl> <include-mechanisms value="GSSAPI PLAIN DIGEST-MD5" /> <qop value="auth" /> <strength value="medium" /> <reuse-session value="false" /> <server-auth value="false" /> <policy> <forward-secrecy value="true" /> <no-active value="false" /> <no-anonymous value="false" /> <no-dictionary value="true" /> <no-plain-text value="false" /> <pass-credentials value="true" /> </policy> <properties> <property name="myprop1" value="1" /> <property name="myprop2" value="2" /> </properties> </sasl> <authentication-provider name="myprovider" /> <properties> <property name="myprop3" value="propValue" /> </properties> </connector> <outbound-connections> <outbound-connection name="my-outbound-connection" uri="http://myhost:7777/"/> <remote-outbound-connection name="my-remote-connection" outbound-socket-binding-ref="my-remote-socket" username="myUser" security-realm="ApplicationRealm"/> <local-outbound-connection name="myLocalConnection" outbound-socket-binding-ref="my-outbound-socket"/> </outbound-connections> </subsystem>
Configuration Aspects Not Yet Documented
- JNDI and Multicast Automatic Detection
11.2.4.5. Use Security Realms with Remote EJB Clients
- Add a new security realm to the domain controller or standalone server.
- Add the following parameters to the
jboss-ejb-client.properties
file, which is in the classpath of the application. This example assumes the connection is referred to asdefault
by the other parameters in the file.remote.connection.default.username=appuser remote.connection.default.password=apppassword
- Create a custom Remoting connector on the domain or standalone server, which uses your new security realm.
- Deploy your EJB to the server group which is configured to use the profile with the custom Remoting connector, or to your standalone server if you are not using a managed domain.
11.2.4.6. Add a New Security Realm
Run the Management CLI.
Start thejboss-cli.sh
orjboss-cli.bat
command and connect to the server.Create the new security realm itself.
Run the following command to create a new security realm namedMyDomainRealm
on a domain controller or a standalone server.For a domain instance, use this command:/host=master/core-service=management/security-realm=MyDomainRealm:add()
For a standalone instance, use this command:/core-service=management/security-realm=MyDomainRealm:add()
Create the references to the properties file which will store information about the new role.
Run the following command to create a pointer a file namedmyfile.properties
, which will contain the properties pertaining to the new role.Note
The newly created properties file is not managed by the includedadd-user.sh
andadd-user.bat
scripts. It must be managed externally.For a domain instance, use this command:/host=master/core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path=myfile.properties)
For a standalone instance, use this command:/core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path=myfile.properties)
Your new security realm is created. When you add users and roles to this new realm, the information will be stored in a separate file from the default security realms. You can manage this new file using your own applications or procedures.
11.2.4.7. Add a User to a Security Realm
Run the
add-user.sh
oradd-user.bat
command.Open a terminal and change directories to theEAP_HOME/bin/
directory. If you run Red Hat Enterprise Linux or another UNIX-like operating system, runadd-user.sh
. If you run Microsoft Windows Server, runadd-user.bat
.Choose whether to add a Management User or Application User.
For this procedure, typeb
to add an Application User.Choose the realm the user will be added to.
By default, the only available realm isApplicationRealm
. If you have added a custom realm, you can type its name instead.Type the username, password, and roles, when prompted.
Type the desired username, password, and optional roles when prompted. Verify your choice by typingyes
, or typeno
to cancel the changes. The changes are written to each of the properties files for the security realm.
11.2.4.8. About Remote EJB Access Using SSL Encryption
Warning
11.3. JAX-RS Application Security
11.3.1. Enable Role-Based Security for a RESTEasy JAX-RS Web Service
RESTEasy supports the @RolesAllowed, @PermitAll, and @DenyAll annotations on JAX-RS methods. However, it does not recognize these annotations by default. Follow these steps to configure the web.xml
file and enable role-based security.
Warning
Procedure 11.1. Enable Role-Based Security for a RESTEasy JAX-RS Web Service
- Open the
web.xml
file for the application in a text editor. - Add the following <context-param> to the file, within the
web-app
tags:<context-param> <param-name>resteasy.role.based.security</param-name> <param-value>true</param-value> </context-param>
- Declare all roles used within the RESTEasy JAX-RS WAR file, using the <security-role> tags:
<security-role> <role-name>ROLE_NAME</role-name> </security-role> <security-role> <role-name>ROLE_NAME</role-name> </security-role>
- Authorize access to all URLs handled by the JAX-RS runtime for all roles:
<security-constraint> <web-resource-collection> <web-resource-name>Resteasy</web-resource-name> <url-pattern>/PATH</url-pattern> </web-resource-collection> <auth-constraint> <role-name>ROLE_NAME</role-name> <role-name>ROLE_NAME</role-name> </auth-constraint> </security-constraint>
Role-based security has been enabled within the application, with a set of defined roles.
Example 11.12. Example Role-Based Security Configuration
<web-app> <context-param> <param-name>resteasy.role.based.security</param-name> <param-value>true</param-value> </context-param> <servlet-mapping> <servlet-name>Resteasy</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> <security-constraint> <web-resource-collection> <web-resource-name>Resteasy</web-resource-name> <url-pattern>/security</url-pattern> </web-resource-collection> <auth-constraint> <role-name>admin</role-name> <role-name>user</role-name> </auth-constraint> </security-constraint> <security-role> <role-name>admin</role-name> </security-role> <security-role> <role-name>user</role-name> </security-role> </web-app>
11.3.2. Secure a JAX-RS Web Service using Annotations
This topic covers the steps to secure a JAX-RS web service using the supported security annotations
Procedure 11.2. Secure a JAX-RS Web Service using Supported Security Annotations
- Enable role-based security. For more information, refer to: Section 11.3.1, “Enable Role-Based Security for a RESTEasy JAX-RS Web Service”
- Add security annotations to the JAX-RS web service. RESTEasy supports the following annotations:
- @RolesAllowed
- Defines which roles can access the method. All roles should be defined in the
web.xml
file. - @PermitAll
- Allows all roles defined in the
web.xml
file to access the method. - @DenyAll
- Denies all access to the method.
Chapter 12. The Security Subsystem
12.1. About the Security Subsystem
security
subsystem provides security infrastructure for applications. The subsystem uses a security context associated with the current request to expose the capabilities of the authentication manager, authorization manager, audit manager, and mapping manager to the relevant container.
security
subsystem is preconfigured by default, so security elements rarely need to be changed. The only security element that may need to be changed is whether to use deep-copy-subject-mode. In most cases, administrators will focus on the configuration of security domains.
See Section 12.3.2.1, “About Deep Copy Subject Mode” for details about deep copy subject mode.
A security domain is a set of Java Authentication and Authorization Service (JAAS) declarative security configurations which one or more applications use to control authentication, authorization, auditing, and mapping. Three security domains are included by default: jboss-ejb-policy
, jboss-web-policy
, and other
. You can create as many security domains as you need to accommodate your application requirements. See Section 13.9, “Use a Security Domain in Your Application” for details about security domain.
12.2. About the Structure of the Security Subsystem
Example 12.1. Example Security Subsystem Configuration
<subsystem xmlns="urn:jboss:domain:security:1.2"> <security-management> ... </security-management> <security-domains> <security-domain name="other" cache-type="default"> <authentication> <login-module code="Remoting" flag="optional"> <module-option name="password-stacking" value="useFirstPass"/> </login-module> <login-module code="RealmUsersRoles" flag="required"> <module-option name="usersProperties" value="${jboss.domain.config.dir}/application-users.properties"/> <module-option name="rolesProperties" value="${jboss.domain.config.dir}/application-roles.properties"/> <module-option name="realm" value="ApplicationRealm"/> <module-option name="password-stacking" value="useFirstPass"/> </login-module> </authentication> </security-domain> <security-domain name="jboss-web-policy" cache-type="default"> <authorization> <policy-module code="Delegating" flag="required"/> </authorization> </security-domain> <security-domain name="jboss-ejb-policy" cache-type="default"> <authorization> <policy-module code="Delegating" flag="required"/> </authorization> </security-domain> </security-domains> <vault> ... </vault> </subsystem>
<security-management>
, <subject-factory>
and <security-properties>
elements are not present in the default configuration. The <subject-factory>
and <security-properties>
elements have been deprecated in JBoss EAP 6.1 onwards.
12.3. Configuring the Security Subsystem
12.3.1. Configure the Security Subsystem
- <security-management>
- This section overrides high-level behaviors of the security subsystem. It contains an optional setting
deep-copy-subject-mode
, that specifies whether to copy or link to security tokens, for additional thread safety. - <security-domains>
- A container element which holds multiple security domains. A security domain may contain information about authentication, authorization, mapping, and auditing modules, as well as JASPI authentication and JSSE configuration. Your application would specify a security domain to manage its security information.
- <security-properties>
- Contains names and values of properties which are set on the java.security.Security class.
12.3.2. Security Management
12.3.2.1. About Deep Copy Subject Mode
12.3.2.2. Enable Deep Copy Subject Mode
Procedure 12.1. Enable Deep Copy Security Mode from the Management Console
Log into the Management Console.
For detailed instructions, see the section entitled The Management Console in the Administration and Configuration Guide for JBoss Enterprise Application Platform 6.x located on the Customer Portal at https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.Managed Domain: Select the appropriate profile.
In a managed domain, the security subsystem is configured per profile, and you can enable or disable the deep copy security mode independently in each profile.To select a profile, click Configuration at the top of the screen, and then select a profile from the Profile drop down box at the top left.Open the Security Subsystem configuration menu.
Expand the Security menu, then select Security Subsystem.Enable Deep Copy Subject mode.
Click Deep Copy Subjects to enable deep copy subject mode.. Check the box beside
If you prefer to use the management CLI to enable this option, use one of the following commands.
Example 12.2. Managed Domain
/profile=full/subsystem=security/:write-attribute(name=deep-copy-subject-mode,value=TRUE)
Example 12.3. Standalone Server
/subsystem=security/:write-attribute(name=deep-copy-subject-mode,value=TRUE)
12.3.3. Security Domains
12.3.3.1. About Security Domains
12.3.3.2. CLI Operations Related to Security Domains
Example 12.4. flush-cache
/subsystem=security/security-domain=other:read-operation-description(name=flush-cache)
Example 12.5. list-cached-principals
/subsystem=security/security-domain=other:read-operation-description(name=list-cached-principals)
Chapter 13. Authentication and Authorization
13.1. Kerberos and SPNEGO Integration
13.1.1. About Kerberos and SPNEGO Integration
In a typical setup, the user logs into a desktop which is governed by the Active Directory domain. The user then uses the web browser, either Firebox or Internet Explorer, to access a web application that uses JBoss Negotiation hosted on the JBoss EAP. The web browser transfers the desktop sign on information to the web application. JBoss EAP uses background GSS messages with the Active Directory or any Kerberos Server to validate the user. This enables the user to achieve a seamless SSO into the web application.
13.1.2. Desktop SSO using SPNEGO
- Security Domain
- System Properties
- Web Application
Procedure 13.1. Configure Desktop SSO using SPNEGO
Configure Security Domain
Configure the security domains to represent the identity of the server and to secure the web application.Example 13.1. Security Domain Configuration
<security-domains> <security-domain name="host" cache-type="default"> <authentication> <login-module code="Kerberos" flag="required"> <module-option name="storeKey" value="true"/> <module-option name="useKeyTab" value="true"/> <module-option name="principal" value="host/testserver@MY_REALM"/> <module-option name="keyTab" value="/home/username/service.keytab"/> <module-option name="doNotPrompt" value="true"/> <module-option name="debug" value="false"/> </login-module> </authentication> </security-domain> <security-domain name="SPNEGO" cache-type="default"> <authentication> <login-module code="SPNEGO" flag="requisite"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="serverSecurityDomain" value="host"/> </login-module> <!-- Login Module For Roles Search --> </security-domain>
Setup the System Properties
If required, the system properties can be set in the domain model.Example 13.2. Configure System Properties
<system-properties> <property name="java.security.krb5.kdc" value="mykdc.mydomain"/> <property name="java.security.krb5.realm" value="MY_REALM"/> </system-properties>
Configure Web Application
It is not possible to override the authenticators, but it is possible to add theNegotiationAuthenticator
as a valve to your jboss-web.xml descriptor to configure the web application.Note
The valve requires thesecurity-constraint
andlogin-config
to be defined in the web.xml file as this is used to decide which resources are secured. However, the chosenauth-method
is overridden by this authenticator.Example 13.3. Configure Web Application
<!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 2.4//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_4_0.dtd"> <jboss-web> <security-domain>SPNEGO</security-domain> <valve> <class-name>org.jboss.security.negotiation.NegotiationAuthenticator</class-name> </valve> </jboss-web>
The web application also requires a dependency defining inMETA-INF/MANIFEST.MF
so that the JBoss Negotiation classes can be located.Example 13.4. Define Dependency in
META-INF/MANIFEST.MF
Manifest-Version: 1.0 Build-Jdk: 1.6.0_24 Dependencies: org.jboss.security.negotiation
13.1.3. Configure JBoss Negotiation for Microsoft Windows Domain
{hostname}
, realm is referred to as {realm}
, domain is referred to as {domain}
, and the server hosting the JBoss EAP instance is referred to as {machine_name}
.
Procedure 13.2. Configure JBoss Negotiation for Microsoft Windows Domain
Clear Existing Service Principal Mappings
On a Microsoft Windows network some mappings are created automatically. Delete the automatically created mappings to map the identity of the server to the service principal for negotiation to take place correctly. The mapping enables the web browser on the client computer to trust the server and attempt SPNEGO. The client computer verifies with the domain controller for a mapping in the form ofHTTP{hostname}
.The following are the steps to delete the existing mappings:- List the mapping registered with the domain for the computer using the command,
setspn -L {machine_name}
. - Delete the existing mappings using the commands,
setspn -D HTTP/{hostname} {machine_name}
andsetspn -D host/{hostname} {machine_name}
.
- Create a host user account.
Note
Ensure the host user name is different from the{machine_name}
.In the rest of the section the host user name is referred to as{user_name}
. Define the mapping between the
{user_name}
and{hostname}
.- Run the following command to configure the Service Principal Mapping,
ktpass -princ HTTP/{hostname}@{realm} -pass * -mapuser {domain}\{user_name}
. - Enter the password for the user name when prompted.
Note
Reset the password for the user name as it is a prerequisite for exporting the keytab. - Verify the mapping by running the following command,
setspn -L {user_name}
Export the keytab of the user to the server on which EAP JBoss is installed.
Run the following command to export the keytab,ktab -k service.keytab -a HTTP/{hostname}@{realm}
.Note
This command exports the ticket for the HTTP/{hostname} principal to the keytabservice.keytab
, which is used to configure the host security domain on JBoss.- Define the principal within the security domain as follows:
<module-option name="principal">HTTP/{hostname}@{realm}</module-option>
13.1.4. Kerberos Authentication for PicketLink IDP
Procedure 13.3. Install JBoss EAP 6 and setup Kerberos
- Download and install JBoss EAP 6. Refer to installation instructions in the Installation Guide.
- Whether you are using Oracle Java or IBM Java, you must use unlimited JCE. Without unlimited JCE, the JBoss server cannot negotiate on the proper SPNEGO mechanism type (using 1.3.6.1.5.2.5, which is
GSS_IAKERB_MECHANISM
). - Use the example below to configure JBoss to use your desired Java version.
export JAVA_HOME=JDK/JRE_directory
Procedure 13.4. Test your Kerberos setup using JBoss Negotiation Toolkit
- Use the JBoss Negotiation Toolkit available at Github
- Modify the configuration files and use the
mvn clean install
command to build the project. - Copy the file
jboss-negotiation-toolkit/target/jboss-negotiation-toolkit.war
to$JBOSS_HOME/standalone/deployments/
. - Verify that all the three sections pass through the JBoss Negotiation Toolkit.
Procedure 13.5. Set up PicketLink IDP
idp.war
The example provided uses the idp.war
and employee.war
archives, which can be located in the PicketLink Quickstarts repository. Modify the files in idp.war
as described below.
- Add
org.jboss.security.negotiation
module to$JBOSS_HOME/standalone/deployments/idp.war/META-INF/jboss-deployment-structure.xml
because IDP is using the JBoss Negotiation module.<jboss-deployment-structure> <deployment> <!-- Add picketlink module dependency --> <dependencies> <module name="org.picketlink" /> <module name="org.jboss.security.negotiation" /> </dependencies> </deployment> </jboss-deployment-structure>
- Add an additional valve
org.jboss.security.negotiation.NegotiationAuthenticator
for SPNEGO to$JBOSS_HOME/standalone/deployments/idp.war/WEB-INF/jboss-web.xml
. - Change
security-domain
fromidp
toSPNEGO
in$JBOSS_HOME/standalone/deployments/idp.war/WEB-INF/jboss-web.xml
as follows:<jboss-web> <security-domain>SPNEGO</security-domain> <context-root>idp</context-root> <valve> <class-name>org.picketlink.identity.federation.bindings.tomcat.idp.IDPWebBrowserSSOValve</class-name> <param> <param-name>passUserPrincipalToAttributeManager</param-name> <param-value>true</param-value> </param> </valve> <valve> <class-name>org.jboss.security.negotiation.NegotiationAuthenticator</class-name> </valve> </jboss-web>
- Add or change the security-role added to your principal by Kerberos server setup to
$JBOSS_HOME/standalone/deployments/idp.war/WEB-INF/web.xml
. - Modify the file
$JBOSS_HOME/standalone/deployments/idp.war/WEB-INF/picketlink.xml
as follows:<PicketLink xmlns="urn:picketlink:identity-federation:config:2.1"> <PicketLinkIDP xmlns="urn:picketlink:identity-federation:config:2.1"> <IdentityURL>${idp.url::http://localhost:8080/idp/}</IdentityURL> <Trust> <Domains>redhat.com,localhost,amazonaws.com</Domains> </Trust> </PicketLinkIDP> <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1"> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler" /> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" /> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" /> <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" /> </Handlers> <!-- The configuration bellow defines a token timeout and a clock skew. Both configurations will be used during the SAML Assertion creation. This configuration is optional. It is defined only to show you how to set the token timeout and clock skew configuration. --> <PicketLinkSTS xmlns="urn:picketlink:identity-federation:config:1.0" TokenTimeout="5000" ClockSkew="0"> <TokenProviders> <TokenProvider ProviderClass="org.picketlink.identity.federation.core.saml.v1.providers.SAML11AssertionTokenProvider" TokenType="urn:oasis:names:tc:SAML:1.0:assertion" TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:1.0:assertion" /> <TokenProvider ProviderClass="org.picketlink.identity.federation.core.saml.v2.providers.SAML20AssertionTokenProvider" TokenType="urn:oasis:names:tc:SAML:2.0:assertion" TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:2.0:assertion" /> </TokenProviders> </PicketLinkSTS> </PicketLink>
- Change
IdentityURL
to match the host name of server you are running IDP on. - Change
Trust
to contain the domain names trusted by the Identity Provider. - Modify the
employee.war
. Add or change security-roles added to your principal by Kerberos server setup to$JBOSS_HOME/standalone/deployments/employee.war/WEB-INF/web.xml
. - Modify the
security domain
configuration in the file$JBOSS_HOME/standalone/configuration/standalone.xml
. Role mapping configuration is the same as that in normal security domain configurations.<security-domain name="host" cache-type="default"> <authentication> <login-module code="Kerberos" flag="required"> <module-option name="principal" value="HTTP/something.com@yourdomain.COM"/> <module-option name="storeKey" value="true"/> <module-option name="useKeyTab" value="true"/> <module-option name="doNotPrompt" value="true"/> <module-option name="keyTab" value="/root/keytab"/> </login-module> </authentication> </security-domain> <security-domain name="SPNEGO" cache-type="default"> <authentication> <login-module code="SPNEGO" flag="required"> <module-option name="serverSecurityDomain" value="host"/> </login-module> </authentication> </security-domain> <security-domain name="sp" cache-type="default"> <authentication> <login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required" /> </authentication> </security-domain>
Note
jboss.security.disable.secdomain.option
to true
. Refer to Section 13.2.2, “Configure Authentication in a Security Domain” for details. Update the login module to the following:
<login-module code="Kerberos" flag="required"> <module-option name="principal" value="HTTP/something.com@yourdomain.COM"/> <module-option name="credsType" value="acceptor"/> <module-option name="useKeytab" value="file:///root/keytab"/> </login-module>
Procedure 13.6. Verify Kerberos authentication setup for PicketLink IDP
- Start JBoss EAP server using
$JBOSS_HOME/bin/standalone.sh
. - Setup your browser, for example Firefox, to use Kerberos. Follow the instructions provided here: https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/5/html/Deployment_Guide/sso-config-firefox.html
- Verify that you are able to access the
http://YOUR_DOMAIN:8080/employee
from Firefox configured as mentioned above.
13.1.5. Login with Certificate with PicketLink IDP
You can configure the PicketLink IDP to support SSL. The following procedure is an example demonstrating how to configure a web application as an IDP supporting SSL client authentication. There are two ways to configure the IDP to authenticate users:
- If SSL is being used, the server will ask the client for a certificate and use this certificate to authenticate the user.
- If no certificate is provided by the client, a form-based authentication is performed.
13.1.5.1. JBoss EAP 6.3 SSL Configuration
Procedure 13.7. Create the certificate, keystore, and truststore for your server
Create a Certificate for Your Server
Use the following command to create a certificate for your server:keytool -genkey -alias server -keyalg RSA -keystore server.keystore -storepass change_it -validity 365
The system prompts you for additional information. You must provide the values as required. The CN name of the certificate must be the same as your DNS server name. For example, in case of localhost you could use the following command:keytool -genkey -alias server -keystore server.keystore -storepass change_it -keypass password -dname "CN=localhost,OU=QE,O=example.com,L=Brno,C=CZ"
Create the Client Certificate
You will use this client certificate to authenticate against the server when accessing a resource through SSL.keytool -genkey -alias client -keystore client.keystore -storepass change_it -validity 365 -keyalg RSA -keysize 2048 -storetype pkcs12
Create the Truststore
Export the client's certificate and create a truststore by importing this certificate:keytool -exportcert -keystore client.keystore -storetype pkcs12 -storepass change_it -alias client -keypass change_it -file client.keystore keytool -import -file client.keystore -alias client -keystore client.truststore
Change the JBoss EAP 6.3 Server Installation to Enable SSL
Add the following connector to the web subsystem to enable SSL:<connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" enable-lookups="false" secure="true"> <ssl name="localhost-ssl" key-alias="server" password="change_it" certificate-key-file="${jboss.server.config.dir}/server.keystore" protocol="TLSv1" verify-client="want" ca-certificate-file="${jboss.server.config.dir}/client.truststore"/> </connector>
Restart the Server
Restart the server and verify that it is responding on: https://localhost:8443Trust the Certificate
You will be prompted to trust the server certificate.
Before accessing the application, you must import the client.keystore
to your browser. This file holds the client certificate. When you access the application, the browser prompts you to select the certificate you need to use to authenticate with the server. Select the desired certificate.
Add the following security domain to your server installation. If you're in standalone mode, you must add it to the JBOSS_HOME/standalone/configuration/standalone.xml
:
<security-domain name="idp" cache-type="default"> <authentication> <login-module code="CertificateRoles" flag="optional"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="securityDomain" value="idp"/> <module-option name="verifier" value="org.jboss.security.auth.certs.AnyCertVerifier"/> </login-module> <login-module code="org.picketlink.identity.federation.bindings.jboss.auth.RegExUserNameLoginModule" flag="optional"> <module-option name="regex" value="CN=(.*?),"/> </login-module> <login-module code="UsersRoles" flag="required"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="usersProperties" value="users.properties"/> <module-option name="rolesProperties" value="roles.properties"/> </login-module> </authentication> <jsse keystore-password="change_it" keystore-url="${jboss.server.config.dir}" truststore-password="change_it" truststore-url="${jboss.server.config.dir}" client-auth="true"/> </security-domain>The configuration example above validates any provided certificate. If no certificate is provided or if the authentication fails, the procedure falls back to a user/password based authentication.
The Regular Expression User Name Login module can be used after Certificate Login Modules to extract a username, UID or other field from the principal name so that roles can be obtained from LDAP. The module has an option named regex
which specifies the regular expression to be applied to the principal name, the result of which is passed on to the subsequent login module.
UID=007, EMAILADDRESS=something@something, CN=James Bond, O=SpyAgency
would result in the output UID=007
.
Example 13.5. Example of Regular Expression User Name Login Module
<login-module code="org.picketlink.identity.federation.bindings.jboss.auth.RegExUserNameLoginModule" flag="required"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="regex" value="UID=(.*?),"/> </login-module>
java.util.regex.Pattern
class documentation at http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html.
13.2. Authentication
13.2.1. About Authentication
13.2.2. Configure Authentication in a Security Domain
Procedure 13.8. Setup Authentication Settings for a Security Domain
Open the security domain's detailed view.
- Click the Configuration label at the top of the management console.
- Select the profile to modify from the Profile selection box at the top left of the Profile view.
- Expand the Security menu, and select Security Domains.
- Click the View link for the security domain you want to edit.
Navigate to the Authentication subsystem configuration.
Select the Authentication label at the top of the view if it is not already selected.The configuration area is divided into two areas: Login Modules and Details. The login module is the basic unit of configuration. A security domain can include several login modules, each of which can include several attributes and options.Add an authentication module.
Click Add to add a JAAS authentication module. Fill in the details for your module.The Code is the class name of the module. The Flag setting controls how the module relates to other authentication modules within the same security domain.Explanation of the FlagsThe Java Enterprise Edition 6 specification provides the following explanation of the flags for security modules. The following list is taken from http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html#AppendixA. Refer to that document for more detailed information.
Flag Details required The LoginModule is required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.requisite LoginModule is required to succeed. If it succeeds, authentication continues down the LoginModule list. If it fails, control immediately returns to the application (authentication does not proceed down the LoginModule list).sufficient The LoginModule is not required to succeed. If it does succeed, control immediately returns to the application (authentication does not proceed down the LoginModule list). If it fails, authentication continues down the LoginModule list.optional The LoginModule is not required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.Edit authentication settings
After you have added your module, you can modify its Code or Flags by clicking in the Details section of the screen. Be sure the Attributes tab is selected.Optional: Add or remove module options.
If you need to add options to your module, click its entry in the Login Modules list, and select the Module Options tab in the Details section of the page. Click the button, and provide the key and value for the option. Use the button to remove an option.
Your authentication module is added to the security domain, and is immediately available to applications which use the security domain.
jboss.security.security_domain
Module Option
By default, each login module defined in a security domain has the jboss.security.security_domain
module option added to it automatically. This option causes problems with login modules which check to make sure that only known options are defined. The IBM Kerberos login module, com.ibm.security.auth.module.Krb5LoginModule
is one of these.
true
when starting JBoss EAP 6. Add the following to your start-up parameters.
-Djboss.security.disable.secdomain.option=true
13.3. JAAS - Java Authentication and Authorization Service
13.3.1. About JAAS
13.3.2. JAAS Core Classes
Subject
(javax.security.auth.Subject
)
Configuration
(javax.security.auth.login.Configuration
)LoginContext
(javax.security.auth.login.LoginContext
)
Principal
(java.security.Principal
)Callback
(javax.security.auth.callback.Callback
)CallbackHandler
(javax.security.auth.callback.CallbackHandler
)LoginModule
(javax.security.auth.spi.LoginModule
)
13.3.3. Subject and Principal classes
Subject
class is the central class in JAAS. A Subject
represents information for a single entity, such as a person or service. It encompasses the entity's principals, public credentials, and private credentials. The JAAS API uses the existing Java 2 java.security.Principal
interface to represent a principal, which is essentially a typed name.
public Set getPrincipals() {...} public Set getPrincipals(Class c) {...}
getPrincipals()
returns all principals contained in the subject. getPrincipals(Class c)
returns only those principals that are instances of class c
or one of its subclasses. An empty set is returned if the subject has no matching principals.
java.security.acl.Group
interface is a sub-interface of java.security.Principal
, so an instance in the principals set may represent a logical grouping of other principals or groups of principals.
13.3.4. Subject Authentication
- An application instantiates a
LoginContext
and passes in the name of the login configuration and aCallbackHandler
to populate theCallback
objects, as required by the configurationLoginModule
s. - The
LoginContext
consults aConfiguration
to load all theLoginModules
included in the named login configuration. If no such named configuration exists theother
configuration is used as a default. - The application invokes the
LoginContext.login
method. - The login method invokes each loaded
LoginModule
. As eachLoginModule
attempts to authenticate the subject, it invokes the handle method on the associatedCallbackHandler
to obtain the information required for the authentication process. The required information is passed to the handle method in the form of an array ofCallback
objects. Upon success, theLoginModule
s associate relevant principals and credentials with the subject. - The
LoginContext
returns the authentication status to the application. Success is represented by a return from the login method. Failure is represented through a LoginException being thrown by the login method. - If authentication succeeds, the application retrieves the authenticated subject using the
LoginContext.getSubject
method. - After the scope of the subject authentication is complete, all principals and related information associated with the subject by the
login
method can be removed by invoking theLoginContext.logout
method.
LoginContext
class provides the basic methods for authenticating subjects and offers a way to develop an application that is independent of the underlying authentication technology. The LoginContext
consults a Configuration
to determine the authentication services configured for a particular application. LoginModule
classes represent the authentication services. Therefore, you can plug different login modules into an application without changing the application itself. The following code shows the steps required by an application to authenticate a subject.
CallbackHandler handler = new MyHandler(); LoginContext lc = new LoginContext("some-config", handler); try { lc.login(); Subject subject = lc.getSubject(); } catch(LoginException e) { System.out.println("authentication failed"); e.printStackTrace(); } // Perform work as authenticated Subject // ... // Scope of work complete, logout to remove authentication info try { lc.logout(); } catch(LoginException e) { System.out.println("logout failed"); e.printStackTrace(); } // A sample MyHandler class class MyHandler implements CallbackHandler { public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException { for (int i = 0; i < callbacks.length; i++) { if (callbacks[i] instanceof NameCallback) { NameCallback nc = (NameCallback)callbacks[i]; nc.setName(username); } else if (callbacks[i] instanceof PasswordCallback) { PasswordCallback pc = (PasswordCallback)callbacks[i]; pc.setPassword(password); } else { throw new UnsupportedCallbackException(callbacks[i], "Unrecognized Callback"); } } } }
LoginModule
interface. This allows an administrator to plug different authentication technologies into an application. You can chain together multiple LoginModule
s to allow for more than one authentication technology to participate in the authentication process. For example, one LoginModule
may perform user name/password-based authentication, while another may interface to hardware devices such as smart card readers or biometric authenticators.
LoginModule
is driven by the LoginContext
object against which the client creates and issues the login method. The process consists of two phases. The steps of the process are as follows:
- The
LoginContext
creates each configuredLoginModule
using its public no-arg constructor. - Each
LoginModule
is initialized with a call to its initialize method. TheSubject
argument is guaranteed to be non-null. The signature of the initialize method is:public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options)
- The
login
method is called to start the authentication process. For example, a method implementation might prompt the user for a user name and password and then verify the information against data stored in a naming service such as NIS or LDAP. Alternative implementations might interface to smart cards and biometric devices, or simply extract user information from the underlying operating system. The validation of user identity by eachLoginModule
is considered phase 1 of JAAS authentication. The signature of thelogin
method isboolean login() throws LoginException
. ALoginException
indicates failure. A return value of true indicates that the method succeeded, whereas a return value of false indicates that the login module should be ignored. - If the
LoginContext
's overall authentication succeeds,commit
is invoked on eachLoginModule
. If phase 1 succeeds for aLoginModule
, then the commit method continues with phase 2 and associates the relevant principals, public credentials, and/or private credentials with the subject. If phase 1 fails for aLoginModule
, thencommit
removes any previously stored authentication state, such as user names or passwords. The signature of thecommit
method is:boolean commit() throws LoginException
. Failure to complete the commit phase is indicated by throwing aLoginException
. A return of true indicates that the method succeeded, whereas a return of false indicates that the login module should be ignored. - If the
LoginContext
's overall authentication fails, then theabort
method is invoked on eachLoginModule
. Theabort
method removes or destroys any authentication state created by the login or initialize methods. The signature of theabort
method isboolean abort() throws LoginException
. Failure to complete theabort
phase is indicated by throwing aLoginException
. A return of true indicates that the method succeeded, whereas a return of false indicates that the login module should be ignored. - To remove the authentication state after a successful login, the application invokes
logout
on theLoginContext
. This in turn results in alogout
method invocation on eachLoginModule
. Thelogout
method removes the principals and credentials originally associated with the subject during thecommit
operation. Credentials should be destroyed upon removal. The signature of thelogout
method is:boolean logout() throws LoginException
. Failure to complete the logout process is indicated by throwing aLoginException
. A return of true indicates that the method succeeded, whereas a return of false indicates that the login module should be ignored.
LoginModule
must communicate with the user to obtain authentication information, it uses a CallbackHandler
object. Applications implement the CallbackHandler interface and pass it to the LoginContext
, which send the authentication information directly to the underlying login modules.
CallbackHandler
both to gather input from users, such as a password or smart card PIN, and to supply information to users, such as status information. By allowing the application to specify the CallbackHandler
, underlying LoginModule
s remain independent from the different ways applications interact with users. For example, a CallbackHandler
's implementation for a GUI application might display a window to solicit user input. On the other hand, a CallbackHandler
implementation for a non-GUI environment, such as an application server, might simply obtain credential information by using an application server API. The CallbackHandler interface has one method to implement:
void handle(Callback[] callbacks) throws java.io.IOException, UnsupportedCallbackException;
Callback
interface is the last authentication class we will look at. This is a tagging interface for which several default implementations are provided, including the NameCallback
and PasswordCallback
used in an earlier example. A LoginModule
uses a Callback
to request information required by the authentication mechanism. LoginModule
s pass an array of Callback
s directly to the CallbackHandler.handle
method during the authentication's login phase. If a callbackhandler
does not understand how to use a Callback
object passed into the handle method, it throws an UnsupportedCallbackException
to abort the login call.
13.4. Java Authentication SPI for Containers (JASPI)
13.4.1. About Java Authentication SPI for Containers (JASPI) Security
13.4.2. Configure Java Authentication SPI for Containers (JASPI) Security
<authentication-jaspi>
element to your security domain. The configuration is similar to a standard authentication module, but login module elements are enclosed in a <login-module-stack>
element. The structure of the configuration is:
Example 13.6. Structure of the authentication-jaspi
element
<authentication-jaspi> <login-module-stack name="..."> <login-module code="..." flag="..."> <module-option name="..." value="..."/> </login-module> </login-module-stack> <auth-module code="..." login-module-stack-ref="..."> <module-option name="..." value="..."/> </auth-module> </authentication-jaspi>
EAP_HOME/domain/configuration/domain.xml
or EAP_HOME/standalone/configuration/standalone.xml
.
13.5. Authorization
13.5.1. About Authorization
13.5.2. Configure Authorization in a Security Domain
Procedure 13.9. Setup Authorization in a Security Domain
Open the security domain's detailed view.
- Click the Configuration label at the top of the management console.
- In a managed domain, select the profile to modify from the Profile drop down box at the top left.
- Expand the Security menu item, and select Security Domains.
- Click the View link for the security domain you want to edit.
Navigate to the Authorization subsystem configuration.
Select the Authorization label at the top of the screen.The configuration area is divided into two areas: Policies and Details. The login module is the basic unit of configuration. A security domain can include several authorization policies, each of which can include several attributes and options.Add a policy.
Click Add to add a JAAS authorization policy module. Fill in the details for your module.The Code is the class name of the module. The Flag controls how the module relates to other authorization policy modules within the same security domain.Explanation of the FlagsThe Java Enterprise Edition 6 specification provides the following explanation of the flags for security modules. The following list is taken from http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html#AppendixA. Refer to that document for more detailed information.
Flag Details required The LoginModule is required to succeed. If it succeeds or fails, authorization still continues to proceed down the LoginModule list.requisite LoginModule is required to succeed. If it succeeds, authorization continues down the LoginModule list. If it fails, control immediately returns to the application (authorization does not proceed down the LoginModule list).sufficient The LoginModule is not required to succeed. If it does succeed, control immediately returns to the application (authorization does not proceed down the LoginModule list). If it fails, authorization continues down the LoginModule list.optional The LoginModule is not required to succeed. If it succeeds or fails, authorization still continues to proceed down the LoginModule list.Edit authorization settings
After you have added your module, you can modify its Code or Flags by clicking in the Details section of the screen. Be sure the Attributes tab is selected.Optional: Add or remove module options.
If you need to add options to your module, click its entry in the Policies list, and select the Module Options tab in the Details section of the page. Click and provide the key and value for the option. Use the button to remove an option.
Your authorization policy module is added to the security domain, and is immediately available to applications which use the security domain.
13.6. Java Authorization Contract for Containers (JACC)
13.6.1. About Java Authorization Contract for Containers (JACC)
13.6.2. Configure Java Authorization Contract for Containers (JACC) Security
jboss-web.xml
to include the correct parameters.
To add JACC support to the security domain, add the JACC
authorization policy to the authorization stack of the security domain, with the required
flag set. The following is an example of a security domain with JACC support. However, the security domain is configured in the Management Console or Management CLI, rather than directly in the XML.
<security-domain name="jacc" cache-type="default"> <authentication> <login-module code="UsersRoles" flag="required"> </login-module> </authentication> <authorization> <policy-module code="JACC" flag="required"/> </authorization> </security-domain>
The jboss-web.xml
is located in the WEB-INF/
directory of your deployment, and contains overrides and additional JBoss-specific configuration for the web container. To use your JACC-enabled security domain, you need to include the <security-domain>
element, and also set the <use-jboss-authorization>
element to true
. The following application is properly configured to use the JACC security domain above.
<jboss-web> <security-domain>jacc</security-domain> <use-jboss-authorization>true</use-jboss-authorization> </jboss-web>
Configuring EJBs to use a security domain and to use JACC differs from Web Applications. For an EJB, you can declare method permissions on a method or group of methods, in the ejb-jar.xml
descriptor. Within the <ejb-jar>
element, any child <method-permission>
elements contain information about JACC roles. Refer to the example configuration for more details. The EJBMethodPermission
class is part of the Java Enterprise Edition 6 API, and is documented at http://docs.oracle.com/javaee/6/api/javax/security/jacc/EJBMethodPermission.html.
Example 13.7. Example JACC Method Permissions in an EJB
<ejb-jar> <assembly-descriptor> <method-permission> <description>The employee and temp-employee roles may access any method of the EmployeeService bean </description> <role-name>employee</role-name> <role-name>temp-employee</role-name> <method> <ejb-name>EmployeeService</ejb-name> <method-name>*</method-name> </method> </method-permission> </assembly-descriptor> </ejb-jar>
jboss-ejb3.xml
descriptor, in the <security>
child element. In addition to the security domain, you can also specify the run-as principal, which changes the principal the EJB runs as.
Example 13.8. Example Security Domain Declaration in an EJB
<ejb-jar> <assembly-descriptor> <security> <ejb-name>*</ejb-name> <security-domain>myDomain</security-domain> <run-as-principal>myPrincipal</run-as-principal> </security> </assembly-descriptor> </ejb-jar>
13.6.3. Fine Grained Authorization Using XACML
13.6.3.1. About Fine Grained Authorization and XACML
- PERMIT - The access is approved.
- DENY - The access is denied.
- INDETERMINATE - There is an error at the PDP.
- NOTAPPLICABLE - There is some attribute missing in the request or there is no policy match.
- Oasis XACML v2.0 library
- JAXB v2.0 based object model
- ExistDB Integration for storing/retrieving XACML Policies and Attributes
13.6.3.2. Configure XACML for Fine Grained Authorization
Procedure 13.10. Configure XACML
- Download the library which is a single jar file.
Create one or more policy files for XACML
- Under the
WEB-INF/classes
, create apolicies
directory to save all your policies. - Create a
policyConfig.xml
underWEB-INF/classes
directory.The following are the two types of policy sets can be defined:- Role Permission Policy Sets (RPS)
- Permission Policy Sets (PPS)
Example 13.9. Role Permission Policy Sets (RPS)
Employee<PolicySet xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" PolicySetId="RPS:employee:role" PolicyCombiningAlgId="urn:oasis:names:tc:xacml:1.0:policy-combining-algorithm:permit-overrides"> <Target> <Subjects> <Subject> <SubjectMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:anyURI-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">employee</AttributeValue> <SubjectAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI"/> </SubjectMatch> </Subject> </Subjects> </Target> <!-- Use permissions associated with the employee role --> <PolicySetIdReference>PPS:employee:role</PolicySetIdReference> </PolicySet>
Manager<PolicySet xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" PolicySetId="RPS:manager:role" PolicyCombiningAlgId="urn:oasis:names:tc:xacml:1.0:policy-combining-algorithm:permit-overrides"> <Target> <Subjects> <Subject> <SubjectMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:anyURI-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">manager</AttributeValue> <SubjectAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI"/> </SubjectMatch> </Subject> </Subjects> </Target> <!-- Use permissions associated with the manager role --> <PolicySetIdReference>PPS:manager:role</PolicySetIdReference> </PolicySet>
Example 13.10. Permission Policy Sets (PPS)
Employee<PolicySet xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" PolicySetId="PPS:employee:role" PolicyCombiningAlgId="urn:oasis:names:tc:xacml:1.0:policy-combining-algorithm:permit-overrides"> <Target /> <!-- Permissions specifically for the employee role --> <Policy PolicyId="Permissions:specifically:for:the:employee:role" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:permit-overrides"> <Target /> <!-- Permission to create a purchase order --> <Rule RuleId="Permission:to:create:a:purchase:order" Effect="Permit"> <Target> <Resources> <Resource> <ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">purchase order </AttributeValue> <ResourceAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" DataType="http://www.w3.org/2001/XMLSchema#string" /> </ResourceMatch> </Resource> </Resources> <Actions> <Action> <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">create</AttributeValue> <ActionAttributeDesignator AttributeId="urn:action-id" DataType="http://www.w3.org/2001/XMLSchema#string" /> </ActionMatch> </Action> </Actions> </Target> </Rule> </Policy> <!-- HasPrivilegesOfRole Policy for employee role --> <Policy PolicyId="Permission:to:have:employee:role:permissions" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:permit-overrides"> <Target /> <!-- Permission to have employee role permissions --> <Rule RuleId="Permission:to:have:employee:permissions" Effect="Permit"> <Condition> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:and"> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:anyURI-is-in"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">employee</AttributeValue> <ResourceAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI" /> </Apply> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:anyURI-is-in"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">urn:oasis:names:tc:xacml:2.0:actions:hasPrivilegesOfRole </AttributeValue> <ActionAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#anyURI" /> </Apply> </Apply> </Condition> </Rule> </Policy> </PolicySet>
Manager<PolicySet xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" PolicySetId="PPS:manager:role" PolicyCombiningAlgId="urn:oasis:names:tc:xacml:1.0:policy-combining-algorithm:permit-overrides"> <Target /> <!-- Permissions specifically for the manager role --> <Policy PolicyId="Permissions:specifically:for:the:manager:role" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:permit-overrides"> <Target /> <!-- Permission to sign a purchase order --> <Rule RuleId="Permission:to:sign:a:purchase:order" Effect="Permit"> <Target> <Resources> <Resource> <ResourceMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">purchase order </AttributeValue> <ResourceAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id" DataType="http://www.w3.org/2001/XMLSchema#string" /> </ResourceMatch> </Resource> </Resources> <Actions> <Action> <ActionMatch MatchId="urn:oasis:names:tc:xacml:1.0:function:string-equal"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#string">sign</AttributeValue> <ActionAttributeDesignator AttributeId="urn:action-id" DataType="http://www.w3.org/2001/XMLSchema#string" /> </ActionMatch> </Action> </Actions> </Target> </Rule> </Policy> <!-- HasPrivilegesOfRole Policy for manager role --> <Policy PolicyId="Permission:to:have:manager:role:permissions" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:permit-overrides"> <Target /> <!-- Permission to have manager role permissions --> <Rule RuleId="Permission:to:have:manager:permissions" Effect="Permit"> <Condition> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:and"> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:anyURI-is-in"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">manager</AttributeValue> <ResourceAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI" /> </Apply> <Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:anyURI-is-in"> <AttributeValue DataType="http://www.w3.org/2001/XMLSchema#anyURI">urn:oasis:names:tc:xacml:2.0:actions:hasPrivilegesOfRole </AttributeValue> <ActionAttributeDesignator AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#anyURI" /> </Apply> </Apply> </Condition> </Rule> </Policy> <!-- Include permissions associated with employee role --> <PolicySetIdReference>PPS:employee:role</PolicySetIdReference> </PolicySet>
Create a configuration file for the XACML engine.
A configuration file is created to configure the locators and mention the directories where the policies are saved.Example 13.11. Configuration File
Configuration File Only Indicating The Directory Of The Policy Files.<ns:jbosspdp xmlns:ns="urn:jboss:xacml:2.0"> <ns:Policies> <ns:PolicySet> <ns:Location>test/policies/rbac/</ns:Location> </ns:PolicySet> </ns:Policies> <ns:Locators> <ns:Locator Name="org.jboss.security.xacml.locators.JBossRBACPolicySetLocator"/> </ns:Locators> </ns:jbosspdp>
Configuration File Defining the Policy Set<ns:jbosspdp xmlns:ns="urn:jboss:xacml:2.0"> <ns:Policies> <ns:PolicySet> <ns:Location>test/policies/rbac/employee-PPS-policyset.xml</ns:Location> </ns:PolicySet> <ns:PolicySet> <ns:Location>test/policies/rbac/manager-PPS-policyset.xml</ns:Location> </ns:PolicySet> <ns:PolicySet> <ns:Location>test/policies/rbac/employee-RPS-policyset.xml</ns:Location> </ns:PolicySet> <ns:PolicySet> <ns:Location>test/policies/rbac/manager-RPS-policyset.xml</ns:Location> </ns:PolicySet> </ns:Policies> <ns:Locators> <ns:Locator Name="org.jboss.security.xacml.locators.JBossRBACPolicySetLocator"/> </ns:Locators> </ns:jbosspdp>
- Create a Policy Decision Point (PDP) and pass it in the Configuration File.
- In the Policy Enforcement Point (PEP), create an XACML request based on the context. Pass the XACML request to the PDP to get one of the following access decisions:
- Permit
- Deny
- Indeterminate
- Not Applicable
Example 13.12. Access Decisions
Permit condition<Request xmlns="urn:oasis:names:tc:xacml:2.0:context:schema:os" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:xacml:2.0:context:schema:os access_control-xacml-2.0-context-schema-os.xsd"> <Subject> <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" DataType="http://www.w3.org/2001/XMLSchema#string"> <AttributeValue>Anne</AttributeValue> </Attribute> <Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI"> <AttributeValue>manager</AttributeValue> </Attribute> </Subject> <Resource> <Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI"> <AttributeValue>manager</AttributeValue> </Attribute> </Resource> <Action> <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#anyURI"> <AttributeValue>urn:oasis:names:tc:xacml:2.0:actions:hasPrivilegesOfRole</AttributeValue> </Attribute> </Action> </Request>
Deny Permission<Request xmlns="urn:oasis:names:tc:xacml:2.0:context:schema:os" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:xacml:2.0:context:schema:os access_control-xacml-2.0-context-schema-os.xsd"> <Subject> <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id" DataType="http://www.w3.org/2001/XMLSchema#string"> <AttributeValue>Anne</AttributeValue> </Attribute> <Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI"> <AttributeValue>manager</AttributeValue> </Attribute> </Subject> <Resource> <Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:subject:role" DataType="http://www.w3.org/2001/XMLSchema#anyURI"> <AttributeValue>manager</AttributeValue> </Attribute> </Resource> <Action> <Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#anyURI"> <AttributeValue>urn:nobody</AttributeValue> </Attribute> </Action> </Request>
13.7. Security Auditing
13.7.1. About Security Auditing
13.7.2. Configure Security Auditing
Procedure 13.11. Setup Security Auditing for a Security Domain
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.
- Expand the Security menu and select Security Domains.
- Click View for the security domain you want to edit.
Navigate to the Auditing subsystem configuration.
Select the Audit tab at the top 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. Fill in the Code section with the classname of the provider module.Verify if your 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 6 includes theLogAuditProvider
module by default. If enabled following the steps above, this audit module writes security notifications to aaudit.log
file in thelog
subfolder within theEAP_HOME
directory.To verify if the steps above have worked in the context of theLogAuditProvider
, perform an action that is likely to trigger a notification and then check the audit log file.For a full list of included security auditing provider modules, see here: Section A.4, “Included Security Auditing Provider Modules”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 , and provide the key and value for the option.To edit an option that already exists, clickto remove it, and click to add it again with the correct options.
Your security auditing module is added to the security domain, and is immediately available to applications which use the security domain.
13.7.3. New Security Properties
Name | Description | Possible values | Behavior | Default |
---|---|---|---|---|
org.jboss.security.web.audit | This property controls the granularity of the security auditing of web requests. | off , headers , cookies , parameters , attributes | Any component (or comma-separated group of components) specified will be audited out of web requests. | headers,parameters |
org.jboss.security.web.audit.mask | This property can be used to specify a list of strings to be matched against headers, parameters, cookies, and attributes of web requests. Any element matching the specified masks will be excluded from security audit logging. | Any comma separated string indicating keys of headers, parameters, cookies, and attributes. | Currently, the matching of the masks is fuzzy rather than strict. For example, a mask of authorization will mask both the header called authorization and the parameter called custom_authorization. A future release may introduce strict masks. | j_password,authorization |
13.8. Security Mapping
13.8.1. About Security Mapping
13.8.2. Configure Security Mapping in a Security Domain
Procedure 13.12. Setup Security Mapping Settings in a Security Domain
Open the security domain's detailed view.
- Click the Configuration label at the top of the management console.
- In a managed domain, select a profile from the Profile selection box at the top left.
- Expand the Security menu, and select Security Domains.
- Click View for the security domain you want to edit.
Navigate to the Mapping subsystem configuration.
Select the Mapping label at the top of the screen.The configuration area is divided into two areas: Modules and Details. The mapping module is the basic unit of configuration. A security domain can include several mapping modules, each of which can include several attributes and options.Add a security mapping module.
Click Add.Fill in the details for your module. The Code is the class name of the module. The Type field refers to the type of mapping this module performs. Allowed values are principal, role, attribute or credential.Edit a security mapping module
After you have added your module, you can modify its Code or Type.- Select the Attributes tab.
- Click Details section of the screen.in the
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 , and provide the key and value for the option.To edit an option that already exists, click Remove to remove it, and add it again with the new value.Use thebutton to remove an option.
Your security mapping module is added to the security domain, and is immediately available to applications which use the security domain.
13.9. Use a Security Domain in Your Application
To use a security domain in your application, first you need to define the security domain in the server's configuration and then enable it for an application in the application's deployment descriptor. Then you must add the required annotations to the EJB that uses it. This topic covers the steps required to use a security domain in your application.
Warning
Procedure 13.13. Configure Your Application to Use a Security Domain
Define the Security Domain
You need to define the security domain in the server's configuration file, and then enable it for an application in the application's descriptor file.Configure the security domain in the server's configuration file
The security domain is configured in thesecurity
subsystem of the server's configuration file. If the JBoss EAP 6 instance is running in a managed domain, this is thedomain/configuration/domain.xml
file. If the JBoss EAP 6 instance is running as a standalone server, this is thestandalone/configuration/standalone.xml
file.Theother
,jboss-web-policy
, andjboss-ejb-policy
security domains are provided by default in JBoss EAP 6. The following XML example was copied from thesecurity
subsystem in the server's configuration file.Thecache-type
attribute of a security domain specifies a cache for faster authentication checks. Allowed values aredefault
to use a simple map as the cache, orinfinispan
to use an Infinispan cache.<subsystem xmlns="urn:jboss:domain:security:1.2"> <security-domains> <security-domain name="other" cache-type="default"> <authentication> <login-module code="Remoting" flag="optional"> <module-option name="password-stacking" value="useFirstPass"/> </login-module> <login-module code="RealmDirect" flag="required"> <module-option name="password-stacking" value="useFirstPass"/> </login-module> </authentication> </security-domain> <security-domain name="jboss-web-policy" cache-type="default"> <authorization> <policy-module code="Delegating" flag="required"/> </authorization> </security-domain> <security-domain name="jboss-ejb-policy" cache-type="default"> <authorization> <policy-module code="Delegating" flag="required"/> </authorization> </security-domain> </security-domains> </subsystem>
You can configure additional security domains as needed using the Management Console or CLI.Enable the security domain in the application's descriptor file
The security domain is specified in the<security-domain>
child element of the<jboss-web>
element in the application'sWEB-INF/jboss-web.xml
file. The following example configures a security domain namedmy-domain
.<jboss-web> <security-domain>my-domain</security-domain> </jboss-web>
This is only one of many settings which you can specify in theWEB-INF/jboss-web.xml
descriptor.
Add the Required Annotation to the EJB
You configure security in the EJB using the@SecurityDomain
and@RolesAllowed
annotations. The following EJB code example limits access to theother
security domain by users in theguest
role.package example.ejb3; import java.security.Principal; import javax.annotation.Resource; import javax.annotation.security.RolesAllowed; import javax.ejb.SessionContext; import javax.ejb.Stateless; import org.jboss.ejb3.annotation.SecurityDomain; /** * Simple secured EJB using EJB security annotations * Allow access to "other" security domain by users in a "guest" role. */ @Stateless @RolesAllowed({ "guest" }) @SecurityDomain("other") public class SecuredEJB { // Inject the Session Context @Resource private SessionContext ctx; /** * Secured EJB method using security annotations */ public String getSecurityInfo() { // Session context injected using the resource annotation Principal principal = ctx.getCallerPrincipal(); return principal.toString(); } }
For more code examples, see theejb-security
quickstart in the JBoss EAP 6 Quickstarts bundle, which is available from the Red Hat Customer Portal.
Chapter 14. Single Sign On (SSO)
14.1. About Single Sign On (SSO) for Web Applications
Single Sign On (SSO) allows authentication to one resource to implicitly authorize access to other resources.
Non-clustered SSO limits the sharing of authorization information to applications on the same virtual host. In addition, there is no resiliency in the event of a host failure. Clustered SSO data can be shared between applications in multiple virtual hosts, and is resilient to failover. In addition, clustered SSO is able to receive requests from a load balancer.
If a resource is unprotected, a user is not challenged to authenticate at all. If a user accesses a protected resource, the user is required to authenticate.
14.2. About Clustered Single Sign On (SSO) for Web Applications
jboss-web.xml
.
- Apache Tomcat ClusteredSingleSignOn
- Apache Tomcat IDPWebBrowserSSOValve
- SPNEGO-based SSO provided by PicketLink
14.3. Choose the Right SSO Implementation
web.xml
deployment descriptor. Clustered SSO allows for replication of security context and identity information, regardless of whether or not the applications are themselves clustered. Although these technologies may be used together they are separate concepts.
If your organization already uses a Kerberos-based authentication and authorization system, such as Microsoft Active Directory, you can use the same systems to transparently authenticate to your enterprise applications running on JBoss EAP 6.
If you are running multiple applications on a single instance and need to enable SSO session replication for those applications, non-clustered SSO will meet your requirements.
If you are running either a single application, or multiple applications, across a cluster and need to enable SSO session replication for those applications, clustered SSO will meet your requirements.
14.4. Use Single Sign On (SSO) In A Web Application
Single Sign On (SSO) capabilities are provided by the web and Infinispan subsystems. Use this procedure to configure SSO in web applications.
Prerequisites
- A configured security domain which handles authentication and authorization.
- The
infinispan
subsystem. It is present in thefull-ha
profile for a managed domain, or by using thestandalone-full-ha.xml
configuration in a standalone server. - The
web
cache-container
and SSO replicated-cache. The initial configuration files already contain theweb
cache-container, and some of the configurations already contain the SSO replicated-cache as well. Use the following commands to check for and enable the SSO replicated-cache. Note that these commands modify theha
profile of a managed domain. You can change the commands to use a different profile, or remove the/profile=ha
portion of the command, for a standalone server.Example 14.1. Check for the
web
cache-containerThe profiles and configurations mentioned above include theweb
cache-container by default. Use the following command to verify its presence. If you use a different profile, substitute its name instead ofha
./profile=ha/subsystem=infinispan/cache-container=web/:read-resource(recursive=false,proxies=false,include-runtime=false,include-defaults=true)
If the result issuccess
the subsystem is present. Otherwise, you need to add it.Example 14.2. Add the
web
cache-containerUse the following three commands to enable theweb
cache-container to your configuration. Modify the name of the profile as appropriate, as well as the other parameters. The parameters here are the ones used in a default configuration./profile=ha/subsystem=infinispan/cache-container=web:add(aliases=["standard-session-cache"],default-cache="repl",module="org.jboss.as.clustering.web.infinispan")
/profile=ha/subsystem=infinispan/cache-container=web/transport=TRANSPORT:add(lock-timeout=60000)
/profile=ha/subsystem=infinispan/cache-container=web/replicated-cache=repl:add(mode="ASYNC",batching=true)
Example 14.3. Check for the
SSO
replicated-cacheRun the following Management CLI command:/profile=ha/subsystem=infinispan/cache-container=web/:read-resource(recursive=true,proxies=false,include-runtime=false,include-defaults=true)
Look for output like the following:"sso" => {
If you do not find it, the SSO replicated-cache is not present in your configuration.Example 14.4. Add the
SSO
replicated-cache/profile=ha/subsystem=infinispan/cache-container=web/replicated-cache=sso:add(mode="SYNC", batching=true)
- The
web
subsystem needs to be configured to use SSO. The following command enables SSO on the virtual server calleddefault-host
, and the cookie domaindomain.com
. The cache name issso
, and reauthentication is disabled./profile=ha/subsystem=web/virtual-server=default-host/sso=configuration:add(cache-container="web",cache-name="sso",reauthenticate="false",domain="domain.com")
- Each application which will share the SSO information must be configured to use the same <security-domain> in its
jboss-web.xml
deployment descriptor and the same Realm in itsweb.xml
configuration file.
Configure sso
under the web subsystem in the server profile. The ClusteredSingleSignOn
version is used when attribute cache-container
is present, otherwise standard SingleSignOn
class is used.
Example 14.5. Example Clustered SSO Configuration
/subsystem=web/virtual-server=default-host/sso=configuration:add(cache-container="web",cache-name="sso",reauthenticate="false",domain="domain.com")
Example 14.6. Example Non-Clustered SSO Configuration
/subsystem=web/virtual-server=default-host/sso=configuration:add(reauthenticate="false")
An application can programmatically invalidate a session by invoking method javax.servlet.http.HttpSession.invalidate()
.
14.5. About Kerberos
14.6. About SPNEGO
14.7. About Microsoft Active Directory
- Lightweight Directory Access Protocol (LDAP), for storing information about users, computers, passwords, and other resources.
- Kerberos, for providing secure authentication over the network.
- Domain Name Service (DNS) for providing mappings between IP addresses and host names of computers and other devices on the network.
14.8. Configure Kerberos or Microsoft Active Directory Desktop SSO for Web Applications
To authenticate your web or EJB applications using your organization's existing Kerberos-based authentication and authorization infrastructure, such as Microsoft Active Directory, you can use the JBoss Negotiation capabilities built into JBoss EAP 6. If you configure your web application properly, a successful desktop or network login is sufficient to transparently authenticate against your web application, so no additional login prompt is required.
There are a few noticeable differences between JBoss EAP 6 and earlier versions:
- Security domains are configured for each profile of a managed domain, or for each standalone server. They are not part of the deployment itself. The security domain a deployment should use is named in the deployment's
jboss-web.xml
orjboss-ejb3.xml
file. - Security properties are configured as part of a security domain. They are not part of the deployment.
- You can no longer override the authenticators as part of your deployment. However, you can add a NegotiationAuthenticator valve to your
jboss-web.xml
descriptor to achieve the same effect. The valve still requires the<security-constraint>
and<login-config>
elements to be defined in theweb.xml
. These are used to decide which resources are secured. However, the chosen auth-method will be overridden by the NegotiationAuthenticator valve in thejboss-web.xml
. - The
CODE
attributes in security domains now use a simple name instead of a fully-qualified class name. The following table shows the mappings between the classes used for JBoss Negotiation, and their classes.
Simple Name | Class Name | Purpose |
---|---|---|
Kerberos |
com.sun.security.auth.module.Krb5LoginModule
com.ibm.security.auth.module.Krb5LoginModule
|
Kerberos login module when using the Oracle JDK
Kerberos login module when using the IBM JDK
|
SPNEGO | org.jboss.security.negotiation.spnego.SPNEGOLoginModule | The mechanism which enables your Web applications to authenticate to your Kerberos authentication server. |
AdvancedLdap | org.jboss.security.negotiation.AdvancedLdapLoginModule | Used with LDAP servers other than Microsoft Active Directory. |
AdvancedAdLdap | org.jboss.security.negotiation.AdvancedADLoginModule | Used with Microsoft Active Directory LDAP servers. |
The JBoss Negotiation Toolkit
is a debugging tool which is available for download from https://community.jboss.org/servlet/JiveServlet/download/16876-2-34629/jboss-negotiation-toolkit.war. It is provided as an extra tool to help you to debug and test the authentication mechanisms before introducing your application into production. It is an unsupported tool, but is considered to be very helpful, as SPNEGO can be difficult to configure for web applications.
Procedure 14.1. Setup SSO Authentication for your Web or EJB Applications
Configure one security domain to represent the identity of the server. Set system properties if necessary.
The first security domain authenticates the container itself to the directory service. It needs to use a login module which accepts some type of static login mechanism, because a real user is not involved. This example uses a static principal and references a keytab file which contains the credential.The XML code is given here for clarity, but you should use the Management Console or Management CLI to configure your security domains.<security-domain name="host" cache-type="default"> <authentication> <login-module code="Kerberos" flag="required"> <module-option name="storeKey" value="true"/> <module-option name="useKeyTab" value="true"/> <module-option name="principal" value="host/testserver@MY_REALM"/> <module-option name="keyTab" value="/home/username/service.keytab"/> <module-option name="doNotPrompt" value="true"/> <module-option name="debug" value="false"/> </login-module> </authentication> </security-domain>
Configure a second security domain to secure the web application or applications. Set system properties if necessary.
The second security domain is used to authenticate the individual user to the Kerberos or SPNEGO authentication server. You need at least one login module to authenticate the user, and another to search for the roles to apply to the user. The following XML code shows an example SPNEGO security domain. It includes an authorization module to map roles to individual users. You can also use a module which searches for the roles on the authentication server itself.<security-domain name="SPNEGO" cache-type="default"> <authentication> <!-- Check the username and password --> <login-module code="SPNEGO" flag="requisite"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="serverSecurityDomain" value="host"/> </login-module> <!-- Search for roles --> <login-module code="UsersRoles" flag="required"> <module-option name="password-stacking" value="useFirstPass" /> <module-option name="usersProperties" value="spnego-users.properties" /> <module-option name="rolesProperties" value="spnego-roles.properties" /> </login-module> </authentication> </security-domain>
Specify the security-constraint and login-config in the
web.xml
Theweb.xml
descriptor contain information about security constraints and login configuration. The following are example values for each.<security-constraint> <display-name>Security Constraint on Conversation</display-name> <web-resource-collection> <web-resource-name>examplesWebApp</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>RequiredRole</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>SPNEGO</auth-method> <realm-name>SPNEGO</realm-name> </login-config> <security-role> <description> role required to log in to the Application</description> <role-name>RequiredRole</role-name> </security-role>
Specify the security domain and other settings in the
jboss-web.xml
descriptor.Specify the name of the client-side security domain (the second one in this example) in thejboss-web.xml
descriptor of your deployment, to direct your application to use this security domain.You can no longer override authenticators directly. Instead, you can add the NegotiationAuthenticator as a valve to yourjboss-web.xml
descriptor, if you need to. The<jacc-star-role-allow>
allows you to use the asterisk (*) character to match multiple role names, and is optional.<jboss-web> <security-domain>SPNEGO</security-domain> <valve> <class-name>org.jboss.security.negotiation.NegotiationAuthenticator</class-name> </valve> <jacc-star-role-allow>true</jacc-star-role-allow> </jboss-web>
Add a dependency to your application's
MANIFEST.MF
, to locate the Negotiation classes.The web application needs a dependency on classorg.jboss.security.negotiation
to be added to the deployment'sMETA-INF/MANIFEST.MF
manifest, in order to locate the JBoss Negotiation classes. The following shows a properly-formatted entry.Manifest-Version: 1.0 Build-Jdk: 1.6.0_24 Dependencies: org.jboss.security.negotiation
- As an alternative, add a dependency to your application by editing the
META-INF/jboss-deployment-structure.xml
file:<?xml version="1.0" encoding="UTF-8"?> <jboss-deployment-structure> <deployment> <dependencies> <module name='org.jboss.security.negotiation'/> </dependencies> </deployment> </jboss-deployment-structure>
Your web application accepts and authenticates credentials against your Kerberos, Microsoft Active Directory, or other SPNEGO-compatible directory service. If the user runs the application from a system which is already logged into the directory service, and where the required roles are already applied to the user, the web application does not prompt for authentication, and SSO capabilities are achieved.
14.9. Configure SPNEGO Fall Back to Form Authentication
Procedure 14.2. SPNEGO security with fall back to form authentication
Set up SPNEGO
Refer the procedure described in Section 14.8, “Configure Kerberos or Microsoft Active Directory Desktop SSO for Web Applications”Modify
web.xml
Add alogin-config
element to your application and setup the login and error pages in web.xml:<login-config> <auth-method>SPNEGO</auth-method> <realm-name>SPNEGO</realm-name> <form-login-config> <form-login-page>/login.jsp</form-login-page> <form-error-page>/error.jsp</form-error-page> </form-login-config> </login-config>
Add web content
Add references oflogin.html
anderror.html
toweb.xml
. These files are added to web application archive to the place specified inform-login-config
configuration. For more information refer Enable Form-based Authentication section in the Security Guide for JBoss EAP 6. A typicallogin.html
looks like this:<html> <head> <title>Vault Form Authentication</title> </head> <body> <h1>Vault Login Page</h1> <p> <form method="post" action="j_security_check"> <table> <tr> <td>Username</td><td>-</td> <td><input type="text" name="j_username"></td> </tr> <tr> <td>Password</td><td>-</td> <td><input type="password" name="j_password"></td> </tr> <tr> <td colspan="2"><input type="submit"></td> </tr> </table> </form> </p> <hr> </body> </html>
Note
Chapter 15. Single Sign-On with SAML
15.1. About Security Token Service (STS)
- Type of the request, such as Issue, Renew, and so on.
- Type of the token.
- Lifetime of the issued token.
- Information about the service provider that requested the token.
- Information used to encrypt the generated token.
Note
provider
attribute. The value specified in this parameter is passed to the relevant KeyStore.getInstance("PKCS11")
calls and the key and trust store are initialized.
java.security
policy file. Oracle's Java PKCs#11 Reference Guide document may be a useful resource for this information.
RequestSecurityToken
element. The sample request contains two other WS-Trust elements: RequestType
, which specifies that this request is an Issue request, and TokenType
, which specifies the type of the token to be issued.
Example 15.1. WS-Trust security token request message
<S11:Envelope xmlns:S11=".." xmlns:wsu=".." xmlns:wst=".."> <S11:Header> ... </S11:Header> <S11:Body wsu:Id="body"> <wst:RequestSecurityToken Context="context"> <wst:TokenType>http://www.tokens.org/SpecialToken</wst:TokenType> <wst:RequestType> http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue </wst:RequestType> </wst:RequestSecurityToken> </S11:Body> </S11:Envelope>
Example 15.2. Security token response message
<wst:RequestSecurityTokenResponse Context="context" xmlns:wst=".." xmlns:wsu=".."> <wst:TokenType>http://www.tokens.org/SpecialToken</wst:TokenType> <wst:RequestedSecurityToken> <token:SpecialToken xmlns:token="..."> ARhjefhE2FEjneovi&@FHfeoveq3 </token:SpecialToken> </wst:RequestedSecurityToken> <wst:Lifetime> <wsu:Created>...</wsu:Created> <wsu:Expires>...</wsu:Expires> </wst:Lifetime> </wst:RequestSecurityTokenResponse>
TokenType
element specifies the type of the issued token, while the RequestedSecurityToken
element contains the token itself. The format of the token depends on the type of the token. The Lifetime
element specifies when the token was created and when it expires.
The following are the steps in which the security token requests are processed:
- A client sends a security token request to
PicketLinkSTS
.
PicketLinkSTS
parses the request message, generating a JAXB object model.
PicketLinkSTS
reads the configuration file and creates theSTSConfiguration
object, if needed. Then it obtains a reference to theWSTrustRequestHandler
from the configuration and delegates the request processing to the handler instance.
- The request handler uses the
STSConfiguration
to set default values when needed (for example, when the request doesn't specify a token lifetime value).
- The
WSTrustRequestHandler
creates theWSTrustRequestContext
, setting theJAXB
request object and the caller principal it received fromPicketLinkSTS
.
- The
WSTrustRequestHandler
uses theSTSConfiguration
to get theSecurityTokenProvider
that must be used to process the request based on the type of the token that is being requested. Then it invokes the provider, passing the constructedWSTrustRequestContext
as a parameter.
- The
SecurityTokenProvider
instance process the token request and stores the issued token in the request context.
- The
WSTrustRequestHandler
obtains the token from the context, encrypts it if needed, and constructs the WS-Trust response object containing the security token.
PicketLinkSTS
dictates the response generated by the request handler and returns it to the client.
15.2. Configure Security Token Service (STS)
picketlink.xml
file, which belongs in the WEB-INF
directory of the deployed application. The following are the elements that can be configured in the picketlink.xml
file.
Note
PicketLinkSTS
: This is the root element. It defines some properties that allows the STS administrator to set a the following default values:STSName
: A string representing the name of the security token service. If not specified, the defaultPicketLinkSTS
value is used.TokenTimeout
: The token lifetime value in seconds. If not specified, the default value of 3600 (one hour) is used.EncryptToken
: A boolean specifying whether issued tokens are to be encrypted or not. The default value is false.
KeyProvider
: This element and all its sub elements are used to configure the keystore that are used by PicketLink STS to sign and encrypt tokens. Properties like the keystore location, its password, and the signing (private key) alias and password are all configured in this section.RequestHandler
: This element specifies the fully qualified name of theWSTrustRequestHandler
implementation to be used. If not specified, the defaultorg.picketlink.identity.federation.core.wstrust.StandardRequestHandler
is used.TokenProvider
: This section specifies theTokenProvider
implementations that must be used to handle each type of security token. In the example we have two providers - one that handles tokens of typeSpecialToken
and one that handles tokens of typeSAMLV2.0
. TheWSTrustRequestHandler
calls thegetProviderForTokenType
(String type) method ofSTSConfiguration
to obtain a reference to the appropriateTokenProvider
.TokenTimeout
: This is used by theWSTrustRequestHandler
when no Lifetime has been specified in the WS-Trust request. It creates a Lifetime instance that has the current time as the creation time and expires after the specified number of seconds.ServiceProviders
: This section specifies the token types that must be used for each service provider (the Web service that requires a security token). When a WS-Trust request does not contain the token type, theWSTrustRequestHandler
must use the service provider endpoint to find out the type of the token that must be issued.EncryptToken
: This is used by theWSTrustRequestHandler
to decide if the issued token must be encrypted or not. If true, the public key certificate (PKC) of the service provider is used to encrypt the token.
Example 15.3. STS Configuration
<PicketLinkSTS xmlns="urn:picketlink:identity-federation:config:1.0" STSName="Test STS" TokenTimeout="7200" EncryptToken="true"> <KeyProvider ClassName="org.picketlink.identity.federation.bindings.tomcat.KeyStoreKeyManager"> <Auth Key="KeyStoreURL" Value="keystore/sts_keystore.jks"/> <Auth Key="KeyStorePass" Value="testpass"/> <Auth Key="SigningKeyAlias" Value="sts"/> <Auth Key="SigningKeyPass" Value="keypass"/> <ValidatingAlias Key="http://services.testcorp.org/provider1" Value="service1"/> <ValidatingAlias Key="http://services.testcorp.org/provider2" Value="service2"/> </KeyProvider> <RequestHandler>org.picketlink.identity