Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-overrides.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-overrides.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-overrides.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-overrides.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,184 @@ +<?xml version="1.0"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +<document> + <properties> + <title>Spring Configuration Overrides</title> + <subtitle>Spring Configuration Overrides</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]"/> + </authors> + </properties> + <body> +<section name="Spring Configuration Overrides"> + + <p> + Spring Configuration Overrides, located in <strong><code>/WEB-INF/assembly/override/</code></strong>, are loaded over the configuration files found in the parent assembly folder (<strong><code>/WEB-INF/assembly/</code></strong>). + Use the override folder to modify the default assembly configuration. There are examples of overrides in the <strong><code>/WEB-INF/assembly/alternate/</code></strong> directory. + Note that the configuration files found in the alternate directory are only examples. They are not actively used. If you wanted to use one of the alternate configuration files, copy it into the overrides directory, + and then modify it from there. + </p> + <p> + Spring beans are replaced by name. So the configuration files do not need to match by file name when overriding. If you are only overriding one bean though, + it might be easier to just replace the bean in the main Jetspeed Spring container by dropping in a new file with only that one bean. + </p> +<subsection name='Example Spring Override'> +<p>For example, say if we were to override the CapabilityValve found in Jetspeed's pipelines.xml file:</p> +<source><![CDATA[ + <bean id="capabilityValve" + class="org.apache.jetspeed.capabilities.impl.CapabilityValveImpl" + init-method="initialize" + > + <constructor-arg> + <ref bean="org.apache.jetspeed.capabilities.Capabilities" /> + </constructor-arg> + </bean> +]]></source> + <p> +The pipelines.xml has a lot of beans. We only need to replace the one bean, capabilityValve, with our implementation. Note the bean id is the same, the impl is different: + </p> +<source><![CDATA[ + <bean id="capabilityValve" + class="com.ace.capabilities.impl.AceCapabilityValveImpl" + init-method="initialize" + > + <constructor-arg> + <ref bean="com.ace.services.AceDataService" /> + </constructor-arg> + </bean> +]]></source> +<p>Saving this one bean in a file named capability-valve-override.xml would clearly define what is being overriden.</p> +</subsection> + <p> + Commonly used overrides in Jetspeed are: + <ul> + <li>DBPSML</li> + <li>Versioned Deployment</li> + <li>Adding a Jetspeed Service</li> + <li>Pipelines or tweaking a feature</li> + </ul> + </p> +<subsection name='DBPSML'> +<p>PSML represents the pages in your portal. There can be lots of them. The default implementation stores the PSML files on the file system. +A secondary implementation stores the files in the database. Storing in the database is necessary when deploying to a clustered Jetspeed distribution, +or when you have tens of thousands of users where performance is required. Provided in the alternate directory is a DBPSML alternate configuration, db-page-manager.xml. +You can take this file and copy it into your overrides directory. It will override the page-manager.xml beans by name. +</p> +<source><![CDATA[ + <bean id="org.apache.jetspeed.page.PageManagerImpl" + name="pageManagerImpl" + init-method="init" + class="org.apache.jetspeed.page.impl.DatabasePageManager"> + <!-- OJB configuration file resource path --> + <constructor-arg index="0"><value>JETSPEED-INF/ojb/page-manager-repository.xml</value></constructor-arg> + <!-- permissions security enabled flag, default=false --> + <constructor-arg index="1"><value>false</value></constructor-arg> + <!-- constraints security enabled flag, default=true --> + <constructor-arg index="2"><value>true</value></constructor-arg> + <!-- folder/page/link cache --> + <constructor-arg index="3"><ref bean="pageManagerOidCache"/></constructor-arg> + <!-- folder/page/link path cache --> + <constructor-arg index="4"><ref bean="pageManagerPathCache"/></constructor-arg> + </bean> +]]></source> +</subsection> +<subsection name="Versioned Deployment"> +<p>The default Jetspeed Deployer, although it works well for development on Tomcat, doesn't work well in clustered environments. +We have implement a second, Versioned Portlet Application Manager for clustered environments. +The Node Manager implementation will most likely be deprecated in the future. We are running into +limitations with the NodeManager-based cluster support when deploying +to clusters with replicated databases as well as replicated app servers. +The default PAM (Portlet Application Manager) is not-appropriate for many deployments of the +portal. This second version of the PAM has no listeners, +and a simpler deployment algorithm based on a version number supplied in the jetspeed-portlet.xml +metadata +If this field is not found, or if it is equal to or less than the version in the database, +then the PA will not be deployed. +This will allow for dropping in 2..n PAs in a cluster, without re-registering. The problem +with re-registering is that the registry algorithm deep deletes the old PA def from the database, +create a new PA, with all new OIDs, invalidating all other PAs and portlets on other nodes +in the cluster. +</p> +<source><![CDATA[ +<bean id="deployFactory" class="org.apache.jetspeed.tools.deploy.JetspeedDeployFactory"/> + <bean id="org.apache.jetspeed.tools.pamanager.PortletApplicationManager" + class="org.apache.jetspeed.tools.pamanager.VersionedPortletApplicationManager" init-method="start" destroy-method="stop" + > + <constructor-arg><ref bean="portletFactory"/></constructor-arg> + <constructor-arg><ref bean="org.apache.jetspeed.components.portletregistry.PortletRegistry"/></constructor-arg> + <constructor-arg><ref bean="org.apache.jetspeed.components.portletentity.PortletEntityAccessComponent"/></constructor-arg> + <constructor-arg><ref bean="org.apache.jetspeed.container.window.PortletWindowAccessor"/></constructor-arg> + <constructor-arg><ref bean="org.apache.jetspeed.security.PermissionManager"/></constructor-arg> + <constructor-arg><ref bean="org.apache.jetspeed.search.SearchEngine"/></constructor-arg> + <constructor-arg><ref bean="org.apache.jetspeed.security.RoleManager"/></constructor-arg> + <!-- role principals to assign a default permission(s) during deployment of a Portlet Application --> + <constructor-arg > + <list> + <value>user</value> + </list> + </constructor-arg> + + <!-- application root --> + <constructor-arg> + <value>${applicationRoot}</value> + </constructor-arg> + + + <!-- optional configuration for automatic creation of not yet existing roles as defined in the deployed web.xml: + <property name="autoCreateRoles"><value>true</value></property> + --> + <!-- optional descriptor change monitor check interval in seconds (0: disabled, default: 10): + <property name="descriptorChangeMonitorInterval"><value>10</value></property> + --> + <!-- optional max PA start retries in case of an error registering ths PA (0: do not retry, default: 10): + this was introduced because of DB constraint validation errors in clustered environments + see https://issues.apache.org/jira/browse/JS2-666 + <property name="maxRetriedStarts"><value>10</value></property> + --> + </bean> +]]></source> +<p> +Provided in the alternate directory is a deployment alternate configuration, deployment.xml. You can take this file and copy it into your overrides directory. It will override the deployment.xml beans by name. +</p> +</subsection> +<subsection name="Adding Jetspeed Services"> + <p>Occasionally you may write your own service to run inside Jetspeed. You will need to add your service to the PortalServices bean. + Unfortunately this requires cutting and pasting the entire PortalServices bean, and adding your service to the map in your overriden jetspeed-services.xml:</p> +<source><![CDATA[ + +<beans> + <!-- Portlet Services --> + <bean id="PortalServices" + class="org.apache.jetspeed.services.JetspeedPortletServices" > + <constructor-arg> + <map> + ... + <entry key="MyNewService"> + <ref bean="com.ace.services.MyNewService"/> + </entry> + </map> + </constructor-arg> + </bean> +</beans> +]]></source> +<p> +In this case take the jetspeed-services.xml, copy it to your WEB-INF/assembly/override directory, and modify it there to add your new service +</p> +</subsection> +</section> +</body> +</document>
Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-profile.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-profile.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-profile.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-profile.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,51 @@ +<?xml version="1.0"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +<document> + <properties> + <title>Profiler Config</title> + <subtitle>Profiler Configuration</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]"/> + </authors> + </properties> + <body> +<section name="Profiler Component Configuration"> +<p> +The profiler.xml Spring configuration file configures the profiler component. +<table> + <tr> + <th>Constructor Argument</th> + <th>Description</th> + </tr> + <tr> + <td>(0) JETSPEED-INF/ojb/profiler_repository.xml</td> + <td>Holds the OJB database to POJO mapper for marshalling profile information to and from the persistent store.</td> + </tr> + <tr> + <td>(1) j1</td> + <td>The default profiling rule. If a user does not have a profiling rule defined in the association table, this profiling rule is used.</td> + </tr> + <tr> + <td>(2) ProfileResolvers (ref bean)</td> + <td>The map of profiler resolver names to implementing resolver classes. New resolvers should be added to the ProfileResolver table.</td> + </tr> +</table> +</p> +</section> +</body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-spring.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-spring.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-spring.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-spring.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,123 @@ +<?xml version="1.0"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +<document> + <properties> + <title>Spring Framework Introduction</title> + <subtitle>Spring Framework Introduction</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]"/> + </authors> + </properties> + <body> + + <section name="Spring Introduction"> + <p> + Spring is a unique Java application framework meant to simplify the development of applications. Whereas Enterprise Java Beans are very complex to use, the <a href="http://www.springframework.org";>Spring Framework</a> is an easy to use and understand framework for enterprise applications. Spring focuses on: + <ul> + <li>Providing a simple way to manage an object's lifetime and relationships (through Dependency Injection).</li> + <li>A layered architecture. Spring is comprehensive yet modular. You only use what you need. For example, you may only make use of the JDBC support without linking in an entire framework.</li> + <li>Promoting best software development practices. For example, Spring is designed to always promote test-driven development and eliminate the need for factories and singletons.</li> + <li>Inversion of Control. Spring is an application container supporting interceptions and declarative aspect oriented programming.</li> + </ul> + Spring is an open source project; however it is not housed at Apache. + </p> + + <subsection name="Jetspeed + Spring"> + <p> + The Jetspeed portal is configured completely as a Spring application. All services in Jetspeed are constructed and configured as Spring beans. + Jetspeed runs in a Spring container. Spring provides a great environment for customization your deployment of Jetspeed. Some of the + added benefits of Spring in Jetspeed are: + <ul> + <li>Aspect Oriented Programming in the Spring configuration files.</li> + <li>Hot swapping: allows implementation hiding and swapping.</li> + <li>Failover: failover to next component when a component fails.</li> + <li>Multicasting: multicasting of method invocation to multiple components.</li> + <li>Lifecycle management: starting, pausing and resuming components.</li> + </ul> + </p> + </subsection> + + <subsection name="Components run in a Spring Container"> + <p> + Jetspeed, as a Spring application, is a collection of components, or services, all assembled together to create a complete working portal. If you look at from this point of view, you + can see the major portal components being managed by the container, which is really just a Spring container as shown in the diagram below. Note this is by no way an inclusive list of all Jetspeed services wired in Spring: + </p> + <p> + <img src="images/jetspeed-portal-container.jpg" border="0"/><br/><br/> + </p> + </subsection> + + + <subsection name="Programming to the Jetspeed API"> + <p> + When developing Jetspeed core, Jetspeed extensions, or Jetspeed Administrative Portlets, you should always program to the Jetspeed API. + All Jetspeed Components are wired together on interfaces, not class implementations. This contract-by-interface approach to programming makes for a powerful + and extensible programming model for developing enterprise portal applications. When you are configuring your Jetspeed Spring components (beans), you will see + that components have their dependencies wired in to other Jetspeed components via dependency injection. The injected dependencies are always interfaces. + Dependencies are declaratively managed in the Spring configuration. In Jetspeed, we support both constructor + and setter dependency injection. Here is an example of a component having its dependencies constructor-injected: + </p> + <p> + <source><![CDATA[ +<bean id='PortalAdministrationImpl' init-method="start" + class='org.apache.jetspeed.administration.PortalAdministrationImpl'> + <constructor-arg index='0'> + <ref bean="org.apache.jetspeed.security.UserManager"/> + </constructor-arg> + <constructor-arg index='1'> + <ref bean="org.apache.jetspeed.security.RoleManager"/> + </constructor-arg> + <constructor-arg index='2'> + <ref bean="org.apache.jetspeed.security.GroupManager"/> + </constructor-arg> + <constructor-arg index='3'> + <ref bean="org.apache.jetspeed.page.PageManager"/> + </constructor-arg> + <constructor-arg index='4'> + <ref bean="org.apache.jetspeed.prefs.PreferencesProvider"/> + </constructor-arg> + <constructor-arg index='5'> + <ref bean="org.apache.jetspeed.profiler.Profiler"/> + </constructor-arg> + <constructor-arg index='6'> + <ref bean="mailSender"/> + </constructor-arg> + <constructor-arg index='7'> + <ref bean="adminVelocityEngine"/> + </constructor-arg> +</bean> + ]]></source> + </p> + <p>And here is the Java code constructor matching the Spring configuration. Notice that the dependencies injected are interfaces, not concrete class implementations: + </p> + <source><![CDATA[ +public PortalAdministrationImpl( UserManager userManager, + RoleManager roleManager, + GroupManager groupManager, + PageManager pageManager, + PreferencesProvider preferences, + Profiler profiler, + JavaMailSender mailSender, + VelocityEngine velocityEngine) + ]]></source> + + </subsection> + + </section> + </body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-sso.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-sso.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-sso.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/config-sso.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,298 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<document> +<properties> + <title>Guide to Federated Security</title> + <subtitle>Federated Security Configuration Overview</subtitle> + <authors> + <person name="David Sean Taylor" email="[email protected]" /> + </authors> +</properties> +<body> + +<section name="SSO and Federated Identify Management"> + <p> + +SSO, or Single Signon, is a way for organizations to centralize their identity management and authentication needs in a consolidated, single solution across multiple applications in the enterprise. +There are quite a few solutions available to enterprise to implement SSO with. Jetspeed classifies SSO in two categories: +</p> +<ul> +<li>Jetspeed SSO</li> +<li>External Identity Management Solutions</li> +</ul> +<p> +The first, Jetspeed SSO, is a rather simpler solution for enterprise applications who do not need the complexity of a robust identity management SSO solution. In this case, Jetspeed provides a credential store +for user credentials. Jetspeed can store encrypted credentials for users or groups of users to external sites. The second solution requires a third party open source project or product. In this case, Jetspeed +integrates with an external SSO solution. These external solutions can often a single-signon solution for an organization, or even a federation of organizations. +</p> +<subsection name='Jetspeed SSO'> +<p> +Jetspeed SSO uses Jetspeed and Java security to implement a set of services and portlets for storing credentials. A <a href='../adminguide/sso.html'>management administrative portlet</a> allows the editing of SSO sites and remote credentials. +Jetspeed SSO comes with a secure IFrame and Web Content set of portlets. These portlets allow you to secure access to external sites. +Authentication suport includes: +</p> +<ul><li><b>Basic authentication</b> is the default and can be supported effectively without even setting the <b>sso.type</b> preference. +Simply provide credentials for the domain, and basic authentication defaults. The credentials will not be sent preemptively, +but if a 401 request is returned for Basic authentication, it will be handled properly. +This is equivalent to setting the preference sso.type=basic (or sso.type=html (old - now deprecated in favor of calling it <b>basic</b>). +if you set sso.type=basic.preemptive, it will send the credentials preemptively. +</li> +<li><b>URL authentication</b> (query args) is supported as <b>sso.type=url</b> or <b>sso.type=url.base64</b>. +By definition, this type of authentication is <quote>preemptive</quote>, so no distinction is made +there. +</li> +<li> +<b>Form-authentication</b> is supported with <b>sso.type=form</b> (which is equivalent to sso.type=form.post - you can also specify sso.type=form.get, +if GET protocol is used on the login form). This form also requires a bunch of other data +( e.g. the action URL, other args, names of the fields for credentials, etc.). +All of this is in an example that is in the demo portlet.xml. +Form-based authentication is also considred "preemptive", in that it authenticates before any other +content is read. However, it only does it once. If it succeeds, all should be well. +If it fails, the user will have to login by hand (since the initial content URL will +cause a redirect to the login page). +</li> +<p>Here are some examples of preferences that can be set for the SSO IFrame and SSO Content portlets:</p> +<source><![CDATA[ + <preference> + <name>sso.type</name> + <value>basic | url | form</value> + </preference> + <preference> + <name>sso.url.Principal</name> + <value>sso-principal</value> + </preference> + <preference> + <name>sso.url.Credential</name> + <value>sso-credential</value> + </preference> + <preference> + <name>SRC</name> + <value>http://www.nytimes.com</value> + </preference> + <preference> + <name>sso.type</name> + <value>form</value> + </preference> + <preference> + <name>sso.form.Action</name> + <value>http://www.nytimes.com/auth/login</value> + </preference> + <preference> + <name>sso.form.Principal</name> + <value>USERID</value> + </preference> + <preference> + <name>sso.form.Credential</name> + <value>PASSWORD</value> + </preference> + <preference> + <name>sso.form.Args</name> + <value>Submit2=Log In;OP=;OQ=;is_continue=false</value> + </preference> +]]></source> + +</ul> +</subsection> +<subsection name='Integrating with External SSO'> + <p> + To enable an identity management service, such as Site Minder, or Shibbboleth (see below), there are some general guidelines for integrating your SSO solution with Jetspeed. + + + remove the + Login Portlet from the custom build and delegate authentication to the authentication + provider. Upon successful authentication, redirect to the portal. + + <ol> + <li>Remove the Login Portlet from your custom home page. You will no longer need it. The third party SSO will handle all authentication. You will need to + configure the third party SSO to redirect to the Jetspeed portal upon successful authentication. All authentication activities are removed from Jetspeed. + </li> + <li>Modify the Jetspeed web.xml to include any required settings for your SSO solution. You might need to enable this filter and mapping: +<source><![CDATA[ + <filter> + <filter-name>PortalFilter</filter-name> + <filter-class>org.apache.jetspeed.login.filter.PortalFilter</filter-class> + </filter> + <filter-mapping> + <filter-name>PortalFilter</filter-name> + <url-pattern>/*</url-pattern> + </filter-mapping> +]]></source> + </li> + <li>Additional edits to the Jetspeed web.xml recommended:</li> + <ul> + <li>remove security-config for the login portlet +<source><![CDATA[ + <login-config> + <auth-method>FORM</auth-method> + <realm-name>Jetspeed</realm-name> + <form-login-config> + <form-login-page>/login/login</form-login-page> + <form-error-page>/login/error</form-error-page> + </form-login-config> + </login-config> +]]></source> +</li> + <li>Remove the servlets: LoginProxyServlet, LoginServlet, LoginErrorServlet, LoginRedirectorServlet and LogoutServlet</li> + <li>Remove the servlet-mappings for the above servlets</li> + </ul> + </ol> + </p> +</subsection> +<subsection name='Shibboleth'> +<p> +Jetspeed comes with a Shibboleth filter for performing Single Sign-on (SSO) with Shibboleth and the Jetspeed Portal. + Shibboleth's Service Provider provides HTTP request headers. The filter reads and interprets the Shibboleth headers as single sign-on tokens. + Shibboleth can also be configured to provide various user attributes that can be passed onto the portal. Refer to your Shibboleth documentation for more details. + The Jetspeed Shiboleth filter is configured in the Jetspeed web.xml: +</p> + +<source><![CDATA[ +<filter> + <filter-name>ShibbolethPortalFilter</filter-name> + <filter-class>org.apache.jetspeed.security.impl.shibboleth.ShibbolethPortalFilter + </filter-class> +</filter> +]]></source> +<p> +If there are no Shibboleth headers present, Jetspeed will not authenticate the user. +If there are Shibboleth tokens on the HTTP request, Jetspeed will use them and automatically authenticate users, + bypassing Jetspeed's internal authentication and login mechanisms. +</p> +<p> +To configure Jetspeed to use Shibboleth headers, there is a Spring configuration file found under WEB-INF/assembly/alternate/shibboleth.xml: +</p> + +<source><![CDATA[ +<beans xmlns="http://www.springframework.org/schema/beans"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd";> +<bean id="org.apache.jetspeed.security.shibboleth.ShibbolethConfiguration" + class="org.apache.jetspeed.security.impl.shibboleth.ShibbolethConfiguration"> + <!-- map of common jetspeed-security principals to shibboleth headers --> + <constructor-arg index='0'> + <map> + <entry key='username'> + <value>shib-person-commonname</value> + </entry> + </map> + </constructor-arg> + <!-- Always authenticate against Jetspeed (should be false if your jetspeed db != authentication users) --> + <constructor-arg index='1'> + <value type="boolean">true</value> + </constructor-arg> + <constructor-arg index='2'> + <ref bean="PortalConfiguration" /> + </constructor-arg> + </bean> +</beans> +]]></source> + +<p> +The first constructor argument is a map of common jetspeed security names. Currently we only support mapping the <code>username</code> from a Shibboleth principal. It is configured to map to the Shibboleth header/attribute named <code>sub-person-commonname</code>. +</p> +<p> +The second constructor turns on or off Jetspeed authentication. Turn this off if you simply want to trust Shibboleth or if you don't have passwords available in constructor-arg one. +</p> + + +</subsection> +<subsection name='CAS'> +<p> +The <a href='http://www.jasig.org/cas'>Central Authentication Service</a>, CAS, is a single sign-on protocol for the web. +Like other Single Sign-on systems (SSO), its purpose is to permit a user to access multiple applications while providing their credentials (such as userid and password) only once. +It also allows web applications to authenticate users without gaining access to a user's security credentials, such as a password. +</p> +<p> +Jetspeed is distributed with a CAS servlet filter for performing Single Sign-on (SSO) with CAS and the Jetspeed Portal. + CAS must first be installed into your application server. Once it is installed and configured, users can login via CAS. When they go to visit any Jetspeed pages, + Jetspeed can check to see if CAS has successfully authenticated. If CAS has authenticated, Jetspeed participates in CAS SSO, by using the identity provided by CAS internally. + The following sections describe how to configure Jetspeed with CAS. +</p> +<h4>Configuring the CAS Filter</h4> +<p> + Be sure to configure your application server with CAS here as described here: + <a href='http://www.ja-sig.org/wiki/display/CASC/CAS+Client+for+Java+3.1'>Configuring CAS with Java</a>. Once you have configured the application server with CAS and verified + that is working, then continue with the Jetpeed configuration instructions here. The CAS filter is configured in Jetspeed's web.xml. You will need to add the following lines to the web.xml. + The CAS Filter should be placed in the web.xml before the Jetspeed Portal Filter. Note that the init-params values will be specific to your deployment. We provide some localhost examples here: +</p> +<source><![CDATA[ +<filter> + <filter-name>CAS Filter</filter-name> + <filter-class>edu.yale.its.tp.cas.client.filter.CASFilter</filter-class> + <init-param> + <param-name>edu.yale.its.tp.cas.client.filter.loginUrl</param-name> + <param-value>http://localhost/login</param-value> + </init-param> + <init-param> + <param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name> + <param-value>http://localhost/serviceValidate</param-value> + </init-param> + <init-param> + <param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name> + <param-value>localhost</param-value> + </init-param> +</filter> +]]></source> +<p>Make sure to add the CAS filter mapping to your web.xml as well:</p> +<source><![CDATA[ + <filter-mapping> + <filter-name>CAS Filter</filter-name> + <url-pattern>/portal/caslogin/*</url-pattern> + </filter-mapping> +]]></source> + +<h4>Configuring the Jetspeed CAS Portal Filter</h4> +<p> + The Jetspeed CAS Portal filter reads and interprets the CAS session state to participate in CAS SSO. The Jetspeed CAS Portal filter is configured in Jetspeed's web.xml. + You will need to add the following lines to the web.xml. Make sure to place the filter after(below) the CAS Filter described above. +</p> +<source><![CDATA[ + <filter> + <filter-name>PortalFilter</filter-name> + <filter-class>org.apache.jetspeed.security.impl.cas.CASPortalFilter</filter-class> + </filter> +]]></source> +<p>Make sure to add the filter mapping to your web.xml as well:</p> +<source><![CDATA[ + <filter-mapping> + <filter-name>PortalFilter</filter-name> + <url-pattern>/portal/*</url-pattern> + </filter-mapping> +]]></source> +<p> +If there is no CAS session state, Jetspeed will not authenticate the user. +If there is CAS session state, Jetspeed will use them and automatically authenticate users, + bypassing Jetspeed's internal authentication and login mechanisms. +</p> + +<h4>Logging out</h4> +<p>To enable CAS session logout, add the following init parameter to the Jetspeed Logout Servlet in Jetspeed's web.xml. Note the param value will be specific to your CAS configuration. </p> +<source><![CDATA[ + <servlet> + <servlet-name>LogoutServlet</servlet-name> + <servlet-class>org.apache.jetspeed.login.LogoutServlet</servlet-class> + <init-param> + <param-name>casLogoutUrl</param-name> + <param-value>http://localhost/logout</param-value> + </init-param> + </servlet> +]]></source> + +</subsection> +</section> +</body> +</document> \ No newline at end of file Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/credentials.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/credentials.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/credentials.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/credentials.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,185 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<document> + <properties> + <title>Jetspeed 2 Security - Credentials Management</title> + <authors> + <person name="David Le Strat" email="[email protected]" /> + <person name="Ate Douma" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Managing Credentials"> + <p> + Although the <code>DefaultCredentialHandler</code> provides fine-grained management of credentials, it cannot + provide direct feedback to the user like presenting a warning that the current password is soon to be expired. + But, special request processing pipeline valves provided with jetspeed allow to do just that.</p> + <p> + The configuration for these valves can be found and set in the <code>pipelines.xml</code> spring + configuration file.</p> + <subsection name="LoginValidationValveImpl"> + <p> + The <a href="../apidocs/org/apache/jetspeed/security/impl/LoginValidationValveImpl.html"> + <code>LoginValidationValveImpl</code></a> provides feedback to the user about the cause of an failed login + attempt.</p> + <p> + It retrieves the <code>UserPrincipal</code> and its current <code>PasswordCredential</code> for the + specified user name, and (if found) determines an specific error code based on its state. + This error code is communicated back to through the session so an appropriate error message can be + presented to the user.</p> + <p> + The following possible error codes can be returned (all defined in the + <a href="../apidocs/org/apache/jetspeed/login/LoginConstants.html"> + <code>LoginConstants</code></a> interface):</p> + <ol> + <li>ERROR_UNKNOWN_USER</li> + <li>ERROR_INVALID_PASSWORD</li> + <li>ERROR_USER_DISABLED</li> + <li>ERROR_FINAL_LOGIN_ATTEMPT</li> + <li>ERROR_CREDENTIAL_DISABLED</li> + <li>ERROR_CREDENTIAL_EXPIRED</li> + </ol> + <p> + Of the above error codes, the <code>ERROR_FINAL_LOGIN_ATTEMPT</code> will only be reported if the valve + is configured with the same <code>maxNumberOfAuthenticationFailures</code> value as used for the + related <code>MaxPasswordAuthenticationFailuresInterceptor</code> described above:</p> + <source><![CDATA[ + <bean id="loginValidationValve" + class="org.apache.jetspeed.security.impl.LoginValidationValveImpl" + init-method="initialize"> + <!-- maxNumberOfAuthenticationFailures + This value should be in sync with the value for + org.apache.jetspeed.security.spi.impl.MaxPasswordAuthenticationFailuresInterceptor + (if used) to make sense. + Any value < 2 will suppress the LoginConststants.ERROR_FINAL_LOGIN_ATTEMPT + error code when only one last attempt is possible before the credential + will be disabled after the next authentication failure. + --> + <constructor-arg index="0"><value>3</value></constructor-arg> + <constructor-arg index="1"> + <list> + <value>org.apache.jetspeed.powertool.actions</value> + </list> + </constructor-arg> +</bean>]]> + </source> <p> +Along with enabling the Login Validation Valve, make sure to add the MaxPasswordAuthenticationFailuresInterceptor to +the Credential Policy Manager and ensure the Login Attempts values are in sync. Out of the box, the MaxPasswordAuthenticationFailuresInterceptor + is not configured. + </p> +<source><![CDATA[ +<bean id="org.apache.jetspeed.security.spi.impl.UserPasswordCredentialPolicyManagerImpl" + class="org.apache.jetspeed.security.spi.impl.UserPasswordCredentialPolicyManagerImpl"> + <meta key="j2:cat" value="default or security" /> + <constructor-arg index="0" ref="org.apache.jetspeed.security.CredentialPasswordEncoder" /> + <constructor-arg index="1" ref="org.apache.jetspeed.security.CredentialPasswordValidator" /> + <constructor-arg index="2"> + <list> + <!-- enforce an invalid preset password value in the persisent store is required to be changed --> + <bean class="org.apache.jetspeed.security.spi.impl.ValidatePasswordOnLoadInterceptor" /> + <!-- ensure preset cleartext passwords in the persistent store will be encoded on first use --> + <bean class="org.apache.jetspeed.security.spi.impl.EncodePasswordOnFirstLoadInterceptor" /> + + <bean class="org.apache.jetspeed.security.spi.impl.MaxPasswordAuthenticationFailuresInterceptor"> + <constructor-arg index="0"><value>3</value></constructor-arg> + </bean> + + <!-- Password Expiration interceptor. Required for enabling password expirations. This example is set at 30 days --> + <bean class="org.apache.jetspeed.security.spi.impl.PasswordExpirationInterceptor"> + <constructor-arg index="0"><value>30</value></constructor-arg> + </bean> + </list> + </constructor-arg> + </bean> +]]></source> + </subsection> + <subsection name="PasswordCredentialValveImpl"> + <p> + The <a href="../apidocs/org/apache/jetspeed/security/impl/PasswordCredentialValveImpl.html"> + <code>PasswordCredentialValveImpl</code></a> is meant to be used together with a special Portlet on a + special Portal Page (PSML) to automatically request or even require a user to change its password.</p> + <p> + This valve evaluates <code>PasswordCredential.isUpdateRequired()</code> and optionally the + <code>expirationDate</code>, <code>lastAuthenticationDate</code> and <code>previousAuthenticationDate</code> + fields to determine if a user is required or just be asked to change its password.</p> + <p> + This valve can optionally be configured with a list of <code>expirationWarningDays</code> numbers in + its constructor: + <source><![CDATA[ +<bean id="passwordCredentialValve" + class="org.apache.jetspeed.security.impl.PasswordCredentialValveImpl" + init-method="initialize"> + <constructor-arg> + <!-- expirationWarningDays --> + <list> + <value>2</value> + <value>3</value> + <value>7</value> + </list> + </constructor-arg> +</bean>]]> + </source> + These numbers each represent a day before the current <code>expirationDate</code> of the password credential + when a user should be warned its password is soon to expire and be asked to change it. The + <code>lastAuthenticationDate</code> and the <code>previousAuthenticationDate</code> are used to determine + when this should happen. It will be done only once for each configured <code>expirationWarningDay</code>. + If a user logs on for the first time (after several days) with the above example configuration, 6 days + before the password expires, he or she will be warned about it. And again when 3 or 2 days are left.</p> + <p> + When a user logs on the last day before the password expires <em>or</em> when <code>updateRequired</code> + is <code>true</code>, the user will be required to change the password, regardless if expirationWarningDays + are configured or not.</p> + <p> + To be able to automatically provide the user with this information and allow or require the password to + be changed directly after login, a special <code>ProfileLocator</code> + <a href="../apidocs/org/apache/jetspeed/profiler/ProfileLocator.html#SECURITY_LOCATOR"> + <code>SECURITY_LOCATOR</code></a> is used. The <code>PageProfilerValve</code> (which should be configed + <em>after</em> this valve in the pipeline) will then use this enforced locator to be used to find the + related portal page to present to the user.</p> + <p> + For this to work, a <code>"security"</code> Profiler rule must have been setup like the default one + provided by Jetspeed:</p> + <p align="center"> + <img src="../deployguide/images/security-locator.jpg" border="0"/> + </p> + <p> + As can seen from the above image, the default page which will be presented to the user is the + <code>/my-account.psml</code> located in the root.</p> + <p> + This default page contains only one portlet, the <code>ChangePasswordPortlet</code> from the security + Portlet Application.</p> + <p> + The <code>ChangePasswordPortlet</code> works together with the <code>PasswordCredentialValveImpl</code> + as it checks for the + <a href="../apidocs/org/apache/jetspeed/security/PasswordCredential.html#PASSWORD_CREDENTIAL_DAYS_VALID_REQUEST_ATTR_KEY"> + <code>PASSWORD_CREDENTIAL_DAYS_VALID_REQUEST_ATTR_KEY</code></a> request parameter which will be set by + this valve with the number of days the password is still valid. For a required password change this will + be set to Integer(0).</p> + <p> + The default <code>my-account.psml</code> page contains <em>only</em> the <code>ChangePasswordPortlet</code> + to make sure a user which is <em>required</em> to change the password cannot interact with the portal any + other way then after the password is changed.</p> + <p> + Although the user might be attempted to select a link to a different page (from a portal menu for exampl), + this valve will make sure only the configured "security" locator page is returned if it is required. + But, once the password is changed the then targeted page in the url will be navigated to automatically. + </p> + </subsection> + </section> + </body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/deploy-tools.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/deploy-tools.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/deploy-tools.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-deploy/src/site/xdoc/deploy-tools.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,90 @@ +<?xml version="1.0" ?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<document> + <properties> + <title>Jetspeed-2 Deploy Tools</title> + <authors> + <person name="David Le Strat" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="The Role of Jetspeed Deploy Tools"> + <subsection name="JetspeedDeploy and the DeploymentManager"> + <p> + The Jetpeed Deployment tool (JetspeedDeploy) prepares portlet applications for deployment within the Jetspeed Portal. Jetspeed requires + that a servlet be added to all portlet application's web.xml declarations before the portlet application can be run with Jetpeed. + Your portlet application can be prepared for deployment by you manually editing the web.xml and adding the required servlet, or the tool + can be used standalone, from the command line. Or, you can also rely on Jetspeed to add the servlet itself, as the deploy tool is built + into the Jetspeed Portal itself. Inside the portal, when a new + portlet deployment event is registered, the <code>DeployPortletAppEventListener</code> invokes <code>JetspeedDeploy</code> tool + to prepare the portlet application for deployment. When are new events registered? When you drop the portlet application WAR in the deploy + directory, which is located by default in the Jetspeed WEB-INF/deploy directory. + <code>JetspeedDeploy</code> copies the web application archives (.war) from the WEB-INF/deploy directory to the + destination directory (for example, the Tomcat /webapps directory) and parses the <code>web.xml</code>, <code>portlet.xml</code>, and <code>context.xml</code> + to ensure their compliance with the Jetspeed-2 portal engine. + </p> + <p> + <img src="images/jetspeed-deploy-c.gif" border="0"/><br/><br/> + </p> + <p> + The deploy tool then infuses the <code>web.xml</code> + with the <code>JetspeedContainer</code> servlet if it does not already exist, which is necessary for any portlet application deployed to Jetpeed: + <source> + <servlet> + <servlet-name>JetspeedContainer</servlet-name> + <display-name>Jetspeed Container</display-name> + <description>MVC Servlet for Jetspeed Portlet Applications</description> + <servlet-class>org.apache.jetspeed.container.JetspeedContainerServlet</servlet-class> + <init-param> + <param-name>contextName</param-name> + <param-value>${portlet-application-name}</param-value> + </init-param> + <load-on-startup>0</load-on-startup> + </servlet> + ... + <servlet-mapping> + <servlet-name>JetspeedContainer</servlet-name> + <url-pattern>/container/*</url-pattern> + </servlet-mapping> + </source> + </p> + <p> + In the same fashion, the <code>JetspeedDeploy</code> invokes the <code>JetspeedContextRewriter</code> to manipulate + a portlet application <code>context.xml</code> file. For more information about Tomcat <code>context.xml</code>, + see <a href="http://tomcat.apache.org/tomcat-6.0-doc/deployer-howto.html#A%20word%20on%20Contexts";>tomcat's documentation</a>. + </p> + </subsection> + <subsection name="JetspeedDeploy Standalone Usage"> + <p> + <code>JetspeedDeploy</code> can also be invoke through the command line: + <source> + java -jar jetspeed-deploy-tools-<version>.jar -s inputWarPath outputWarPath + </source> + where: + <ul> + <li><code>-s</code>: flag indicating whether or not to strip to loggers from the application. When the flag is present, the + loggers available in the application will be removed.</li> + <li><code>inputWarPath</code>: the path of the war to process.</li> + <li><code>outputWarPath</code>: the path of the processed war.</li> + </ul> + </p> + </subsection> + </section> + </body> +</document> +
