AEM Portals and Portlets aem-portals-and-portlets

This document describes the following:

AEM Portal Architecture aem-portal-architecture

AEM portal architecture includes definitions of portals and portlets.

What is a portal? what-is-a-portal

A portal is a web application that provides personalization, single sign on, content integration from different sources, and hosts the presentation layer of information systems.

You can run JSR 286-compliant portlets in AEM. The portlet component lets you embed a portlet on the page. See Administering the AEM Content Portlet.

What is a portlet? what-is-a-portlet

Portlets are web components deployed inside of a container that generate dynamic content. The portlet interface is packaged and deployed as a .war file inside of a portlet container. If you are running AEM as a portal, you need the portlet’s .war file to run the portlet.

To configure AEM content to appear in a portal, see Installing, Configuring, and Using AEM in a portlet.

AEM Portal Director aem-portal-director

Administering the AEM Content Portlet administering-the-aem-content-portlet

The AEM content portlet enables you to display AEM content in a portal. The portlet is available at /crx-quickstart/opt/portal, and can be customized in various ways. For example, you can customize the SSO/Authentication handling by deploying your own authentication service generating the required authentication information for AEM to overwrite the default behavior. The plugins use a defined API that lets you add your own functionality by building the plugin against the API. The plugin can be deployed into the running portlet. To function properly, it needs a configuration of the AEM author and publish instance together with the content path to display on startup.

Some of the configurations can be changed through portlet preferences and others through OSGi service configurations. You change these configurations using config files or the OSGi web console.

Portlet Preferences portlet-preferences

Porlet preferences can be configured at deployment time in the portal server or by editing the WEB-INF/portlet.xml file before deploying the portlet web application. The portlet.xml file appears as follows by default:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="https://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
             xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="https://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd /opt/SUNWps/dtd/portlet.xsd"
             version="1.0">
   <portlet>
      <portlet-name>RSSWeatherPortlet</portlet-name>
      <portlet-class>org.jboss.portlet.weather.WeatherPortlet</portlet-class>
      <init-param>
         <name>default_zipcode</name>
         <value>05673</value>
      </init-param>
      <init-param>
         <name>RSS_XSL</name>
         <value>/WEB-INF/Rss.xsl</value>
      </init-param>
      <init-param>
         <name>base_url</name>
         <value>https://xml.weather.yahoo.com/forecastrss?p=</value>
      </init-param>
      <expiration-cache>180</expiration-cache>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>VIEW</portlet-mode>
         <portlet-mode>EDIT</portlet-mode>
      </supports>
      <portlet-info>
         <title>Weather Portlet</title>
      </portlet-info>
      <portlet-preferences>
         <preference>
            <name>expires</name>
            <value>180</value>
         </preference>
         <preference>
            <name>RssXml</name>
            <value>https://xml.weather.yahoo.com/forecastrss?p=33145</value>
            <read-only>false</read-only>
         </preference>
      </portlet-preferences>
   </portlet>
</portlet-app>

The portlet can be configured with the following preferences:

OSGi Web Console osgi-web-console

Assuming the portal server runs on host localhost, port 8080 and the AEM portlet web application is mounted in the web application context cqportlet, the URL for the web console is https://localhost:8080/cqportlet/cqbridge/system/console. The default user and password is admin.

Open the Configurations tab and select Portal Directory CQ Server Configuration. Here you specify the base URL to the author and the publish instance. This procedure is described in Configuring the Portlet.

Providing Configurations providing-configurations

To support automated deployments and configuration provisioning, the AEM content portlet has built-in configuration support that tries to read configurations from the classpath provided to the portlet application.

On startup, the system property com.day.cq.portet.config is read to detect the current environment. Usually, the value of this property is something like dev, prod, test, and so on. If no environment is set, no configurations are read.

If an environment is set, a config file is searched in the classpath at* *com/day/cq/portlet/{env}.config where env is replaced with the actual value for the environment. This file should list all configuration files for this environment. These files are searched relative to the location of the config file. For example, if the file contains a line my.service.xml, this file is read from the classpath at com/day/cq/portlet/my.service.config. The name of the file consists of the persistence ID of the service, followed by .config. In the previous example, the persistence ID is my.service. The format of the configuration file, is the format used by the Apache Sling OSGi installer.

This means, for each environment, a corresponding config file needs to be added. A configuration that should be applied to all environments needs to be entered in all these files - if it is just for a single environment, it is just entered in that file. This mechanism ensures full control over which configuration is read in which environment.

It is possible to use a different system property to detect the environment. Specify the system property com.day.cq.portet.configproperty containing the name of the system property to use instead of com.day.cq.portet.config.

Caching and Caching Invalidation caching-and-caching-invalidation

The portlet, in its default configuration, caches the responses it receives from AEM WCM in a user-specific cache. The caches need to be invalidated when changes occur in the content of the publish instance. For this purpose, in AEM WCM a replication agent must be configured on the author instance. The cache can also be flushed manually. This section describes both of those procedures.

The portlet can be configured with its own cache, so that the content in the portlet displays without requiring access to AEM. The portal is available as content in /libs/portal/director. To access the content, start a AEM instance and download, using CRXDE Lite or Webdav, the file from that location.

You can either deploy this bundle at runtime or add it to the portlet web application at WEB-INF/lib/resources/bundles before the deployment.

After the cache is deployed, the portlet caches contents from the publish instance. The portlet cache can be invalidated with a dispatcher flush from AEM. To configure the portlet to use its own cache:

Flushing the Cache via Replication Agent flushing-the-cache-via-replication-agent

Just like the normal dispatcher invalidation, a replication agent can be configured to target the portal’s AEM portlet cache. After you configure the replication agent, every regular page activation flushes the portal cache.

If you operate several portal nodes running the AEM portlet, you need to create an agent for each node as described in this procedure.

To configure a replication agent for the portal:

Manually Flushing the Portlet Cache manually-flushing-the-portlet-cache

You can manually flush the portlet cache by accessing the same URL configured for the replication agent. See Flushing the Cache for the form of the URL. In addition, the URL needs to be extended with a URL parameter Path=<path> to indicate what to flush.

For example:

https://10.0.20.99:10040/wps/PA_CQ5_Portlet/cqbridge/cqpcache?Path=* flushes the complete cache. https://10.0.20.99:10040/wps/PA_CQ5_Portlet/cqbridge/cqpcache?Path=/content/mypage/xyz flushes /content/mypage/xyz from the cache.

Portal Security portal-security

The portal is the driving authentication mechanism. You can log into AEM either with a technical user, the portal user, a group, and so on. The portlet has no access to the password for the user in the portal, so if the portlet does not know all the credentials to successfully log in a user, an SSO solution must be used. In this case, the AEM portlet forwards all required information to AEM, which in turn forwards this information to the underlying AEM repository. This behavior is pluggable and can be customized.

Authentication on Publish authentication-on-publish

This section describes the available authentication modes the portlet can use in communicating with the underlying AEM WCM instances.

By default no user information is sent to the publish instance of AEM; the content is always displayed as the anonymous user. If user specific information should be delivered from AEM or if user authentication for publish is required, this has to be turned on.

Accessing the Portlet’s Authentication Configuration accessing-the-portlet-s-authentication-configuration

Authentication configuration options that the portlet uses in AEM WCM instances are available in the Web console (OSGi configuration).

To access the portlet’s authentication configuration:

Technical User Mode technical-user-mode

In default mode, all requests issued by the portlet for the AEM WCM author instance are authenticated using the same technical user, regardless of the current portal user. Technical User mode is enabled by default. You enable/disable this mode in the respective configuration screen in the OSGi management console:

The technical user specified must exist on the AEM WCM author instance and on the publish instance if Authenticate on Publish is enabled. Be sure to give the user access privileges sufficient for authoring work.

SSO sso

The portlet supports SSO with AEM out of the box. The authenticator service can be configured to use SSO and transmit the current portal user with format Basic as a cookie named cqpsso to AEM. AEM should be configured to use the SSO authentication handler for path /. The cookie name needs to be configured here as well.

The crx-quickstart/repository/repository.xml for AEM repository needs to be configured accordingly:

<LoginModule class="com.day.crx.security.authentication.CRXLoginModule">
  ...
  <param name="trust_credentials_attribute" value="TrustedInfo"/>
  <param name="anonymous_principal" value="anonymous"/>
</LoginModule>

SSO Authentication Mode sso-authentication-mode

The portlet can authenticate for AEM WCM using the Single Sign On (SSO) scheme. In this mode, the user currently logged in to the portal is forwarded to AEM WCM in the form of an SSO cookie. If SSO mode is used, all portal users with access to the AEM portlet must be known to the underlying AEM WCM instances, most commonly in the form of AEM WCM being connected to LDAP, or by having manually created the users beforehand. Also, before enabling SSO in the portlet, the underlying AEM WCM author instance (and the publish instance, if Authenticate on Publish is enabled) needs to be configured to accept SSO-based requests.

To configure the portlet to use SSO authentication mode, complete the following steps (described in detail in the following sections):

Enabling AEM WCM’s repository to accept trusted credentials enabling-aem-wcm-s-repository-to-accept-trusted-credentials

Before SSO can be enabled for AEM WCM, the underlying repository needs to be configured to accept the trusted credentials provided by AEM WCM. To do this, you configure AEM’s repository.xml.

Enabling SSO authentication in the AEM WCM enabling-sso-authentication-in-the-aem-wcm

To enable SSO in AEM WCM, access the relevant configuration entry in the AEM WCM’s Apache Felix Web Management Console (OSGi):

For every request AEM WCM receives, first the SSO-based authentication is attempted. Upon failure, a fallback to the usual basic authentication scheme is performed. As such, normal connections to AEM WCM without SSO remain possible.

Enabling SSO Authentication in a AEM Portlet enabling-sso-authentication-in-a-aem-portlet

In order for the underlying AEM WCM instance to accept SSO requests, the portlet’s authentication mode has to be switched from Technical to SSO.

To enable SSO authentication in a AEM portlet:

After performing this procedure, requests are authenticated using SSO. A typical snippet from the HTTP communication reveals the presence of the following SSO and Portlet specific headers:

C-12-#001898 -> [GET /mynet/en/_jcr_content/par/textimage/image.img.png HTTP/1.1 ]
C-12-#001963 -> [cq5:locale: en ]
C-12-#001979 -> [cq5:used-locale: en ]
C-12-#002000 -> [cq5:locales: en,en_US ]
C-12-#002023 -> [cqp:user: wpadmin ]
C-12-#002042 -> [cqp:portal: IBM WebSphere Portal/6.1 ]
C-12-#002080 -> [cqp:windowid: 7_CGAH47L000CE302V2KFNOG0084 ]
C-12-#002124 -> [cqp:windowstate: normal ]
C-12-#002149 -> [cqp:portletmode: view ]
C-12-#002172 -> [User-Agent: Jakarta Commons-HttpClient/3.1 ]
C-12-#002216 -> [Host: 10.0.0.68:4502 ]
C-12-#002238 -> [Cookie: $Version=0; cqpsso=Basic+d3BhZG1pbg%3D%3D ]
C-12-#002289 -> [ ]

Enabling PIN authentication enabling-pin-authentication

If you are not using the default inline editing features of the AEM content portlet, but want the authoring and administration part of the portlet outside the portal directly in the AEM author instance, you should enable PIN authentication. You also need to change the configuration of the management buttons.

To open the website administration page or to edit a page from the portlet, the AEM content portlet uses the new pin authentication. By default, the pin authentication is disabled, therefore, the following configuration changes have to be made in AEM:

Privileges privileges

Some functions of the portlet are protected by privileges. The current user needs to have this privilege to be able to access this function. There are the following privileges pre-defined:

The best approach to manage the privileges is to use portal roles and assign roles to these privileges. This can be done through an OSGi configuration. The “Day Portal Director Privilege Manager” can be configured with a set of roles for each privilege. If the user has one of the roles, the user has the corresponding privilege.

In addition it is possible to define this role based access on a per portlet instance base. The preferences dialog of the portlet contains an input field for each of the above privileges. For each privilege a comma-separated list of portlet roles can be configured. If a value is configured, this overrides the global configuration from the “Day Portal Director Privilege Manager” service and it might be required to add the same roles from this global setting as the roles are not merged! If no value is specified, the global configuration is used.

Customizing the AEM portlet application customizing-the-aem-portlet-application

The provided AEM portlet application starts an OSGi container inside the web application just as AEM does. This architecture lets you use all the benefits of OSGi:

Toolbar Buttons toolbar-buttons

The toolbar and its buttons are configurable and can be customized. You can add your own buttons to the toolbar or define which buttons are displayed in which mode. Each button is an OSGi service configurable through an OSGi configuration.

The OSGi web console lists all button configurations on the Configuration tab. For each button, you can define in which mode this button is displayed. This lets you disable a button by removing all modes for example.

By default, the AEM content portlet uses the inline editing functionality. However, if you prefer to switch into the AEM author instance for editing, enable the SiteAdmin Button and the ContentFinder Button, but disable the Edit Button. In this case, make sure to correctly configure the PIN authentication in AEM.

The portlet’s toolbar layout can be customized by installing a bundle through the portlet’s Felix Web Console, which contains custom CSS/HTML at a predefined location.

Bundle Structure bundle-structure

The following is an example bundle structure:

$ jar tvf target/toolbarlayout-0.0.1-SNAPSHOT.jar | awk '{print $8}'
META-INF/
META-INF/MANIFEST.MF
/com/day/cq/portlet/toolbar/layout/
/com/day/cq/portlet/toolbar/layout/author.gif
/com/day/cq/portlet/toolbar/layout/back.gif
/com/day/cq/portlet/toolbar/layout/button.html
/com/day/cq/portlet/toolbar/layout/edit.gif
/com/day/cq/portlet/toolbar/layout/manage.html
/com/day/cq/portlet/toolbar/layout/publish.html
/com/day/cq/portlet/toolbar/layout/refresh.gif
/com/day/cq/portlet/toolbar/layout/siteadmin.gif
/com/day/cq/portlet/toolbar/layout/toolbar.css

The META-INF folder contains the MANIFEST.MF file required by OSGi to identify it as a bundle. It appears as follows:

Manifest-Version: 1.0
Built-By: djaeggi
Created-By: Apache Maven Bundle Plugin
Import-Package: com.day.cq.portlet.toolbar.layout
Bnd-LastModified: 1234178347159
Export-Package: com.day.cq.portlet.toolbar.layout
Bundle-Version: 0.0.1.SNAPSHOT
Bundle-Name: Company CQ5 Portal Director Portlet Toolbar Layout
Bundle-Description: This bundle provides a custom layout for the CQ5 P
 ortal Director Portlet Toolbar.
Build-Jdk: 1.5.0_16
Bundle-ManifestVersion: 2
Bundle-SymbolicName: com.day.cq.portlet.company.toolbarlayout
Tool: Bnd-0.0.255

The fact that the HTML/CSS/images are within the /com/day/cq/portlet/toolbar/layout folder is mandated by the portlet and cannot be changed. Along the same lines, the Import-Package and Export-Package headers in MANIFEST.MF must be called /com/day/cq/portlet/toolbar/layout as well. The Bundle-SymbolicName must be a unique, fully qualified package name.

You can build it using a tool such as maven or manually create such a jar file with the relevant header set as shown in this section.

Portlet Toolbar Views portlet-toolbar-views

The portlet’s toolbar basically has two view states. Each view and associated buttons can be customized with a respective HTML file.

Publish View publish-view

The publish view only has one button that switches the toolbar to the Manage view. The publish view is represented by the publish.html file in previous bundle. In the HTML, you can use the following placeholders, which are replaced by the portlet with the respective contents when rendered:

Publish View Placeholders publish-view-placeholders

Manage View manage-view

The manage view has four buttons: Edit, Websites tab, Refresh and Back. The manage view is represented by the manage.html file in the previous bundle. In the HTML, you can use the following placeholders, which are replaced by the portlet with the respective contents when rendered:

Manage View Placeholders manage-view-placeholders

Buttons buttons

Buttons, on whichever view they appear, use the same common HTML, defined in button.html.

In the HTML, you can use the following placeholders, which are replaced by the portlet with the respective contents when rendered:

Manage and Publish View Buttons manage-and-publish-view-buttons

Example of a button.html file:

<div class="cqp_button">

 <a href="#" onclick="{onclick}">

 <img src="/wps/PA_CQ5_Portlet/cqbridge/static/{id}.gif" alt="{text}"
title="{text}"/>

 </a>
</div>

Installing a Custom Layout installing-a-custom-layout

To install a custom layout, access the portlet’s OSGI Web console **Bundles **section and upload the bundle.

Packages packages

If you need to upload, or create, packages for your installation, then see Package Manager in the AEM documentation for detailed instructions.

Link Handling link-handling

All links are rewritten to work within the portal context. By default links with render parameters are used. The Portal Director HTML Rewriter can be configured to use action links instead.

You can also define additional request parameters to be queried for the content path to be displayed. This is useful, for example, if there is a link from the outside to specific content.

In addition, the Portal Director HTML Rewriter can be configured with a list of regular expressions defined excludes for link rewriting. For example, if you have relative links to external systems, you should add them to this exclude list.

Localization localization

The AEM content portlet has a built-in localization feature, which ensures that the content from AEM is in the correct language.

This is done in two steps:

The Portal Director Locale Handler can be configured with the paths to check for locale information - usually this includes everything under /content and with the position of the locale information in the path. By default, the locale handler follows the recommondation of structuring multi-language sites within AEM.

If your site has no strict rule for handling the locale information within the path, it is possible to replace the locale handler with your own implementation.

Optional OSGi Services optional-osgi-services

Optional OSGi services can be implemented to customize various parts of the portlet. Each service corresponds to a Java interface. This interface can be implemented and deployed through a bundle into the portlet.

Replacing Default Services replacing-default-services

The following services have a default implementation in the content portlet (with a corresponding Java interface). To customize, a bundle containing the new service implementation needs to be deployed into the portlet application.

When implementing such a service, make sure to set the service.ranking property of the service to a positive value. The default implementation uses the ranking** 0** and the portlet uses the service with the highest ranking.

Portlet Events portlet-events

The portlet API (JSR-286) specifies portlet events. The AEM content portlet has an integrated bridge, distributing portlet events for the AEM portlet as OSGi events - this makes handling of portlet events pluggable.

If you want to handle specific events, declare these as receiving events in the deployment descriptor (or configure it through your portal server) and implement an OSGi service declaring the EventHandler interface (see OSGi EventAdmin specification).

Whenever a portlet event occurs, a specific OSGi event is sent invoking your handler. The handler gets all context information and can update the status of the portlet accordingly or sent new events. Basically, inside the handle method all functionality of the portlet event phase can be used.

Using AEM as a Portal using-aem-as-a-portal

Use the Portlet component to add portlet windows to AEM pages. Shared libraries that you install to the application server enable the Portlet component to detect deployed portlet applications.

To use AEM as a portal, perform the following tasks:

Installing the portlet component installing-the-portlet-component

The AEM Quickstart JAR file contains the portlet component files. To obtain the files (cq-portlet-components.zip), you can either execute the Quickstart, or extract the contents.

Adding the Portlet component to Sidekick adding-the-portlet-component-to-sidekick

Add the portlet component to the paragraph system so that it is available to authors.

Configuring and deploying your portlet applications configuring-and-deploying-your-portlet-applications

Deploy the portlets to the application server web container so that they are available to the Portal component. Before you deploy the portlet application, you need to configure the application so that it loads the AEM portal container servlet. This configuration enables the Portlet component to access the portlets.

Adding portlets to your AEM page adding-portlets-to-your-aem-page

Use the Portal component to add a portlet window to your web page. Use the component properties to specify the portlet to display.

Installing, Configuring, and Using AEM in a Portlet installing-configuring-and-using-aem-in-a-portlet

To access content provided by AEM WCM, the portal server needs to be fitted with the AEM Portal Director Portlet. You do this by installing, configuring, and adding the portlet to the portal page by using the steps provided in this section.

By default, the portlet connects to the publish instance at localhost:4503 and to the author instance at localhost:4502. These values can be changed during deployment of the portlet. The portal director is available as content in the repository under /libs/portal/directory. Download the application war file before using it.

Downloading the war file downloading-the-war-file

Installing the portlet installing-the-portlet

To install the portlet:

Configuring the Portlet configuring-the-portlet

After you install the portlet, you need to configure it so that it knows the URLs of the underlying AEM instances (author and publish). You can also configure other options.

To configure the portlet:

Content URLs content-urls

When content is requested from AEM, the portlet uses the current display mode (publish or author) and the current path to assemble a complete URL. With the default values, the first url is https://localhost:4503/content/geometrixx/en.portlet.html. The value of the htmlSelector is automatically added to the URL before the extension.

If the portlet switches to the help mode and the appendHelpViewModeAsSelector is selected, then the help selector is appended as well, for example, https://localhost:4503/content/geometrixx/en.portlet.html.help. If the portlet window is maximized and the appendMaxWindowStateAsSelector is selected, then the selector is appended as well, for example, https://localhost:4503/content/geometrixx/en.portlet.max.help.

The selectors can be evaluated in AEM and a different template can be used for different selectors.

Using a Content Url Map in AEM using-a-content-url-map-in-aem

Usually the start path points directly to the content in AEM. However if you want to maintain start paths in AEM rather than in the portlet preferences, you can point the start path to a content map in AEM, like /var/portlets. In this case, a script running in AEM can use the submitted information from the portlet to decide which url is the start URL. It should issue a redirect to the correct URL.

Adding the Portlet to the Portal Page adding-the-portlet-to-the-portal-page

To add the portlet to the portal page:

Using the Portlet using-the-portlet

To access the page you added to the portlet: