Author: jaredmorgs Date: 2012-11-29 22:20:53 -0500 (Thu, 29 Nov 2012) New Revision: 8975 Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Preface.xml epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/Advanced/Foundations/Requests.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SAML2.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml Log: BZ#856430 - Incorporated changes suggested by Marek to the CAS section. Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Preface.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/Preface.xml 2012-11-30 02:05:39 UTC (rev 8974) +++ epp/docs/branches/6.0/Reference_Guide/en-US/Preface.xml 2012-11-30 03:20:53 UTC (rev 8975) @@ -14,6 +14,31 @@ <variablelist id="vari-Reference_Guide-Introduction-Devices"> <varlistentry> <term> + <replaceable>CAS_DIR</replaceable> + </term> + <listitem> + <para>The installation root of the Central Authentication Service (CAS) Single Sign-on Framework. This directory is an arbitrary location chosen when CAS is downloaded and installed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>HTTPD_DIST</replaceable> + </term> + <listitem> + <para>The installation root of the Apache httpd server. Apache httpd is a web server used to deploy non-java based applications such as CGI or PHP. This directory contains the main folders that comprise the server such as <filename>/conf</filename>, <filename>/webapps</filename>, and <filename>/bin</filename>. </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <replaceable>ID_HOME</replaceable> + </term> + <listitem> + <para> +The <filename>JPP_SERVER/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/</filename> directory, which contains identity-related configuration resources. This abbreviation is used primarily in <xref linkend="chap-LDAP_Integration"/>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> <replaceable>JPP_DIST</replaceable> </term> <listitem> @@ -44,20 +69,12 @@ </varlistentry> <varlistentry> <term> - <replaceable>CAS_DIR</replaceable> + <replaceable>TOMCAT_DIST</replaceable> </term> <listitem> - <para>The installation root of the Central Authentication Service (CAS) Single Sign-on Framework. This directory is an arbitrary location chosen when CAS is downloaded and installed.</para> + <para>The installation root of the Apache Tomcat server. Apache Tomcat is a simple Java-based web server that can host servlet or JSP applications. This directory contains the main folders that comprise the server such as <filename>/bin</filename>, <filename>/conf</filename>, <filename>/webapps</filename>, and <filename>/lib</filename>.</para> </listitem> </varlistentry> - <varlistentry> - <term> - <replaceable>HTTPD_DIST</replaceable> - </term> - <listitem> - <para>The installation root of the Apache httpd Server. This folder contains the main folders that comprise the server such as <filename>/conf</filename>, <filename>/webapps</filename>, and <filename>/bin</filename>.</para> - </listitem> - </varlistentry> </variablelist> </section> <!-- FOR PUBLICAN --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Common_Content/Conventions.xml"> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2012-11-30 02:05:39 UTC (rev 8974) +++ epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2012-11-30 03:20:53 UTC (rev 8975) @@ -8,6 +8,34 @@ <simpara> <revhistory> <revision> + <revnumber>6.0.0-22</revnumber> + <date>Fri Nov 30 2012</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>BZ#856430 - Incorporated changes suggested by Marek to the CAS section.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>6.0.0-21</revnumber> + <date>Thu Nov 29 2012</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>BZ#856453 - Made the minor, required changes to the LDAP section as identified by Marek in the BS issue.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.0.0-20</revnumber> <date>Wed Nov 28 2012</date> <author> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/Advanced/Foundations/Requests.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/Advanced/Foundations/Requests.xml 2012-11-30 02:05:39 UTC (rev 8974) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/Advanced/Foundations/Requests.xml 2012-11-30 03:20:53 UTC (rev 8975) @@ -1,17 +1,16 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-Component_request_life_cycle"> - <title>Component request life cycle</title> - <section id="sect-Reference_Guide-Component_request_life_cycle-Component_request_life_cycle_contract"> - <title>Component request life cycle contract</title> - <para> - The component request life cycle is an interface that defines a contract for a component for being involved into a request: - </para> - -<programlisting language="Java" role="Java">public interface ComponentRequestLifecycle + <title>Component request life cycle</title> + <section id="sect-Reference_Guide-Component_request_life_cycle-Component_request_life_cycle_contract"> + <title>Component request life cycle contract</title> + <para> + The component request life cycle is an interface that defines a contract for a component for being involved into a request: + </para> + <programlisting language="Java" role="Java">public interface ComponentRequestLifecycle { /** * Start a request. @@ -25,24 +24,21 @@ */ void endRequest(ExoContainer container); }</programlisting> - <para> - The container passed is the container to which the component is related. This contract is often used to setup a thread local based context that will be demarcated by a request. - </para> - <para> - For instance in the GateIn portal context, a component request life cycle is triggered for user requests. Another example is the initial data import in GateIn that demarcates using callbacks made to that interface. - </para> - - </section> - - <section id="sect-Reference_Guide-Component_request_life_cycle-Request_life_cycle"> - <title>Request life cycle</title> - <para> - The <envar>RequestLifeCycle</envar> class has several statics methods that are used to schedule the component request life cycle of components. Its main responsibility is to perform scheduling while respecting the constraint to execute the request life cycle of a component only once even if it can be scheduled several times. - </para> - <section id="sect-Reference_Guide-Request_life_cycle-Scheduling_a_component_request_life_cycle"> - <title>Scheduling a component request life cycle</title> - -<programlisting language="Java" role="Java">RequestLifeCycle.begin(component); + <para> + The container passed is the container to which the component is related. This contract is often used to setup a thread local based context that will be demarcated by a request. + </para> + <para> + For instance in the portal context, a component request life cycle is triggered for user requests. Another example is the initial data import in GateIn that demarcates using callbacks made to that interface. + </para> + </section> + <section id="sect-Reference_Guide-Component_request_life_cycle-Request_life_cycle"> + <title>Request life cycle</title> + <para> + The <envar>RequestLifeCycle</envar> class has several statics methods that are used to schedule the component request life cycle of components. Its main responsibility is to perform scheduling while respecting the constraint to execute the request life cycle of a component only once even if it can be scheduled several times. + </para> + <section id="sect-Reference_Guide-Request_life_cycle-Scheduling_a_component_request_life_cycle"> + <title>Scheduling a component request life cycle</title> + <programlisting language="Java" role="Java">RequestLifeCycle.begin(component); try { // Do something @@ -51,16 +47,13 @@ { RequestLifeCycle.end(); }</programlisting> - - </section> - - <section id="sect-Reference_Guide-Request_life_cycle-Scheduling_a_container_request_life_cycle"> - <title>Scheduling a container request life cycle</title> - <para> - Scheduling a container triggers the component request life cycle of all the components that implement the interface <envar>ComponentRequestLifeCycle</envar>. If one of the component has already been scheduled before and then that component will not be scheduled again. When the local value is true, then the looked components will be those of the container, when it is false then the scheduler will also look at the components in the ancestor containers. - </para> - -<programlisting language="Java" role="Java">RequestLifeCycle.begin(container, local); + </section> + <section id="sect-Reference_Guide-Request_life_cycle-Scheduling_a_container_request_life_cycle"> + <title>Scheduling a container request life cycle</title> + <para> + Scheduling a container triggers the component request life cycle of all the components that implement the interface <envar>ComponentRequestLifeCycle</envar>. If one of the component has already been scheduled before and then that component will not be scheduled again. When the local value is true, then the looked components will be those of the container, when it is false then the scheduler will also look at the components in the ancestor containers. + </para> + <programlisting language="Java" role="Java">RequestLifeCycle.begin(container, local); try { // Do something @@ -69,34 +62,21 @@ { RequestLifeCycle.end(); }</programlisting> - - </section> - - <section id="sect-Reference_Guide-Request_life_cycle-When_request_life_cycle_is_triggered"> - <title>When request life cycle is triggered</title> - <section id="sect-Reference_Guide-When_request_life_cycle_is_triggered-Portal_request_life_cycle"> - <title>Portal request life cycle</title> - <para> - Each portal request triggers the life cycle of the associated portal container. - </para> - - </section> - - <section id="sect-Reference_Guide-When_request_life_cycle_is_triggered-JMX_request_Life_Cycle"> - <title>JMX request Life Cycle</title> - <para> - When a JMX bean is invoked, the request life cycle of the container to which it belongs it scheduled. Indeed JMX is an entry point of the system that may need component to have a request life cycle triggered. - </para> - - </section> - - - </section> - - - </section> - - + </section> + <section id="sect-Reference_Guide-Request_life_cycle-When_request_life_cycle_is_triggered"> + <title>When request life cycle is triggered</title> + <section id="sect-Reference_Guide-When_request_life_cycle_is_triggered-Portal_request_life_cycle"> + <title>Portal request life cycle</title> + <para> + Each portal request triggers the life cycle of the associated portal container. + </para> + </section> + <section id="sect-Reference_Guide-When_request_life_cycle_is_triggered-JMX_request_Life_Cycle"> + <title>JMX request Life Cycle</title> + <para> + When a JMX bean is invoked, the request life cycle of the container to which it belongs it scheduled. Indeed JMX is an entry point of the system that may need component to have a request life cycle triggered. + </para> + </section> + </section> + </section> </section> - - Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml 2012-11-30 02:05:39 UTC (rev 8974) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/LDAP.xml 2012-11-30 03:20:53 UTC (rev 8975) @@ -2,12 +2,13 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent"> ]> -<chapter id="sect-Reference_Guide_eXo_JCR_1.14-LDAP_Integration"> - <title>LDAP Integration</title> +<chapter id="chap-LDAP_Integration"> + <title><remark>BZ#856453 </remark>LDAP Integration</title> <note> <title>Notational Device</title> + <remark>Docs Note - jmorgan - The file path relating to ID_HOME has changed in JPP6. I&apos;ve made this change based on Marek&apos;s feedback. I&apos;ve also added this to the File Name Conventions section in the Preface.</remark> <para> - For ease of readability the following section uses the notational device <replaceable>ID_HOME</replaceable> to represent the file path <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/organization/</filename>, as this directory is the root of all JBoss Portal Platform&apos;s identity-related configuration. + For ease of readability the following section uses the notational device <replaceable>ID_HOME</replaceable> to represent the file path <filename>JPP_SERVER/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/</filename>, as this directory is the root of all JBoss Portal Platform&apos;s identity-related configuration. </para> </note> <para> @@ -23,52 +24,10 @@ --> <para> LDAP provides the protocols required to manage the data stored in a Directory Server. A Directory Server contains information about resources available (user accounts and printers for example) and their location on the network. </para> - <para> - The following table is a list of Directory Servers that are supported and certified in JBoss Portal Platform. - </para> - <table> - <title>Supported and Certified Directory Servers</title> - <tgroup cols="2"> - <colspec colnum="1" colname="LDAP" colwidth="1*"/> - <thead> - <row> - <entry> - <emphasis>Directory Server</emphasis> - </entry> - <entry> - <emphasis>Version</emphasis> - </entry> - </row> - </thead> - <tbody> - <row> - <entry> OpenDS </entry> - <entry> 1.2, 2.0, 2.2 Update 1 </entry> - </row> - <row> - <entry> OpenLDAP </entry> - <entry> 2.4 </entry> - </row> - <row> - <entry> Red Hat Directory Server </entry> - <entry> 7.1, 8.1, 8.2, 9.0 </entry> - </row> - <row> - <entry> Sun Java System Directory Server </entry> - <entry> 6.1 </entry> - </row> - <row> - <entry> Microsoft Active Directory </entry> - <entry> Windows Server 2008, Windows Server 2008 R2, Windows Server 2012 </entry> - </row> - </tbody> - </tgroup> - </table> -<!-- Source Metadata -URL: http://www.jboss.com/products/platforms/portals/testedconfigurations/ -Author [w/email]: Red Hat Inc -License: ---> <note> + <remark>Docs Note - jmorgan - There used to be a table here with all the supported LDAP servers, however as decided in the PRD planning, all supported configuration will be captured in the KBase article. I have removed the table </remark> + <para>Refer to the <ulink url="https://access.redhat.com/knowledge/articles/119833">JBoss Portal Platform Supported Configurations</ulink> +page for a list of supported directory servers. </para> + <note> <title>Examples</title> <para> JBoss Portal Platform includes several example LDAP configuration <filename>.xml</filename> files and <filename>.ldif</filename> (LDAP Data Interchange Format) data files. @@ -84,10 +43,10 @@ Install your <application>LDAP</application> server by following the installation instructions provided for the product you are using. </para> <para> - If you are installing the <application>Red Hat Directory Server</application>, you should refer to the Installation Guide at <ulink url="http://docs.redhat.com/docs/en-US/Red_Hat_Directory_Server/inde... type="http"/>. + If you are installing the <application>Red Hat Directory Server</application>, you should refer to the Installation Guide at <ulink url="https://access.redhat.com/knowledge/docs/Red_Hat_Directory_Serv... type="http"/>. </para> <para> - If you are using a third party directory server (<application>OpenDS</application>, <application>OpenLDAP</application> or <application>Microsoft Active Directory</application>), refer the appropriate documentation for that product. + If you are using a third party directory server (<application>OpenDS</application>, <application>OpenLDAP</application> or <application>Microsoft Active Directory</application>), refer to the appropriate documentation for that product. </para> <para> The following values provide an example of working configuration settings for the different Directory Servers: @@ -192,16 +151,16 @@ <section id="sect-Reference_Guide_eXo_JCR_1.14-LDAP_Integration-LDAP_in_Read-only_Mode"> <title>LDAP in Read-only Mode</title> <para> - This section will show you how to add LDAP in read-only mode. This means that user data entries (both pre-existing, and newly added through the JBoss Portal Platform User Interface) will be consumed though the Directory Server and LDAP services, but written to the underlying database. The only exception is that passwords updated via the UI will also be propagated into the appropriate LDAP entry. + This section will show you how to add LDAP in read-only mode. This means that user data entries (both pre-existing, and newly added through the JBoss Portal Platform User Interface) will be consumed though the Directory Server and LDAP services, but written to the underlying database. The only exception is that passwords updated through the user interface will also be propagated into the appropriate LDAP entry. </para> - <procedure id="proc-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_mode-Set_up_LDAP_read-only_Mode"> + <procedure id="proc-LDAP-LDAP_read-only_Mode"> <title>Set up LDAP read-only Mode</title> <step> <para> Open the <filename><replaceable>ID_HOME</replaceable>/idm-configuration.xml</filename> file. </para> <para> -JBoss Portal Platform uses the PicketLink IDM framework as the underlying identity storage system, hence all the configurations use dedicated Picketlink settings. +JBoss Portal Platform uses the PicketLink IDM framework as the underlying identity storage system, therefore the configuration uses dedicated PicketLink settings. </para> </step> <step> @@ -232,21 +191,84 @@ </para> </listitem> </itemizedlist> - <procedure id="proc-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_Mode-Set_up_LDAP_read-only_Mode-RHDS_or_OpenDS"> - <title>Red Hat Directory Server or OpenDS</title> + </step> + <step id="step-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_Mode-Set_up_LDAP_read-only_Mode-Step-4"> + <para> + To use a different LDAP server or directory data, edit the DS-specific <filename>.xml</filename> file you uncommented in the relevant sub-procedure above, and change the values to suit your requirements. + </para> + <para> + Refer to the list in <xref linkend="exam-Reference_Guide-LDAP_Integration-Examples-LDAP_configuration_options"/> for some examples, or refer to the product-specific documentation for more information. + </para> + </step> + <step> + <para> + Start the server. + </para> + </step> + <step> + <para> + Navigate to the portal homepage (<ulink url="http://localhost:8080/portal" type="http"/>) and log in as an administrator. + </para> + </step> + <step> + <para> + Navigate to <menuchoice> + <guimenu>Group</guimenu> + <guimenuitem>Organization</guimenuitem> + <guimenuitem>Users and groups management</guimenuitem> + </menuchoice>. + </para> + <substeps> <step> <para> + Create a new group called <emphasis>acme</emphasis> under the root node. + </para> + </step> + <step> + <itemizedlist> + <listitem> + <para> + <emphasis role="bold">For RHDS, OpenDS and OpenLDAP</emphasis>: + </para> + <para> + Create two sub-groups called <emphasis>roles</emphasis> and <emphasis>organization_units</emphasis>. + </para> + </listitem> + <listitem> + <para> + <emphasis role="bold">For MSAD:</emphasis> + </para> + <para> + Create a subgroup called <emphasis>roles</emphasis>. + </para> + </listitem> + </itemizedlist> + </step> + </substeps> + </step> + </procedure> + <para> + Users defined in LDAP should be visible in &quot;<emphasis>Users and groups management</emphasis>&quot; and groups from LDAP should be present as children of <emphasis>/acme/roles</emphasis> and <emphasis>/acme/organization_units</emphasis>. + </para> + <remark>Docs Note - jmorgan - After pinging asaldana, he began updating the IDM page on picketlink confluence. With this in mind, I changed this link to the new location. The old locatoin was to a SVN repo of static docs. </remark> + <para> + More information about configuration can be found in the <ulink url="https://docs.jboss.org/author/display/PLINK/PicketLink+IDM"... Community Documentation</ulink>. + </para> + <procedure id="proc-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_Mode-Set_up_LDAP_read-only_Mode-RHDS_or_OpenDS"> + <title>Red Hat Directory Server or OpenDS</title> + <step> + <para> Uncomment the line under &quot;<emphasis>Read Only &quot;ACME&quot; LDAP Example</emphasis>&quot;: </para> - <programlisting language="XML" role="XML"><![CDATA[<!--Read Only "ACME" LDAP Example--> + <programlisting language="XML" role="XML"><![CDATA[<!--Read Only "ACME" LDAP Example--> <value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-LDAP-acme-config.xml</value> ]]></programlisting> - </step> - <step> - <para> + </step> + <step> + <para> Uncomment the <parameter>groupTypeMappings</parameter> under &quot;<emphasis>Uncomment for ACME LDAP example</emphasis>&quot;: </para> - <programlisting language="XML" role="XML"><![CDATA[<!-- Uncomment for ACME LDAP example --> + <programlisting language="XML" role="XML"><![CDATA[<!-- Uncomment for ACME LDAP example --> <entry> <key><string>/acme/roles/*</string></key> <value><string>acme_roles_type</string></value> @@ -256,66 +278,64 @@ <value><string>acme_ou_type</string></value> </entry> ]]></programlisting> - <para> + <para> Refer to <xref linkend="exam-Reference_Guide-LDAP_Integration-Examples-Read_Only_groupTypeMappings"/> for more information about how these <parameter>groupTypeMappings</parameter> operate. </para> - </step> - <step> - <para> - Continue to <xref linkend="step-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_Mode-Set_up_LDAP_read-only_Mode-Step-4"/>. + </step> + <step> + <para>Return to <xref linkend="proc-LDAP-LDAP_read-only_Mode"/>. </para> - </step> - </procedure> - <procedure id="proc-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_Mode-Set_up_LDAP_read-only_Mode-MSAD"> - <title>Microsoft Active Directory</title> - <step> - <para> + </step> + </procedure> + <procedure id="proc-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_Mode-Set_up_LDAP_read-only_Mode-MSAD"> + <title>Microsoft Active Directory</title> + <step> + <para> Uncomment the line under &quot;<emphasis>MSAD Read Only &quot;ACME&quot; LDAP Example</emphasis>&quot;: </para> - <programlisting language="XML" role="XML"><![CDATA[<!--MSAD Read Only "ACME" LDAP Example--> + <programlisting language="XML" role="XML"><![CDATA[<!--MSAD Read Only "ACME" LDAP Example--> <value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-msad-readonly-config.xml</value> ]]></programlisting> - </step> - <step> - <para> + </step> + <step> + <para> Uncomment the <parameter>groupTypeMappings</parameter> under &quot;<emphasis>Uncomment for MSAD ReadOnly LDAP example</emphasis>&quot;: </para> - <programlisting language="XML" role="XML"><![CDATA[<!-- Uncomment for MSAD ReadOnly LDAP example --> + <programlisting language="XML" role="XML"><![CDATA[<!-- Uncomment for MSAD ReadOnly LDAP example --> <entry> <key><string>/acme/roles/*</string></key> <value><string>msad_roles_type</string></value> </entry> ]]></programlisting> - <para> + <para> Refer to <xref linkend="exam-Reference_Guide-LDAP_Integration-Examples-Read_Only_groupTypeMappings"/> for more information about how these <parameter>groupTypeMappings</parameter> operate. </para> - </step> - <step> - <para> - Continue to <xref linkend="step-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_Mode-Set_up_LDAP_read-only_Mode-Step-4"/>. + </step> + <step> + <para>Return to <xref linkend="proc-LDAP-LDAP_read-only_Mode"/>. </para> - </step> - </procedure> - <procedure id="proc-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_Mode-Set_up_LDAP_read-only_Mode-OpenLDAP"> - <title>OpenLDAP</title> - <step> - <para> + </step> + </procedure> + <procedure id="proc-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_Mode-Set_up_LDAP_read-only_Mode-OpenLDAP"> + <title>OpenLDAP</title> + <step> + <para> If you have not done so already, install your LDAP server. Refer to <xref linkend="proc-Reference_Guide-LDAP_Integration-LDAP_Set_Up"/> for some assistance. </para> - </step> - <step> - <para> + </step> + <step> + <para> Uncomment the line under &quot;<emphasis>OpenLDAP ReadOnly &quot;ACME&quot; LDAP Example</emphasis>&quot;: </para> - <programlisting language="XML" role="XML"><![CDATA[<!--OpenLDAP ReadOnly "ACME" LDAP Example--> + <programlisting language="XML" role="XML"><![CDATA[<!--OpenLDAP ReadOnly "ACME" LDAP Example--> <value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-openLDAP-acme-config.xml</value> ]]></programlisting> - </step> - <step> - <para> + </step> + <step> + <para> Uncomment the <parameter>groupTypeMappings</parameter> under &quot;<emphasis>Uncomment for ACME LDAP example</emphasis>&quot;: </para> - <programlisting language="XML" role="XML"><![CDATA[<!-- Uncomment for ACME LDAP example --> + <programlisting language="XML" role="XML"><![CDATA[<!-- Uncomment for ACME LDAP example --> <entry> <key><string>/acme/roles/*</string></key> <value><string>acme_roles_type</string></value> @@ -325,27 +345,85 @@ <value><string>acme_ou_type</string></value> </entry> ]]></programlisting> - <para> + <para> Refer to <xref linkend="exam-Reference_Guide-LDAP_Integration-Examples-Read_Only_groupTypeMappings"/> for more information about how these <parameter>groupTypeMappings</parameter> operate. </para> - </step> - <step> - <para> - Continue to <xref linkend="step-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_Mode-Set_up_LDAP_read-only_Mode-Step-4"/>. + </step> + <step> + <para>Return to <xref linkend="proc-LDAP-LDAP_read-only_Mode"/> </para> - </step> - </procedure> </step> - <step id="step-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_Mode-Set_up_LDAP_read-only_Mode-Step-4"> + </procedure> + </section> + <section id="sect-Reference_Guide_eXo_JCR_1.14-LDAP_Integration-LDAP_as_Default_Store"> + <title>LDAP as Default Store</title> + <para> + Follow the procedure below to set LDAP up as the default identity store for JBoss Portal Platform. All default accounts and some of groups that comes with JBoss Portal Platform will be created in the LDAP store. + </para> + <para> + The LDAP server will be configured to store part of the JBoss Portal Platform group tree. This means that groups under specified part of the tree will be stored in directory server while all others will be stored in database. + </para> + <procedure id="proc-LDAP-Set_up_LDAP_as_Default_Indentity_Store"> + <title>Set up LDAP as Default Identity Store</title> + <step> + <para>Install the LDAP server. Refer to <xref linkend="proc-Reference_Guide-LDAP_Integration-LDAP_Set_Up"/> for assistance with this step. + </para> + </step> + <step> <para> - To use a different LDAP server or directory data, edit the DS-specific <filename>.xml</filename> file you uncommented in <emphasis role="bold">Substep 3a</emphasis> above and change the values to suit your requirements. + Open the <filename><replaceable>ID_HOME</replaceable>/idm-configuration.xml</filename> file. </para> <para> - Refer to the list in <xref linkend="exam-Reference_Guide-LDAP_Integration-Examples-LDAP_configuration_options"/> for some examples or refer to the product-specific documentation for more information. +JBoss Portal Platform uses the PicketLink IDM framework as the underlying identity storage system, hence all the configurations use dedicated Picketlink settings. </para> </step> <step> <para> + Comment out the default Picketlink <literal>config</literal> value: <parameter>war:/conf/organization/picketlink-idm/picketlink-idm-config.xml</parameter> + </para> + </step> + <step> + <para>Complete the steps in the procedure that relate to the chosen LDAP server: + </para> + <itemizedlist> + <listitem> + <para><xref linkend="proc-LDAP-RHDS_and_OpenDS"/></para> + </listitem> + <listitem> + <para><xref linkend="proc-LDAP-MSAD"/></para> + </listitem> + <listitem> + <para><xref linkend="proc-LDAP-OpenLDAP"/></para> + </listitem> + </itemizedlist> + </step> + <step id="step-Reference_Guide-LDAP_Integration-LDAP_as_Default_Store-Set_up_LDAP_as_Default_Indentity_Store-Step-5"> + <para> + Uncomment the <parameter>groupTypeMappings</parameter> under &quot;<emphasis>Uncomment for sample LDAP configuration</emphasis>&quot;: + </para> + <programlisting language="XML" role="XML"><![CDATA[<entry> + <key><string>/platform/*</string></key> + <value><string>platform_type</string></value> +</entry> +<entry> + <key><string>/organization/*</string></key> + <value><string>organization_type</string></value> +</entry> +]]></programlisting> + <para> + Refer to <xref linkend="exam-Reference_Guide-LDAP_Integration-Examples-Default_groupTypeMappings"/> for more information about how these <parameter>groupTypeMappings</parameter> operate. + </para> + </step> + <step> + <para> + To use a different LDAP server or directory data, edit the DS-specific <filename>.xml</filename> file you uncommented in <emphasis role="bold">Step 4</emphasis> above and change the values to suit your requirements. + </para> + <para> + Refer to the list in <xref linkend="exam-Reference_Guide-LDAP_Integration-Examples-LDAP_configuration_options"/> for some configuration examples, or refer to the LDAP server product-specific documentation for more information. + </para> + </step> + <step> + <para> Start the server. </para> </step> @@ -355,6 +433,7 @@ </para> </step> <step> + <remark>NEEDINFO - jmorgan - This step was missing from this procedure. I copied it directly from the LDAP in Read-only mode procedure, but I&apos;m 100% certain the steps are not correct for setting up the default store. Does an admin need to do anything special in the portal interface to set the default store up? If so, what would be the correct steps to follow?</remark> <para> Navigate to <menuchoice> <guimenu>Group</guimenu> @@ -391,156 +470,79 @@ </substeps> </step> </procedure> - <para> - Users defined in LDAP should be visible in &quot;<emphasis>Users and groups management</emphasis>&quot; and groups from LDAP should be present as children of <emphasis>/acme/roles</emphasis> and <emphasis>/acme/organization_units</emphasis>. - </para> - <para> - More information about configuration can be found in <xref linkend="sect-Reference_Guide-PicketLink_IDM_integration"/> and in the PicketLink project <ulink url="http://anonsvn.jboss.org/repos/picketlink/idm/downloads/docs/1.... type="http">Reference Guide</ulink>. - </para> - </section> - <section id="sect-Reference_Guide_eXo_JCR_1.14-LDAP_Integration-LDAP_as_Default_Store"> - <title>LDAP as Default Store</title> - <para> - Follow the procedure below to set LDAP up as the default identity store for JBoss Portal Platform. All default accounts and some of groups that comes with JBoss Portal Platform will be created in the LDAP store. - </para> - <para> - The LDAP server will be configured to store part of the JBoss Portal Platform group tree. This means that groups under specified part of the tree will be stored in directory server while all others will be stored in database. - </para> - <procedure id="proc-Reference_Guide-LDAP_Integration-LDAP_as_Default_Store-Set_up_LDAP_as_Default_Indentity_Store"> - <title>Set up LDAP as Default Indentity Store</title> + <procedure id="proc-LDAP-RHDS_and_OpenDS"> + <title>For RHDS and OpenDS</title> <step> <para> - If you have not done so already, install your LDAP server. Refer to <xref linkend="proc-Reference_Guide-LDAP_Integration-LDAP_Set_Up"/> for some assistance. - </para> + Expose the entry under &quot;<emphasis>Sample LDAP config</emphasis>&quot;: + </para> + <programlisting language="XML" role="XML"><![CDATA[<!--Sample LDAP config--> +<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-LDAP-config.xml</value> +]]></programlisting> </step> <step> - <para> - Open the <filename><replaceable>ID_HOME</replaceable>/idm-configuration.xml</filename> file. - </para> - <para> -JBoss Portal Platform uses the PicketLink IDM framework as the underlying identity storage system, hence all the configurations use dedicated Picketlink settings. - </para> + <para>Return to <xref linkend="proc-LDAP-Set_up_LDAP_as_Default_Indentity_Store"/> + </para> </step> + </procedure> + <procedure id="proc-LDAP-MSAD"> + <title>For MSAD</title> <step> <para> - Comment out the default Picketlink <literal>config</literal> value: <parameter>war:/conf/organization/picketlink-idm/picketlink-idm-config.xml</parameter> - </para> + Expose the entry under &quot;<emphasis>MSAD LDAP Example</emphasis>&quot;: + </para> + <programlisting language="XML" role="XML"><![CDATA[<!--MSAD LDAP Example--> +<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-msad-config.xml</value> +]]></programlisting> </step> <step> - <para> - Uncomment the appropriate LDAP configuration entry depending on your LDAP server: - </para> - <procedure> - <title>For RHDS and OpenDS</title> + <para>To enable SSL encryption, perform the following sub-steps:</para> + <substeps> <step> <para> - Expose the entry under &quot;<emphasis>Sample LDAP config</emphasis>&quot;: - </para> - <programlisting language="XML" role="XML"><![CDATA[<!--Sample LDAP config--> -<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-LDAP-config.xml</value> -]]></programlisting> + Open the <filename><replaceable>ID_HOME</replaceable>/picketlink-idm/examples/picketlink-idm-msad-config.xml</filename>. + </para> </step> <step> <para> - Continue to <xref linkend="step-Reference_Guide-LDAP_Integration-LDAP_as_Default_Store-Set_up_LDAP_as_Default_Indentity_Store-Step-5"/> - </para> - </step> - </procedure> - <procedure> - <title>For MSAD</title> - <step> - <para> - Expose the entry under &quot;<emphasis>MSAD LDAP Example</emphasis>&quot;: - </para> - <programlisting language="XML" role="XML"><![CDATA[<!--MSAD LDAP Example--> -<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-msad-config.xml</value> -]]></programlisting> - <procedure> - <title>To use SSL encryption with MSAD:</title> - <step> - <para> - Open the <filename><replaceable>ID_HOME</replaceable>/picketlink-idm/examples/picketlink-idm-msad-config.xml</filename>. - </para> - </step> - <step> - <para> Ensure the following entries are uncommented and that the path to the <filename>truststore</filename> file and password are correct: </para> - <programlisting>&lt;option&gt; + <programlisting>&lt;option&gt; &lt;name&gt;customSystemProperties&lt;/name&gt; &lt;value&gt;javax.net.ssl.trustStore=<replaceable>/path/to/truststore</replaceable>&lt;/value&gt; &lt;value&gt;javax.net.ssl.trustStorePassword=<replaceable>password</replaceable>&lt;/value&gt; &lt;/option&gt; </programlisting> - <para> + <para> You can import a custom certificate by replacing the <replaceable>certificate</replaceable> and <replaceable>truststore</replaceable> details in the following command: </para> - <programlisting><command>keytool -import -file <filename> - <replaceable>certificate</replaceable> - </filename> -keystore <filename> - <replaceable>truststore</replaceable> - </filename></command> + <programlisting><command>keytool -import -file <filename> + <replaceable>certificate</replaceable> + </filename> -keystore <filename> + <replaceable>truststore</replaceable> + </filename></command> </programlisting> - </step> - </procedure> </step> - <step> - <para> - Continue to <xref linkend="step-Reference_Guide-LDAP_Integration-LDAP_as_Default_Store-Set_up_LDAP_as_Default_Indentity_Store-Step-5"/> - </para> - </step> - </procedure> - <procedure> - <title>For OpenLDAP</title> - <step> - <para> - Expose the entry under &quot;<emphasis>OpenLDAP LDAP config</emphasis>&quot;: - </para> - <programlisting language="XML" role="XML"><![CDATA[<!--OpenLDAP LDAP config--> -<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-openLDAP-config.xml</value> -]]></programlisting> - </step> - <step> - <para> - Continue to <xref linkend="step-Reference_Guide-LDAP_Integration-LDAP_as_Default_Store-Set_up_LDAP_as_Default_Indentity_Store-Step-5"/> - </para> - </step> - </procedure> + </substeps> </step> - <step id="step-Reference_Guide-LDAP_Integration-LDAP_as_Default_Store-Set_up_LDAP_as_Default_Indentity_Store-Step-5"> - <para> - Uncomment the <parameter>groupTypeMappings</parameter> under &quot;<emphasis>Uncomment for sample LDAP configuration</emphasis>&quot;: - </para> - <programlisting language="XML" role="XML"><![CDATA[<entry> - <key><string>/platform/*</string></key> - <value><string>platform_type</string></value> -</entry> -<entry> - <key><string>/organization/*</string></key> - <value><string>organization_type</string></value> -</entry> -]]></programlisting> - <para> - Refer to <xref linkend="exam-Reference_Guide-LDAP_Integration-Examples-Default_groupTypeMappings"/> for more information about how these <parameter>groupTypeMappings</parameter> operate. - </para> - </step> <step> - <para> - To use a different LDAP server or directory data, edit the DS-specific <filename>.xml</filename> file you uncommented in <emphasis role="bold">Step 4</emphasis> above and change the values to suit your requirements. - </para> - <para> - Refer to the list in <xref linkend="exam-Reference_Guide-LDAP_Integration-Examples-LDAP_configuration_options"/> for some examples or refer to the product-specific documentation for more information. - </para> + <para>Return to <xref linkend="proc-LDAP-Set_up_LDAP_as_Default_Indentity_Store"/>. </para> </step> + </procedure> + <procedure id="proc-LDAP-OpenLDAP"> + <title>For OpenLDAP</title> <step> <para> - Start the server. - </para> + Expose the entry under &quot;<emphasis>OpenLDAP LDAP config</emphasis>&quot;: + </para> + <programlisting language="XML" role="XML"><![CDATA[<!--OpenLDAP LDAP config--> +<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm-openLDAP-config.xml</value> +]]></programlisting> </step> <step> <para> - Navigate to the portal homepage (<ulink url="http://localhost:8080/portal" type="http"/>) and log in as an administrator. - </para> +Return to <xref linkend="proc-LDAP-Set_up_LDAP_as_Default_Indentity_Store"/> + </para> </step> </procedure> </section> @@ -562,7 +564,7 @@ </listitem> <listitem> <para> - One of the three example configuration files discussed in <xref linkend="proc-Reference_Guide-LDAP_Integration-LDAP_in_Read-only_mode-Set_up_LDAP_read-only_Mode"/>: + One of the three example configuration files discussed in <xref linkend="proc-LDAP-LDAP_read-only_Mode"/>: </para> <simplelist> <member> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SAML2.xml =================================================================== (Binary files differ) Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-11-30 02:05:39 UTC (rev 8974) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-11-30 03:20:53 UTC (rev 8975) @@ -350,13 +350,14 @@ <section id="sect-CAS-Authentication_Process"> <title>Authentication Process</title> <para>The authentication process with CAS integration occurs in the following order:</para> + <remark>Docs Note - jmorgan - have taken the original process in https://docs.jboss.org/author/display/GTNPORTAL35/Central+Authentication+... and have tried to break up some of the steps for clarity. If you could please verify these changes are accurate, that would be awesome, Marek.</remark> <orderedlist> <listitem> <para>A user visits the main portal page, and wishes to authenticate. The user clicks <emphasis role="italics">Sign in</emphasis>. </para> </listitem> <listitem> - <para>Normally this action would present the GateIn Portal login dialog, however with SSO integration enabled, the action redirects the user to a marker URL such as + <para>Normally this action would present the portal login dialog, however with SSO integration enabled, the action redirects the user to a marker URL such as <ulink url="http://localhost:8080/portal/sso"/>. </para> <para>The portal handles this user action by calling the interceptor (Servlet filter) @@ -371,7 +372,6 @@ . The user enters the correct authentication information, and submits the form. </para> <para>The CAS server retrieves the information from the identity store. The store could be an external database, a LDAP server, or from information obtained through an authentication plug-in such as the one shipped with JBoss Portal Platform. Refer to <xref linkend="sect-CAS_Authentication_Plug-in"/> for specific details about this technology.</para> - <remark>Docs Note: Removed the large block of content here about the Authentication Plug-in into the Authentication Plug-in section. It just didn&apos;t fit in this work flow overview section, and sits much better in the plug-in section.</remark> </listitem> <listitem> <para> Once CAS determines the user has the correct access privileges to access the portal server, CAS redirects the user back to the portal through another marker URL such as @@ -427,6 +427,7 @@ <section id="sect-CAS-Logout_Workflow"> <title>Logout Process</title> <para>The logout process with CAS integration occurs in the following order:</para> + <remark>Docs Note - jmorgan - The same with this one Marek. Taken from the confluence page and reworked to introduce some separation into the steps. Just check my wording of each step to ensure I haven&apos;t changed the overall technical meaning with my changes. Cheers, Marek!</remark> <orderedlist> <listitem> <para>The authenticated user clicks the @@ -473,23 +474,24 @@ </listitem> </itemizedlist> <section id="sect-CAS-Install_Tomcat_Server"> - <title>Install Tomcat Server</title> - <para>Install and configure Apache Tomcat before proceeding with other configuration relating to CAS. + <title>Install Apache Tomcat Server</title> + <para>Install and configure Apache Tomcat 7 before proceeding with other configuration relating to CAS. </para> - <para>This procedure covers the Linux installation method for Apache Tomcat (httpd). -Completing this task defines the file path abbreviation HTTPD_DIST, which is used in other CAS configuration procedures.</para> <para>File name abbreviations in this section are described in <xref linkend="sect-File_Name_Conventions"/></para> <procedure> - <title>Configuring Tomcat for CAS</title> + <title>Configuring Apache Tomcat for CAS</title> + <remark>Docs Note - redid the procedure with a view to Apache Tomcat, not Apache httpd. If installed from the Zip binary, does Apache Tomcat start a service like httpd (Step 4)?</remark> <step> - <para>Install Tomcat by running <command>sudo yum install httpd</command> in a terminal.</para> + <para>Visit <ulink url="http://tomcat.apache.org/download-70.cgi"/> and download the Tomcat 7 binary distribution.</para> </step> <step> - <para>Edit <filename>HTTPD_DIST/conf/httpd.conf</filename> and change the Listen 80 port to 8888 to avoid a conflict with the default JBoss Portal Platform listen port.</para> - <remark>NEEDINFO - this used to be HTTPD_DIST/conf/server.xml, but if you install httpd using RPM, this file doesn&apos;t seem to exist. I assumed the .conf file was the correct place to change the listen port.</remark> + <para>Extract and install the binary on the server that is required to host CAS. This directory is now referred to as <replaceable>TOMCAT_DIST</replaceable>.</para> </step> <step> - <para>Ensure port 8888 is open in the server firewall, and the httpd service is enabled and running so the platform can communicate with Apache on the same server. + <para>Edit <filename>TOMCAT_DIST/conf/server.xml</filename> and change port 8080 to 8888 to avoid a conflict with the default JBoss Portal Platform listen port.</para> + </step> + <step> + <para>Ensure port 8888 is open in the server firewall, and the service is enabled and running so the platform can communicate with Apache Tomcat on the same server. </para> </step> </procedure> @@ -516,7 +518,6 @@ <section id="sect-CAS_Authentication_Plug-in"> <title>Authentication Plug-in </title> <para>While it is possible (and perfectly acceptable) for an administrator to configure CAS to retrieve user credentials from an external database, or from a LDAP server, it is also possible to use JBoss technology. </para> - <remark>Docs Note: This section was originally in https://docs.jboss.org/author/display/GTNPORTAL35/Central+Authentication+... and has been reworked quite a bit to promote the authentication plug-in as the &quot;best&quot; solution.</remark> <para>CAS can be configured to make secure authentication callbacks to a RESTful service installed on the remote portal instance using the supplied CAS <literal>AuthenticationPlugin</literal>. </para> <para>Implementing the <literal>AuthenticationPlugin</literal> on the CAS server has the advantage of leveraging a single identity storage for portal user, group and role data. If a new user is added using the portal user management interface, the user information is instantly accessible to the CAS server through the technology implemented by the <literal>AuthenticationPlugin</literal>. </para> <para>The plug-in verifies user credentials by connecting to an existing portal instance using REST over the HTTP protocol. The portal serves a REST authentication callback request, and verifies the user identity against the portal&apos;s own identity storage provided by the PicketLink IDM @@ -536,7 +537,7 @@ <para>Replace the default configuration, which declares the Jasig <classname>SimpleTestUsernamePasswordAuthenticationHandler</classname> Authentication Handler with the following supported Authentication Handler. </para> <note> <para>This configuration is available in the - <code><replaceable>SSO_HOME</replaceable>/cas.war/WEB-INF/deployerConfigContext.xml</code>. If you choose to take this configuration file, ensure the default host, port and context parameters are adjusted to match the values corresponding to the remote portal instance. </para> + <code><replaceable>PORTAL_SSO</replaceable>/cas.war/WEB-INF/deployerConfigContext.xml</code>. If you choose to take this configuration file, ensure the default host, port and context parameters are adjusted to match the values corresponding to the remote portal instance. </para> </note> <programlisting> &lt;!-- @@ -553,7 +554,7 @@ <step> <para> Copy all jars from - <code>SSO_HOME/cas/plugin/WEB-INF/lib/ </code>to the + <code>PORTAL_SSO/cas/plugin/WEB-INF/lib/ </code>to the <code>CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/lib</code> directory. </para> </step> @@ -621,10 +622,10 @@ <section id="sect-CAS_Portal_SSO_Primary_Configuration_File"> <title>Portal SSO Primary Configuration File</title> <para> - The main GateIn Portal configuration file for SSO integration is + The main portal configuration file for SSO integration is <code>JPP_SERVER/gatein/gatein.ear/portal.war/WEB-INF/conf/sso/security-sso-configuration.xml</code> . All required SSO components such as agents and SSO interceptors (servlet filters in v5.x of the product) are configured in this file. </para> - <para>In most cases, it will never be necessary to edit <filename>security-sso-configuration.xml</filename> directly when using JBoss Portal Platform. The architecture in JBoss Enterprise Application Platform 6 means that users can override the base configuration described in this file using name/value pairs configured in one place: <filename>JPP_SERVER/standalone/configuration/gatein/configuration.properties</filename></para> + <para>In most cases, it will never be necessary to edit <filename>security-sso-configuration.xml</filename> directly when using JBoss Portal Platform. The portal architecture allows users to override the base configuration described in this file using name/value pairs configured in one place: <filename>JPP_SERVER/standalone/configuration/gatein/configuration.properties</filename></para> <para>The exception to this rule is where configuration present in <filename>security-sso-configuration.xml</filename> is fundamentally unsuitable for the production environment the server will be deployed to, or when additional underlying functionality is required (for example, another custom interceptor). </para> </section> <section id="sect-CAS_Configuring_the_Platform"> @@ -637,7 +638,7 @@ <para>Open <filename>JPP_SERVER/standalone/configuration/gatein/configuration.properties</filename> and locate the SSO sections in the file.</para> </step> <step> - <para>Make the following changes to the file to declare the correct login module, server and portal URLs, and the logout filter. Ensure <replaceable>[portal.container.name]</replaceable> is replaced with the name of the portal container used in production.</para> + <para>Make the following changes to the file to declare the correct login module, server and portal URLs, and the logout filter.</para> <programlisting> # SSO gatein.sso.enabled=true @@ -648,7 +649,7 @@ gatein.sso.portal.url=http://localhost:8080 gatein.sso.filter.logout.class=org.gatein.sso.agent.filter.CASLogoutFilter gatein.sso.filter.logout.url=${gatein.sso.server.url}/logout -gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/login?service=${gatein.sso.portal.url}/@@&lt;replaceable&gt;[portal.container.name]&lt;/replaceable&gt;@(a)/initiatessologin +gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/login?service=${gatein.sso.portal.url}/@@[portal.container.name]@(a)/initiatessologin </programlisting> </step> </procedure> @@ -738,6 +739,10 @@ <para> Specifies the CAS server login URL, which is used by LoginRedirectFilter for redirection to the CAS server login page. </para> + <remark>Docs Note - jmorgan - added this note about the p.c.n variable, and that it *shouldn&apos;t* be substituted for a hard-coded variable name.</remark> + <note> + <para>The string <literal&gt;@@portal.container.name(a)@ </literal>is dynamically replaced when the URL is interpreted by the platform&apos;s SSO Component. It is recommended that this string is used over hard-coding the name of the portal for future maintenance and ease of configuration changes. </para> + </note> </listitem> </varlistentry> </variablelist>