Merge pull request #72 from jenmalloy/RHSSO-906

fixed RHSSO-906

securing_apps/topics/oidc/java/fuse/camel.adoc

@@ -2,7 +2,7 @@
 
 ===== Securing an Apache Camel Application
 
-You can secure your Apache camel endpoint using the http://camel.apache.org/jetty.html[camel-jetty] component by adding securityHandler with `KeycloakJettyAuthenticator` and the proper security constraints injected. You can add the `OSGI-INF/blueprint/blueprint.xml` file to your camel application with a similar configuration as below. The roles, security constraint mappings, and {{book.project.name}} adapter configuration might be slightly different depending on your environment and needs.
+You can secure Apache camel endpoints implemented with the http://camel.apache.org/jetty.html[camel-jetty] component by adding securityHandler with `KeycloakJettyAuthenticator` and the proper security constraints injected. You can add the `OSGI-INF/blueprint/blueprint.xml` file to your camel application with a similar configuration as below. The roles, security constraint mappings, and {{book.project.name}} adapter configuration might differ slightly depending on your environment and needs.
 
 For example:
 
@@ -95,11 +95,11 @@ org.osgi.service.event,
 
 ===== Camel RestDSL
 
-Camel RestDSL is a Camel feature to define your REST endpoints in a fluent way. But you still must use specific implementation classes and provide instructions on how to integrate with {{book.project.name}}.
+Camel RestDSL is a Camel feature used to define your REST endpoints in a fluent way. But you must still use specific implementation classes and provide instructions on how to integrate with {{book.project.name}}.
 
-The way to configure the integration mechanism depends on the Camel component with which you configure your RestDSL-defined routes to work.
+The way to configure the integration mechanism depends on the Camel component for which you configure your RestDSL-defined routes.
 
-This is an example that shows how to do so while using the Jetty engine, with reference to some beans defined in the example above.
+The following example shows how to configure integration using the jetty component, with references to some of the beans defined in previous Blueprint example.
 
 [source,xml]
 ----

securing_apps/topics/oidc/java/fuse/classic-war.adoc

@@ -4,7 +4,10 @@
 
 The needed steps to secure your WAR application are:
 
-. Declare needed security constraints in the `/WEB-INF/web.xml` file. You also need to declare login-config and all the roles inside security-role.
+. In the `/WEB-INF/web.xml` file, declare the necessary:
+* security constraints in the <security-constraint> element
+* login configuration in the <login-config> element
+* security roles in the <security-role> element.
 +
 For example:
 +
@@ -85,9 +88,9 @@ org.keycloak.*;version="{{book.project.versionMvn}}",
 [[config_external_adapter]]
 ====== Configuring the External Adapter
 
-If you do not want the `keycloak.json` adapter configuration file to be bundled inside your WAR application, but instead available externally and loaded based on naming conventions, use this configuration method.
+If you do not want the `keycloak.json` adapter configuration file to be bundled inside your WAR application, but instead made available externally and loaded based on naming conventions, use this configuration method.
 
-To enable the functionality, add this section to your `web.xml` file:
+To enable the functionality, add this section to your `/WEB_INF/web.xml` file:
 
 [source,xml]
 ----

securing_apps/topics/oidc/java/fuse/cxf-builtin.adoc

@@ -2,8 +2,7 @@
 [[_fuse_adapter_cxf_builtin]]
 ===== Securing an Apache CXF Endpoint on the Default Jetty Engine
 
-Some services automatically come with deployed servlets on startup. One such service is the CXF servlet running in the $$http://localhost:8181/cxf$$ context. Securing such endpoints can be complicated. One approach, which {{book.project.name}} is currently using,
+Some services automatically come with deployed servlets on startup. One such service is the CXF servlet running in the $$http://localhost:8181/cxf$$ context. Securing such endpoints can be complicated. One approach, which {{book.project.name}} is currently using, is ServletReregistrationService, which undeploys a built-in servlet at startup, enabling you to redeploy it on a context secured by {{book.project.name}}.
-is providing ServletReregistrationService, which undeploys a built-in servlet at startup, so you are able to redeploy it on a context secured by {{book.project.name}}.
 
 The configuration file `OSGI-INF/blueprint/blueprint.xml` inside your application might resemble the one below. Note that it adds the JAX-RS `customerservice` endpoint, which is endpoint-specific to your application, but more importantly, secures the entire `/cxf` context.
 
@@ -74,7 +73,7 @@ The configuration file `OSGI-INF/blueprint/blueprint.xml` inside your applicatio
 As a result, all other CXF services running on the default CXF HTTP destination are also secured. Similarly, when the application is undeployed, the entire `/cxf` context becomes unsecured as well. For this reason, using your own Jetty engine for your applications as described in <<fake/../cxf-separate.adoc#_fuse_adapter_cxf_separate,Secure CXF Application on separate Jetty Engine>> then gives you more
 control over security for each individual application.
 
-* The `WEB-INF` directory might need to be inside your project (even if your project is not a web application). You also might need to edit the `/WEB-INF/jetty-web.xml` and `/WEB-INF/keycloak.json` files in a similar way as in <<fake/../classic-war.adoc#_fuse_adapter_classic_war,Classic WAR application>>.
+* The `WEB-INF` directory might need to be inside your project (even if your project is not a web application). You might also need to edit the `/WEB-INF/jetty-web.xml` and `/WEB-INF/keycloak.json` files in a similar way as in <<fake/../classic-war.adoc#_fuse_adapter_classic_war,Classic WAR application>>.
 Note that you do not need the `web.xml` file as the security constraints are declared in the blueprint configuration file.
 
 * The `Import-Package` in `META-INF/MANIFEST.MF` must contain these imports:
@@ -92,3 +91,4 @@ org.keycloak.*;version="{{book.project.versionMvn}}",
 org.keycloak.adapters.jetty;version="{{book.project.versionMvn}}",
 *;resolution:=optional
 ----
+

securing_apps/topics/oidc/java/fuse/cxf-separate.adoc

@@ -2,9 +2,9 @@
 [[_fuse_adapter_cxf_separate]]
 ===== Securing an Apache CXF Endpoint on a Separate Jetty Engine
 
-To run your CXF endpoints secured by {{book.project.name}} on separate Jetty engine, complete the following steps:
+To run your CXF endpoints secured by {{book.project.name}} on separate Jetty engines, complete the following steps:
 
-. Add `META-INF/spring/beans.xml` to your application and then declare `httpj:engine-factory` with Jetty SecurityHandler with injected `KeycloakJettyAuthenticator` inside. The configuration might resemble this one for a CXF JAX-WS application:
+. Add `META-INF/spring/beans.xml` to your application, and in it,  declare `httpj:engine-factory` with Jetty SecurityHandler with injected `KeycloakJettyAuthenticator`. The configuration for a CFX JAX-wS application might resemble this one:
 +
 [source,xml]
 ----

securing_apps/topics/oidc/java/fuse/fuse-admin.adoc

@@ -13,14 +13,14 @@ To enable SSH authentication, complete the following steps:
 . In  {{book.project.name}} create a client (for example, `ssh-jmx-admin-client`), which will be used for SSH authentication.
 This client needs to have `Direct Access Grants Enabled` selected to `On`.
 
-. Update or specify this property in the `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` file:
+. In the `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` file, update or specify this property:
 +
 [source]
 ----
 sshRealm=keycloak
 ----
 
-. Add the `$FUSE_HOME/etc/keycloak-direct-access.json` file with the content similar to the following (based on your environment and {{book.project.name}} client settings):
+. Add the `$FUSE_HOME/etc/keycloak-direct-access.json` file with content similar to the following (based on your environment and {{book.project.name}} client settings):
 +
 [source,json]
 ----
@@ -36,7 +36,7 @@ sshRealm=keycloak
 ----
 This file specifies the client application configuration, which is used by JAAS DirectAccessGrantsLoginModule from the `keycloak` JAAS realm for SSH authentication.
 
-. Start Fuse and install the `keycloak` JAAS realm into Fuse. The easiest way is to install the `keycloak-jaas` feature, which has the JAAS realm predefined; you can override it by using your own `keycloak` JAAS realm with higher ranking. For details see the JBoss Fuse documentation. 
+. Start Fuse and install the `keycloak` JAAS realm. The easiest way is to install the `keycloak-jaas` feature, which has the JAAS realm predefined. You can override the feature's predefined realm by using your own `keycloak` JAAS realm with higher ranking. For details see the https:access.redhat.com/documentation/en-us/red_hat_jboss_fuse/6.3/html-single/security_guide/#ESBSecureContainer[JBoss Fuse documentation]. 
 +
 Use these commands in the Fuse terminal:
 +
@@ -54,9 +54,9 @@ ssh -o PubkeyAuthentication=no -p 8101 admin@localhost
 
 . Log in with password `password`.
 
-NOTE: On some later operating systems, you might also need to use this option of SSH command `-o HostKeyAlgorithms=+ssh-dss` because later SSH clients do not allow using the `ssh-dss` algorithm by default, but it is currently used by default in {{book.fuseVersion}}.
+NOTE: On some later operating systems, you might also need to use the SSH command's -o option `-o HostKeyAlgorithms=+ssh-dss` because later SSH clients do not allow use of the `ssh-dss` algorithm, by default. However, by default, it is currently used in {{book.fuseVersion}}.
 
-Note that the user needs to have realm role `admin` to perform all operations or another role to perform a subset of operations (for example, the viewer role to be able to only run read-only Karaf commands). The available roles are configured in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` or `$FUSE_HOME/etc/system.properties`.
+Note that the user needs to have realm role `admin` to perform all operations or another role to perform a subset of operations (for example, the *viewer* role that restricts the user to run only read-only Karaf commands). The available roles are configured in `$FUSE_HOME/etc/org.apache.karaf.shell.cfg` or `$FUSE_HOME/etc/system.properties`.
 
 ====== Using JMX Authentication
 
@@ -64,7 +64,7 @@ JMX authentication might be necessary if you want to use jconsole or another ext
 
 To use JMX authentication, complete the following steps:
 
-. In the `$FUSE_HOME/etc/org.apache.karaf.management.cfg` file, change this property:
+. In the `$FUSE_HOME/etc/org.apache.karaf.management.cfg` file, change the jmxRealm property to:
 +
 [source]
 ----

securing_apps/topics/oidc/java/fuse/hawtio.adoc

@@ -16,7 +16,7 @@ hawtio.rolePrincipalClasses=org.keycloak.adapters.jaas.RolePrincipal,org.apache.
 
 . Create a client in the {{book.project.name}} administration console in your realm. For example, in the {{book.project.name}} `demo` realm, create a client `hawtio-client`, specify `public` as the Access Type, and specify a redirect URI pointing to Hawtio: \http://localhost:8181/hawtio/*. You must also have a corresponding Web Origin configured (in this case, \http://localhost:8181).
 
-. Create the `keycloak-hawtio-client.json` file in the `$FUSE_HOME/etc` directory using the similar content as below. Change the `realm`, `resource`, and `auth-server-url` properties according to your {{book.project.name}} environment. The `resource` property must point to the client created in the previous step. This file is used by the client (Hawtio Javascript application) side.
+. Create the `keycloak-hawtio-client.json` file in the `$FUSE_HOME/etc` directory using content similar to that shown in the example below. Change the `realm`, `resource`, and `auth-server-url` properties according to your {{book.project.name}} environment. The `resource` property must point to the client created in the previous step. This file is used by the client (Hawtio Javascript application) side.
 +
 [source,json]
 ----
@@ -29,7 +29,7 @@ hawtio.rolePrincipalClasses=org.keycloak.adapters.jaas.RolePrincipal,org.apache.
 }
 ----
 
-. Create the `keycloak-hawtio.json` file in the `$FUSE_HOME/etc` dicrectory using similar content as below. Change the `realm` and `auth-server-url` properties according to your {{book.project.name}} environment. This file is used by the adapters on the server (JAAS Login module) side.
+. Create the `keycloak-hawtio.json` file in the `$FUSE_HOME/etc` dicrectory using content similar to that shown in the example below. Change the `realm` and `auth-server-url` properties according to your {{book.project.name}} environment. This file is used by the adapters on the server (JAAS Login module) side.
 +
 [source,json]
 ----
@@ -44,7 +44,7 @@ hawtio.rolePrincipalClasses=org.keycloak.adapters.jaas.RolePrincipal,org.apache.
 }
 ----
 
-. Start {{book.fuseVersion}} and install the keycloak feature if you have not already. The commands in Karaf terminal are similar to this example:
+. Start {{book.fuseVersion}} and install the keycloak feature if you have not already done so. The commands in Karaf terminal are similar to this example:
 +
 [source, subs="attributes"]
 ----
@@ -60,13 +60,16 @@ Note that the user needs to have the proper realm role to successfully authentic
 
 To run Hawtio on the Wildfly 10 server, complete the following steps:
 
-. Set up {{book.project.name}} as in the Securing the Hawtio Administration Console section above. The following assumptions apply: you have a {{book.project.name}} realm `demo` and client `hawtio-client`, and  your {{book.project.name}} is running on `localhost:8080` while the Wildfly server with deployed Hawtio will be running on `localhost:8181`.
+. Set up {{book.project.name}} as described in the previous section, Securing the Hawtio Administration Console. It is assumed that: 
+* you have a {{book.project.name}} realm `demo` and client `hawtio-client`
+* your {{book.project.name}} is running on `localhost:8080`
+* the Wildfly server with deployed Hawtio will be running on `localhost:8181`.
 
-. Copy the `hawtio.war` archive to the `$EAP_HOME/standalone/configuration` directory. For more details about deploying Hawtio see the Fuse Hawtio documentation.
+. Copy the `hawtio.war` archive to the `$EAP_HOME/standalone/configuration` directory. For more details about deploying Hawtio see the https://access.redhat.com/documentation/en-us/red_hat_jboss_fuse/6.3/html-single/deploying_into_a_web_server/eapcamelsubsystem#idm140313338064000[Fuse Hawtio documentation].
 
 . Copy the `keycloak-hawtio.json` and `keycloak-hawtio-client.json` files with the above content to the `$EAP_HOME/standalone/configuration` directory.
 
-. Install the {{book.project.name}} adapter subsystem to your Wildfly server as described in the <<fake/../../jboss-adapter.adoc#_jboss_adapter,JBoss adapter documentation>>
+. Install the {{book.project.name}} adapter subsystem to your Wildfly server as described in the <<fake/../../jboss-adapter.adoc#_jboss_adapter,JBoss adapter documentation>>.
 
 . In the `$EAP_HOME/standalone/configuration/standalone.xml` file configure the system properties as in this example:
 +