Link: Added: This issue is a dependency of JBEPP-801

New content has been added to the Reference Guide with this information:
http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platform/5.1/html-single/Reference_Guide/index.html#id3187873

In step 3 of the Procedure the header line is not matching the two options mentioned afterwards, as only the second option is about changing from FORM to BASIC auth:
"Switch the Java Authentication and Authorization Service (JAAS) authentication from FORM to BASIC. "

Instead, the two options could be described as:
"To integrate with the JBoss SSO valve, one of the following configuration changes in the Java Authentication and Authorization Service (JAAS) configuration of EPP are necessary:

a. Either call the JAAS authentication directly:
...

b. Or switch from FORM to BASIC authentication:

Also, the chapter could be named 'Enabling SSO using JBoss SSO valve'.

Thanks Martin.
Updated content available at:
http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platform/5.1/html/Reference_Guide/ch14s07s02.html

There are some fixes according to Martin's recommendation but few things are still here. So I am reopening:

1) It can be good to add more informations for customers, who are not aware of SSO valve. I think it makes sense to provide some info what it is good for and how they could test it in EPP. When I am looking at the chapter from beginner's perspective, I am seeing only steps for integration but I am not seeing any context informations why I should do these steps and how it is good for etc.

1.a) It can be good to start with some overall informations and provide link to EAP5 docs where are detailed informations about SSO valve. Maybe something like: "JBoss SSO valve is usefull for authenticate user on one EPP5 node in cluster and being automatically authenticated on other EPP5 nodes in same cluster. After successful authentication to EPP5 is user also authenticated in other web applications, which requires authentication. Important condition is that these applications will use same roles as EPP5, otherwise you may end with 403 errors. More info about SSO valve is at 
http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Platform/5/html/Administration_And_Configuration_Guide/clustering-http-sso.html " What do you think?

1.b) It may be good to add steps for test SSO valve integration, so that customers can easily test it. So that it can be good to add these steps at the end: 
"You can test EPP5 with SSO valve by doing these steps:

- Copy server configuration <PROFILE>, where you made previous steps, into configurations called node1 and node2. So that you will have directories /<JBOSS_HOME>/server/node1 and /<JBOSS_HOME>/server/node2

- Run configuration node1 on local machine with command: ./run.sh -c node1 -Djboss.service.binding.set=ports-default -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &

- Run configuration node2 on local machine with command: ./run.sh -c node2 -Djboss.service.binding.set=ports-01 -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=1 &

- Go to http://localhost:8080/portal/private/classic and authenticate as user "root" with password "gtn"

- Go to http://localhost:8180/portal/private/classic . You can see that you will be automatically authenticated as user root on this node as well.

If you want to use real cluster with more different machines like http://machine1.yourdomain.com:8080/portal/private/classic and http://machine2.yourdomain.com:8080/portal/private/classic, you will need to use attribute cookieDomain of SSO valve in file server.xml . So that SSO valve configuration in your server.xml file in both node1 and node2 should look like this:

<Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" cookieDomain="yourdomain.com" />

This will ensure that cookie JSESSIONIDSSO will be used for correct domain and SSO authentication can happen thanks to it."

2) Step 1 of procedure 14.2 (change in jmx-console.war) is not necessary for test authentication of two EPP nodes in cluster. It can be useful only if customer want to test SSO for authentication between "portal" and "jmx-console" web applications. But in this case, it's necessary to change roles in web.xml of jmx-console to use same roles as portal. By default, all authenticated users in portal are in role "users". So it can be good to change <JBOSS_HOME>/server/<PROFILE>/deploy/jmx-console.war/WEB-INF/web.xml to contain this content in the end of the file:

   <security-constraint>
     <web-resource-collection>
       <web-resource-name>HtmlAdaptor</web-resource-name>
       <description>An example security config that only allows users with the
         role JBossAdmin to access the HTML JMX console web application
       </description>
       <url-pattern>/*</url-pattern>
     </web-resource-collection>
     <auth-constraint>
       <!--<role-name>JBossAdmin</role-name>-->
	<role-name>users</role-name>
     </auth-constraint>
   </security-constraint>

   <login-config>
      <auth-method>BASIC</auth-method>
      <realm-name>JBoss JMX Console</realm-name>
   </login-config>

   <security-role>
      <!--<role-name>JBossAdmin</role-name>-->
      <role-name>users</role-name>
   </security-role>



Test of SSO can be done this way:
- Start EPP5 on one node with command: ./run.sh -c node1 -Djboss.service.binding.set=ports-default -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &

- Go to http://localhost:8080/portal/private/classic and authenticate as user "root" with password "gtn"

- Go to http://localhost:8080/jmx-console . You should be automatically authenticated to jmx-console and see content here.

3) Previous changes in login.jsp are useful if user is authenticating through private URL (Going to http://localhost:8080/portal/private/classic and authenticate). But if he also want to authenticate through "Sign in" link (Going to ttp://localhost:8080/portal/public/classic and click "Sign in") he needs to configure automatic redirection to login.jsp page when user clicks to "Sign in" link. Similar thing is already described in other sections like integration with CAS (Procedure 14.8. Redirect to CAS - Step 1 and 2). So you need to change gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml and use this:
<!--
<a class="Login" onclick="$signInAction"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>
-->
<a class="Login" href="/portal/private/classic"><%=_ctx.appRes("UILoginForm.label.Signin")%></a>


and also gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl and use this:
<!--
<a onclick="$signInAction"><%=_ctx.appRes("UILogoPortlet.action.signin")%></a>
-->
<a href="/portal/private/classic"><%=_ctx.appRes("UILogoPortlet.action.signin")%></a>

Thanks for the input Marek,
I've incorporated the content with what already exists in the doc on Stage.
Please review and let me know if it's presented in a logical order, as I'm learning the topic small pieces at a time.

Thanks for the update Scott. I think it looks very good, I only found some smaller issues in new docs:

- Second paragraph: "authentication errors (403 errors, for example). " -> should be "authorization errors (403 errors, for example). " (In this case authentication happens but authorization fails)

Procedure 14.5. Step 1 - In sentence "Copy the <PROFILE> you enabled the valve in (default, for example) ", I would recommend to change "default" profile to "all" because clustering is not enabled in default profile. So it can look like "Copy the <PROFILE> you enabled the valve in (all, for example) "

Section Enabling SSO in a physical cluster - 
Sentence: "This will ensure the JSESSIONIDSSO cookie is be used in the correct domain, allowing the SSO authentication to occur. " - shouldn't be the word "will" instead of "is" ?

Thanks Marek, All fixed.

I've checked it and everything seems to be ok now. Thanks Scott! Should I resolve this jira or you will?

Release Notes Docs Status: Added: Not Required