Bug 972758 - [Doc Bug Fix] SSL for Management Interfaces [NEEDINFO]
[Doc Bug Fix] SSL for Management Interfaces
Status: CLOSED CURRENTRELEASE
Product: JBoss Enterprise Application Platform 6
Classification: JBoss
Component: Documentation (Show other bugs)
6.1.0
Unspecified Unspecified
unspecified Severity urgent
: ER7
: EAP 6.3.0
Assigned To: Russell Dickenson
Hynek Mlnarik
: Documentation, FutureFeature
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2013-06-10 10:24 EDT by Eric Rich
Modified: 2015-08-31 23:34 EDT (History)
10 users (show)

See Also:
Fixed In Version:
Doc Type: Enhancement
Doc Text:
Story Points: ---
Clone Of:
Environment:
Instance Name: Not Defined Build: CSProcessor Builder Version 1.8 Build Name: 11865, Administration and Configuration Guide-6.1-3 Build Date: 23-05-2013 10:40:22
Last Closed: 2014-08-06 10:35:12 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---
rdickens: needinfo? (tfonteyn)


Attachments (Terms of Use)

  None (edit)
Description Eric Rich 2013-06-10 10:24:50 EDT
Title: Secure the Management Interfaces

Section does not cover how to configure the connector for the management interfaces. 

Describe the issue:

When trying to configure SSL what connector is to be configured. 

Suggestions for improvement:

Since there is not connector explain how the management interfaces are configured by the Application Real and Management Realm (or custom Realm) configurations. 

Additional information:

https://access.redhat.com/site/solutions/229963 details the SSL configuration.
Comment 2 Russell Dickenson 2014-05-26 23:47:50 EDT
I have worked through the KB article, correcting instructions as I go, and have successfully configured the SSL connection in 'standalone' mode. However I have been unable to do the same for 'domain' mode, hence the email below to Darran Lofthouse.

Note that if you want to recreate the *example* configuration for 'standalone' mode, you must first have entered the following management CLI command in the path "...\standalone\configuration":

"keytool -genkey -alias jboss -keyalg RSA -keystore keystore.jks -storepass changeit"


-- 8< ------ 8< ------ 8< ------ 8< ------ 8< ------ 8< ------ 8< ------

Darran,

I hope you might be able to help me with this BZ ticket, which requests documentation of configuring the management console to use HTTPS rather than HTTP. In my work so far I have been using the KB article [1] as my main source of information.

If I understand correctly, a prerequisite of this configuration is to have stored a password in the JBoss EAP vault.

For standalone mode, I have noted the necesssary steps as follows:

1. Configure the management console to bind to 'HTTPS' instead of 'HTTP' interface.

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

2. Point the management realm to the keystore:

Management CLI commands
-----------------------
/core-service=management/security-realm=ManagementRealm/server-identity=ssl:add(keystore-path=keystore.jks,keystore-relative-to="jboss.server.config.dir",keystore-password=changeit,alias=mykey)
-----------------------

Note that although in item 2 the name of the keystore file and associated password are in plain text, I will be amending the instructions to instead use a vault, as documented at [2].

My problem is that I can't adapt the CLI commands to suit a domain configuration. Can you help guide me in the right direction?


[1] https://access.redhat.com/site/solutions/229963
[2] http://docbuilder.usersys.redhat.com/22508/#Store_and_Resolve_Sensitive_Strings_In_Your_Applications1
Comment 3 Tom Fonteyne 2014-05-27 08:10:01 EDT
keytool -genkeypair -alias jboss -keyalg RSA -keystore keystore.jks -storepass changeit -validity 365

"genkey" was valid, but deprecated. "genkeypair" should be used instead.
I would also add:  -validity <valDays>
with a number of days to make sure users don't end up with the default = 3 months.


/host=master/core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding,value=management-https)

/host=master/core-service=management/management-interface=http-interface:undefine-attribute(name=socket-binding)

/host=master/core-service=management/security-realm=ManagementRealm/server-identity=ssl:add(keystore-path=keystore.jks,keystore-relative-to="jboss.domain.config.dir",keystore-password=changeit,alias=mykey)

master being the default name for the domain controller

note the "jboss.domain.config.dir" which corresponds with
$JBOSS_HOME/domain/configuration

When doing the Vault, you also use the /host=master prefix
Comment 4 Russell Dickenson 2014-05-28 20:11:13 EDT
Attention: Tom

Thank you for that information. It seems the configuration of SSL for the management interfaces is already documented in the Security Guide. I am reviewing those instructions to see if they ought to be updated and/or simplified.


Regards,

Russell
Comment 7 Russell Dickenson 2014-06-05 23:44:15 EDT
Affected document: Security Guide

I have amended the instructions for accessing the management console via SSL as follows:

* Merged some instructions so that they could be applied to either a standalone or domain mode configuration.
* Added steps to use two keystores, with the password of the first keystore stored in a vault.
* Replaced some XML configuration examples with management CLI commands.

When the Security Guide is next built, I will move this BZ ticket to ON_QA.

[1] http://docbuilder.usersys.redhat.com/22558/#Configure_the_Management_Console_for_HTTPS_in_Standalone_mode
Comment 9 Petr Kremensky 2014-06-17 06:37:06 EDT
Hi Russell,
I noticed you are adding the ssl server identity twice. First in step 4. and than in step 7. Going through the procedure step-be-step user gets the 'JBAS014803: Duplicate resource' error message. You should use write-attribute operation instead
/core-service=management/security-realm=ManagementRealm/server-identity=ssl:write-attribute(name=keystore-password, value="${VAULT::block_console::password_console::1}")

Also Vault have to be initialized first, or user gets the 'JBAS013322: Vault is not initialized' error.

Some reference file that might also help https://mojo.redhat.com/docs/DOC-955880

@hmlnarik may give you more detailed feedback.

Petr
Comment 10 Hynek Mlnarik 2014-06-17 13:13:06 EDT
In addition to comment #9, please add explanations into both beginning (1) and end (2) of this section - why should the user want to configure the mgmt console for https, i.e. what is to be achieved by executing the steps to (1), and what can/should the user do with the result to (2).
Comment 11 Russell Dickenson 2014-06-24 23:01:40 EDT
Attention: Petr

Thank you for your feedback. I will make the changes you recommended.

Attention: Hynek

Thank you for your feedback. I will add explanations to this content as to why you might configure the management interfaces for HTTPS.

Having reviewed this content again myself, I see a number of further issues:
* I don't give any explanation as to which file the XML sample in step 2 affects.
* The XML sample in step 2 should in fact be management CLI commands.
* In the introduction to the procedure I state that the management CLI instructions apply to both 'standalone' and 'domain' mode, then immediately provide separate instructions for each mode.
* Not all the parameters which must be adapted by the customer to their specific environment have been marked or explained as such.

I will go ahead with these changes and put the ticket back to ON_QA status one they are resolved.
Comment 12 Russell Dickenson 2014-06-24 23:11:15 EDT
I have corrected the management CLI command mentioned in comment 9.
Topic: Configure the Management Console for HTTPS [22638] (revision 678038)
Comment 13 sgilda 2014-06-26 09:30:31 EDT
Hi Russell, 

This bug seems to impact both the Administration and Configuration Guide and the Security Guide, so I'm adding the Security Guide to the Component list.

It appears that you have addressed all the issues, but I am not sure if this one is ready to move to ON_QA or not. 

I'll post the verification links and let you decide. When ready, the fixes can be verified at the following links:

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#Secure_the_Management_Interfaces2

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Security_Guide/index.html#Configure_the_Management_Console_for_HTTPS_in_Standalone_mode
Comment 14 Russell Dickenson 2014-06-26 20:59:27 EDT
To complete this ticket I need to address the following point from comment 9:

"Also Vault have to be initialized first, or user gets the 'JBAS013322: Vault is not initialized' error."
Comment 15 Russell Dickenson 2014-06-27 00:50:37 EDT
In addition to the changes proposed in comment 14, I realise that some of the content in topic 22638 duplicates content in the A&C Guide. However the topic in the A&C Guide provides instructions on creating a keystore *AND* SSL certificate. To resolve the duplication I intend splitting topic 9037 into 2 parts and making part 1 (Create a Keystore) a pre-req of topic 22638.
Comment 16 Russell Dickenson 2014-06-30 01:43:31 EDT
I have completed all changes to the following topic:
* Configure the Management Console for HTTPS [22638]

In comment 15 I stated that I intended splitting a toic into 2. I have decided against this, deciding instead to leave that topic alone.

As per comment 10 I have added a brief explanation as to why switching to HTTPS is an advantage.

I have tested this procedure twice and confirmed that having completed it, access to the (web) management console via URL "localhost:8080" is instead directed to "localhost:9443".

Once the amended content is available via the docs-devel site I will move this ticket to ON_QA.
Comment 17 Russell Dickenson 2014-06-30 21:16:12 EDT
I need advice on the procedure I have documented at [1]. In step 7 I specify that the user is to edit the main configuration file. This is *not* the recommended method of configuration, but I can't determine the appropriate management CLI commmands.

Tom, can you help identify how I can convert the XML changes into appropriate management CLI commands?


[1] http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Security_Guide/index.html#Configure_the_Management_Console_for_HTTPS_in_Standalone_mode
Comment 19 Russell Dickenson 2014-07-01 22:54:10 EDT
Attention: Petr

Thank you. For whatever reason I just couldn't get the combination of management CLI parameters correct. I will amend the documentation to suit and re-test the process. If it works I will put this ticket back to ON_QA when it is available on the docs-devel site.
Comment 20 Russell Dickenson 2014-07-02 01:07:17 EDT
With fantastic assistance from Petr Kremensky, I replaced an XML editing section with management CLI commands. I added some more instances of "The expected outcome is....". I also added a note prior to the management CLI commands that the customer must first ensure that the JBoss EAP instance is running.

Topic(s):
* Configure the Management Console for HTTPS [22638]

When the guide is rebuilt the amended text will be available at [1].


[1] http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Security_Guide/index.html#Configure_the_Management_Console_for_HTTPS_in_Standalone_mode
Comment 21 Russell Dickenson 2014-07-02 02:49:14 EDT
As per comment 20, I believe I have completed work on this BZ ticket. I have tested the procedure using a 'standalone' instance.

The amended text is available for review in revision 6.3.0-29 of the Security Guide at [1].


[1] http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Security_Guide/index.html#Configure_the_Management_Console_for_HTTPS_in_Standalone_mode
Comment 22 FIlip Bogyai 2014-07-03 05:55:14 EDT
The section correctly provide information about how to configure the Management Console for HTTPS, but the information about encrypting passwords with vault in Security Realm configuration should not be in this section. 

Security vault is used only for securing passwords in EAP configuration, which is not needed to set up HTTPS for Management Console. Moreover there is already whole section ⁠10.7. Password Vaults for Sensitive Strings about Vault, so I suggest to remove duplicate information about configuring vault and only add a note at the end of the section that vault can be used for encrypting keystore password. This is also because in the procedure you have only set up this vault and not actually encrypt keystore password that is used in Security Realm, so the information here are not completed.

Remove duplicate information about configuring vault, which are in steps 2, 3, 7 in section ⁠10.9. Configure the Management Console for HTTPS.
Comment 23 FIlip Bogyai 2014-07-03 06:05:24 EDT
Also remove the prerequisites at the beginning, because they are not needed to set up HTTPS for Management Console. The links in prerequisites can be used at the end of the section as Optional Step: Use Password Vault to mask keystore password.
Comment 24 Russell Dickenson 2014-07-03 19:33:35 EDT
In response to comments 22 and 23 I have:

* Removed the prerequisites as I confirmed that they are *not* required.
* Removed the unnecessary steps regarding use of the vault. Instead I added an admonition to the end of the topic which directs the reader to the relevant topic(s).

When the guide is rebuilt the amended text will be available at []1.


[1] http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Security_Guide/index.html#Configure_the_Management_Console_for_HTTPS_in_Standalone_mode


PS - Many thanks to FIlip Bogyai for his excellent review and feedback.
Comment 25 David Michael 2014-07-04 01:03:58 EDT
Topic modified/updated:  ⁠11.9. Configure the Management Console for HTTPS

Summary of changes/updates:
- In response to comments 22 and 23 I have:
* Removed the prerequisites as I confirmed that they are *not* required.
* Removed the unnecessary steps regarding use of the vault. Instead I added an admonition to the end of the topic which directs the reader to the relevant topic(s).

Link to topic: http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Security_Guide/index.html#Configure_the_Management_Console_for_HTTPS_in_Standalone_mode
Comment 26 Hynek Mlnarik 2014-07-04 03:44:45 EDT
Verified in Revision 6.3.0-32

Note You need to log in before you can comment on or make changes to this bug.