70 WEM Framework: Understanding the Framework and Services
The application developer's environment consists of the WEM Framework running on WebCenter Sites via REST services. Applications can be written in any language to make REST calls to WebCenter Sites. Custom-built applications can be deployed to an application server other than the platform's, and therefore written independently of the platform's deployment infrastructure.
This chapter contains the following sections:
70.1 Support for Application Development
Support for application development is in the following components (which are also described in their own sections in this chapter):
-
REST services, a set of programmatic interfaces that provide access to the WebCenter Sites objects.
-
UI container, which exposes registered applications. Registration enables rendering of the applications' interfaces. The UI container also supports the WEM Context object, used by applications to get details from the WEM Framework about the logged-in user and current site.
-
Single Sign-On (SSO), which enables authenticated users to log in only once to access all applications allowed to them during the session. (The WebCenter Sites installation process installs the Central Authentication Service web application to support single sign-on in WEM.)
-
REST authorization model, which provides fine-grained access control over REST resources, based on group membership. Application development does not directly involve authorization (which is configured graphically in WEM Admin and the WebCenter Sites Admin interface), except when a predefined user is specified in the code.
WEM Admin is also part of the WEM Framework, but seldom used in application development, mainly to test the results of the application registration process, or to obtain administrative information about sites, users, groups, and roles. Information about WEM Admin and the Web Experience Management Framework, is available in the Oracle Fusion Middleware WebCenter Sites Administrator's Guide.
70.2 REST Services
The REST API exposes the WebCenter Sites data model:
-
Basic asset types and basic assets (read-write)
-
Flex asset types and definitions (read only)
-
Flex children and parents (read-write)
-
Indexing to support asset searches
The following objects are also exposed by the REST API. They are used mainly by administrators in the authorization process (the objects are displayed in the WEM Admin interface):
-
Sites (read-write)
-
Users (read-write)
-
Roles (read-write)
-
ACLs (read only)
-
Groups (read only), introduced in this release to control access to the REST layer.
-
Auxiliary services: user locale and server time zone
(Sites, roles, and users can be configured in WEM Admin. ACLs and groups are exposed in WEM Admin (under Users) as read-only items; they must be configured in the WebCenter Sites Admin interface.)
Objects in WebCenter Sites map to REST resources in WEM. All other features, such as publishing, workflow, database management tools, and page caching must be accessed from the WebCenter Sites Admin interface or via JSP and XML tags.
Among the authorization objects that general administrators manage, sites and roles are the most likely candidates for application development, depending on your requirements. You can also specify "predefined" users to simplify administrators' authorization tasks.
-
Sites: Using sites in application code is a requirement when the application's asset types and assets must be programmatically installed. The code must specify at least one site on which to enable the asset types (site-specific access to assets requires their asset types to be enabled on at least one site). Otherwise, you can install just the asset types (without naming any sites). Administrators will follow up by using the WebCenter Sites Admin interface to enable the asset types and assets on sites of their own choice.
-
Roles: in WEM are used to manage access to applications. Sharing a role to a user and an application on the same site grants the user access to the application on that site. Roles can be used in application code to protect interface functions, such as
Edit. The WebCenter Sites Admin interface exemplifies an application with role-protected interface functions. -
Users: The only user you are likely to specify in your application code is the "predefined" user, to simplify administrators' authorization processes. Specifying the user involves coding a user name and password. Instead of authorizing all application users individually at the REST level, an administrator will authorize your predefined user. Permissions granted to the predefined user will be passed to the logged-in users when they access the application. More information about predefined users and the authorization model can be found in Section 70.5, "Authorization Model."
Keeping track of how sites and roles are used across the system is an administrators task that requires support from application developers. Tracking becomes especially important when the WebCenter Sites platform also functions as a staging system, only because the WEM Framework uses the WebCenter Sites database. For example, sites created in WEM Admin are stored in the database. They might not be used in WebCenter Sites for staging, but they are exposed in the WebCenter Sites Admin interface, along with its dedicated CM sites. Conversely, sites that are created in the WebCenter Sites Admin interface for CM purposes are exposed in WEM Admin, where other applications can be assigned to those sites. For users to be properly authorized, developers must communicate to administrators the nature of the custom-built applications: the resources they use, role-protected interface functions, and predefined users, if any.
70.3 UI Container
The UI container exposes registered applications and supports the Context object, used by applications to get information from the WEM Framework.
This section contains the following topics:
70.3.1 Registration
The purpose of registering an application is to expose the application in WEM Admin for administrators to manage and make available to other users. Registration allows the system to recognize the application as an asset, which in turn allows the system to
-
list the application on the Apps page in WEM Admin (Figure 70-1),
-
locate the icon you have chosen to represent the application,
-
display the application's icon on the WebCenter Sites login page, and in the applications bar on each site to which the application is assigned (Figure 70-1), and
-
render the application's interface when the application's icon is selected.
Figure 70-1 Registered Applications in UI Container
Description of "Figure 70-1 Registered Applications in UI Container"
Registering an application includes registering its views. While multiple and shared views are supported, applications with a single, unshared view are typical (and used in this guide). Views can be of type iframe, HTML, and JavaScript.
To support registration, the WEM Framework ships with the basic asset types FW_Application and FW_View. Both are created when the WEM option is selected during the WebCenter Sites installation process. They are enabled by default on AdminSite (also created during the WebCenter Sites installation process).
Registering an application (once it is deployed) requires creating an instance of FW_Application, creating an instance of FW_View for each view, and associating the FW_View instances with the FW_Application instance. Applications must be registered on AdminSite, even if they will be used on other sites. Registration allows applications to be assigned to other sites.
Applications can be registered either programmatically via the REST API's applications service, or manually from the WebCenter Sites Admin interface. Programmatic registration is preferred. For an example, see Section 71.2, "Launching the Articles Sample Application." For general instructions, see Section 72.6, "Registration Code." An example of manual registration is available in Chapter 78, "WEM Framework: Registering Applications Manually."
70.3.2 WEM Context Object
The UI container provides a JavaScript Context object (WemContext) to all applications inside the container. The Context object is used by the applications to get details from the WEM Framework about the logged-in user and site (for example, the current site's name from the UI container). The Context object also provides various utility methods that applications will use to share data. The Context Object can be used by applications running in the same domain as WebCenter Sites or in different domains. For more information, see Section 72.5, "Context Object: Accessing Parameters from the WEM Framework."
70.4 Single Sign-On
Single sign-on is implemented using Central Authentication Service (http://www.jasig.org/cas). As shown in the sample "Articles" example, the servlet filter that ships with the WEM Framework are ready-to-use for any application that is deployed as a Java web application. If your application is developed using a different technology, refer to CAS clients specific to your choice of technology, at the following URL:
http://www.ja-sig.org/wiki/display/CASC/Official+Clients
When a user tries to access an application protected by CAS, the authentication system responds with the steps below.
-
Initial Access
-
When the user first attempts to access an application protected by CAS,
-
the user is redirected to the CAS login page. Upon successful login,
-
the user is redirected back to the application with a ticket. The cookie for the CAS login page is saved.
-
The application verifies the user's identity by verifying the ticket against CAS. (On content management systems, CAS authenticates by default against the WebCenter Sites database.)
Description of the illustration initialaccess.gif
-
-
Subsequent Access
-
When the user attempts to access another application protected by CAS, the user is redirected to the CAS login page.
-
The cookie is retrieved from the request, implicit login is performed, and the login page is bypassed.
-
The user is redirected back to the application with a ticket.
-
The application verifies the user's identity by verifying the ticket against CAS.
-
70.5 Authorization Model
Authorization is the process of granting users access to applications. General administrators are responsible for authorization by using WEM Admin to couple objects as shown in Figure 70-2. Developers can simplify the administrator's task by coding a predefined user in their applications. How the user fits into the authorization model is explained below.
In Figure 70-2, Site, Application, User, and Role each have a counterpart menu option in WEM Admin. ACLs and groups are exposed on each user's page.
Description of the illustration adminsitespage.gif
Authorization is managed at three levels: application, REST, and database.
-
Application-level authorization requires sharing a role to a user and an application on the same site, which grants the user access to the application on that site. If interface functions are role-protected, their roles as well must be shared to the application users.
-
REST-level authorization regulates the user's permission to operate on the application's resources, assuming ACLs are correctly assigned. REST-level authorization requires configuring groups with privileges to operate on objects that map to REST resources. Users who are assigned to a group gain the group's privileges.
Developers can define a user in their applications (by user name and password) to act as a proxy for logged-in users, which eliminates the need for administrators to configure REST security for each logged-in user. Once an application is deployed and registered, a general administrator authorizes its predefined user by: 1) configuring the predefined user in WEM Admin for application access, 2) configuring a group (in the WebCenter Sites Admin interface) with privileges to operate on the applications' resources, and 3) assigning the predefined user to the group (by using either the WEM Admin or the WebCenter Sites Admin interface). The group's privileges are passed to the predefined user and then to logged-in users when they access the application. Supported security configurations are described and listed in Section 75.3, "REST Authorization." The "Articles" sample application provided with the WEM Framework specifies a predefined user.
-
At the database level, ACLs determine the individual user's access to the system, i.e., permission to log in and operate on the database, regardless of the user's membership in any groups. If a user lacks the appropriate ACLs and therefore permissions to the database tables, then membership in a group does not grant those permissions.
Default ACLs give users almost unrestricted permissions, but not the means, to operate on objects in many of the database tables. Those permissions are modulated at the REST level: Either directly by the user's membership in groups (in the absence of a predefined user), or indirectly by the application's predefined user and his membership in groups. Modifying a group's privileges to operate on objects modifies the group member's privileges to operate on resources. The same user on the WebCenter Sites side remains unaffected by group memberships. Permissions to content are still regulated by ACLs and actuated by sites and roles.
70.6 Custom Applications
Custom applications developed in WEM are often implemented in a loosely coupled manner to the content management platform. Because custom applications utilize the REST API Web services and SSO mechanism enabled by the WEM Framework, they are often deployed to an application server other than the platform's application server. Developers can therefore write custom applications completely independently of the platform's deployment infrastructure. Most custom applications are deployed remotely (Figure 70-3).
Figure 70-3 Remote Application Deployment
Description of "Figure 70-3 Remote Application Deployment "
Custom applications can be implemented as content management or delivery applications. We recommend getting started with the content management side, as it typically does not require much performance tuning effort.
The WEM Framework ships with several lightweight sample applications, which you can launch and analyze as models for developing your own applications. "Articles" illustrates a content management application. Chapter 71, "WEM Framework: The Articles Sample Application" contains instructions for launching "Articles." Specifications can be found in Chapter 72, "WEM Framework: Developing Applications," source code is provided in the WebCenter Sites Misc/Samples folder, and other supporting information is provided in the REST API resource and Bean references. The SSO sample application is for authentication on live sites and the "Recommendations" application illustrates the creation of REST resources.
70.7 Requirements for REST Resources
To authenticate all REST POST/PUT/DELETE requests as valid, each request requires a header with the X-CSRF-Token as the key and a value of either a CAS ticket (multi or single) or a sessionid.