67.1 Introduction to WebCenter Portal Application Security

WebCenter Portal applications are dynamic and often involve input from users in the form of customizations and preferences, and consequently require a flexible security model. The WebCenter security model is based on the ADF security model rather than the more traditional J2EE security model. For more information on ADF security, the section on "Enabling ADF Security in a Fusion Web Application" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

By default, a WebCenter Portal application is configured with ADF security. A default username and password (weblogic/weblogic1) are created automatically for you, and you can use this username/password combination for testing purposes immediately. For more information about configuring ADF security, see Section 67.3, "Configuring ADF Security."

Default login and logout pages are also provided with the WebCenter Portal Application template.

WebCenter Portal applications can also use two out-of-the-box security tools: the Role Manager task flow, and Page Hierarchy security editor. The Role Manager task flow provides pre-defined runtime security administration functionality to define roles and permissions for users. Using the Page Hierarchy security editor provides a quick way to apply inherited and/or delegated security to application pages. These two security tools are described in Section 67.4, "Using the Role Manager Task Flow," and Section 67.6, "Using the Page Hierarchy Security Editor."

67.2Creating an Application Role

There are three roles available out-of-the box:

Administrator - the default member for the application Administrator role is the enterprise Administrator role, whose default member is weblogic

AppConnectionManager - the default member for the AppConnectionManager role is the application Administrator role

AppConnectionViewer - the default member for the AppConnectionViewer role is the authenticated-role

The Administrator role is provided so that you can set up navigation and security for your application, and delegate permissions to other users.

The AppConnectionManager and AppConnectionViewer are roles that are defined for managing and viewing application connections respectively. Typically, application connections are configured and managed using Fusion Middleware Control or WLST commands. However, connections for portlet producers and external applications can be configured through the application's runtime Administration page (or the Role Manager taskflow if implemented separately). To manage or view these connections, you must be part of one of these roles. For more information about the default roles, see "Default Application Roles" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

You can add members at runtime for these roles using the Administrator page (or the Role Manager taskflow if implemented separately), and in JDeveloper using the JAZN Editor. Out-of-the-box, an administrator will be able to configure external application and portlet producer connections, and any other authenticated user will only be able to view these connections. Similarly, you can add users to the application by selecting the Users tab in the ADF Security Policy editor, clicking the Add (+) icon, and specifying a username and password.

To create an application role:

Access the ADF Security Policy editor using any of the following methods:

Navigate to the jazn-data.xml file in the Application Resources Panel, under the META-INF folder. Right-click jazn-data.xml and select Open from the context menu. Open the Application Roles tab.

Right-click the application name, select Secure and then Application Roles.

From the Application menu, select Secure and then Application Roles.

In the Application Roles editor, click the Add (+) icon and select New Role.

Enter a name, a display name, and description for the new role.

Save the file.

Similarly, you can add users to the application by opening the Users tab in the ADF Security Policy editor, clicking the Add (+) icon, and specifying a username and password.

67.3 Configuring ADF Security

ADF security is configured by default if you created your application using the WebCenter Portal Application template. This section describes the Configure ADF security wizard, which you can use to override the default settings for a WebCenter Portal application, or if your application does not use the WebCenter Portal application template (i.e., you did not select the "Configure the application with standard portal features" checkbox when you created your application). This section also describes the grants that are generated when you create a WebCenter Portal application, and when services are consumed.

67.3.1 Configuring ADF Security Settings

This section describes the Configure ADF security wizard, which you can use to override the default settings for a WebCenter Portal application, or if your application does not use the WebCenter Portal application template (i.e., you did not select the "Configure the application with standard portal features" checkbox when you created your application).

To configure the ADF security settings:

Open your portal application.

Access the Configure ADF Security Wizard using one of the following methods:

From the Application menu, select Secure and then Configure ADF Security.

To make the process of securing your application easy, select Form-Based Authentication and then the Generate Default Pages option, as shown in Figure 67-2.

Note:

WebCenter Portal applications provide default login and error pages. You should only select the Generate Default Pages option for applications not built using the WebCenter Portal application template.

On the Enable automatic policy grants page, shown in Figure 67-3, select whether to make ADF resources public without requiring application developers to first define ADF policy grants. For a standard security implementation, you can select the No Automatic Grant option.

However, in this case, you must individually grant permissions on each page in the application.

When you enable automatic policy grants, a View grant for all ADF resources is made to the test-all application role, whose default member is the public role. This option provides a convenient way to run and test application resources without the restricted access that ADF authorization enforces. You can also disable automatic policy grants to secure all ADF resources by default.

Select No Automatic Grant when you want to explicitly configure a policy store to grant access to ADF resources. No automatic grants to the test-all application role are granted. However when WebCenter services task flows are consumed in an application, the WebCenter extension automatically adds appropriate grants for these task flows, giving View access to the role authenticated-role. For more information about the specific grants provided through task flows, see Section 67.3.2, "Automated Security Grants for WebCenter Services."

Note:

Grants made to the role authenticated-role are visible in the source view of the jazn-data.xml file. If the default grant to authenticated-role is not appropriate to the application, you can change it by manually updating the source view of the application's jazn-data.xml.

Select Grant to Existing Objects Only when you want JDeveloper to grant View privileges to the test-all (public) application role and you want this policy to apply to all your application's existing ADF task flows and web pages in the user interface project.

Select Grant to All Objects when you want JDeveloper to grant View privileges to the test-all application role and you want this policy to apply to all ADF task flows and web pages that developers create in the user interface project. Note that the Grant to All Objects option appears when you run the wizard for the first time. Subsequently, the Grant to New Objects option appears each time you run the wizard.

Click Next.

Optionally, if you want to display a specific welcome page upon authentication, then select the Redirect Upon Successful Authentication option as shown in Figure 67-4.

You can either create a custom welcome page or let the wizard create a default one. To keep the process simple, select Generate Default.

Table 67-2 lists the grants that are given when a service is consumed. A service is consumed whenever a component (from the Component Palette) or a task flow (from the Resource Palette) belonging to that service is added to a page.

If ADF security has not been configured for the application, then these grants are not added; however, if security is later configured, grants are added for all services that have been consumed in the application. Common grants are granted whenever any Oracle WebCenter service is consumed.

67.4 Using the Role Manager Task Flow

The Role Manager task flow lets administrators manage application roles, its memberships, and associate service permissions for the role. The Role Manager task flow is available out-of-the-box from the runtime Administration page's Security tab for applications built using the WebCenter Portal application template. For information on how to use the Role Manager runtime to manage and configure users and application roles, see "Managing Users and Application Roles" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

To prevent customizations from being overwritten during updates, the source for the Administration page should not be customized. You can, however, choose to write your own administration page if the default administration page is not sufficient, in which case you can use the Role Manager task flow as part of your application's runtime security administration. Follow the steps below to add it a JSF or JSP page and include it in your application.

To add the Role Manager task flow to your WebCenter Portal application:

Create a new application choosing WebCenter Portal Application as the application type.

Create the application adding any project technology libraries that the application may require. Do not uncheck the Configure the application with standard Portal features check box.

Create a new JSF or JSP page.

From the Resource Palette, expand WebCenter Services Catalog, and from the list of Task Flows, select the Security - Role Manager task flow.

Build the application, log in as an administrator, and navigate to the page containing the role Manager task flow.

67.5 Using the Enterprise Role Member Task Flows

The Enterprise Role Member task flows provide additional task flows to the Role Manager task flow that you can add to a page to monitor enterprise users and roles. The members shown are both roles and users, with the result shown in a tree structure. Roles can be further expanded to see their members.

To add the task flows, follow the same steps as for the Role Manager task flow (see Section 67.4, "Using the Role Manager Task Flow"), substituting one of the task flows described below. Note that all of the Enterprise Role Members task flows take a single mandatory parameter which is the enterprise role name.

Security - Enterprise Role Members

This task flow shows a list of the members for a specified role.

Security - Enterprise Role - Members Search

This task flow does a nested search of members using a pattern for the specified role and shows the list of members.

Security - Enterprise Role - Members Viewer

This task flow shows the Members and Search tabs that are shown for the Enterprise Role Members and Members Search task flows in a single page.

67.6Using the Page Hierarchy Security Editor

This section describes how to use page hierarchy security to provide inherited and delegated security for WebCenter Portal application pages. It includes the following sections:

67.6.1.1 Page Hierarchy Model

A page hierarchy has a default security policy that is set at the root of the hierarchy. Unless explicitly overridden, this policy applies to all pages underneath. At any page in the hierarchy, it is possible to override the inherited policy with a new overriding policy, allowing for delegated administration and modifying the policy at the subordinate pages. Once the policy is overridden for a particular page, the children of that page, by default, will inherit the new policy. The policy established at any node is a list of grants indicating what permissions each of the grantees has on that page and its children, if any.

When you create a WebCenter Portal Application, a default navigation model is created for you that also contains the root node of a page hierarchy. These two structures work independently and collectively to provide the navigation flow and secured access to pages for your application. Figure 67-8 shows the default navigation model (default-navigation-model.xml), which includes a node for the default page hierarchy (pages.xml).

Although there is only a single page hierarchy within your application, any node within that hierarchy can be used as the root node in a navigation model. For example, you might have a page hierarchy that contains top level nodes for Human Resources, Support, Sales, Administration, and so forth. Each of these nodes can be added to the navigation model separately to create navigation only to that section of the page hierarchy.

Figure 67-9 shows the page hierarchy root node and the associated permissions. From the root node you can start building your page hierarchy by adding or dragging pages into it. Note that the "Manage" permission appears only on the root node, and only for the administrator. This allows the administrator to delegate security and have full access to all pages within the hierarchy regardless of any security overrides downstream. In short, a user with "manage" permission on the root node is a super admin and has all access to all pages in the entire hierarchy.

67.6.1.2 Page-level and Page Hierarchy Security

A page hierarchy provides an alternative security mechanism to page-level security for your WebCenter Portal application. Although you can add pages to your application and provide security for them without making them a part of a page hierarchy, a page hierarchy provides a convenient and more manageable way to secure the content for large sites. By simply adding a hierarchy node to the hierarchy root or home node and dragging and dropping pages into it, you can very quickly provide basic security for them.

Note:

Although page-level security can co-exist with page hierarchy security, you cannot apply both page-level and page hierarchy security to the same page. Note also that if you add a page to a hierarchy node, all previous page-level permissions are purged.

67.6.1.3 Inherited and Delegated Security

The page hierarchy model uses a node structure that provides cascaded, role-based security where each child node inherits its parent's security permissions. By adding pages to a node you can quickly configure security for your application pages.

To be able to perform any action at a particular node, you need to have the required permission at the node or its immediate parent that delegates (overrides) security. However in order to view a page, you need to have view access for all pages up the hierarchy right till the root page.

As well as providing basic security inherited from a node's parent, you can also apply delegated security to child nodes to limit or override the security that would otherwise have been inherited. These aspects of page hierarchy security are described in Section 67.6.2, "Building a Page Hierarchy."

Note:

Inherited security is cascaded through a root node that can initially only be populated by an administrator. For other users to be able to create and delegate permissions the administrator must first delegate those permissions. In all cases, permissions are only cascaded down in the tree (that is, a user cannot change settings for a parent node). A user can also only delegate the rights they have themselves or a subset of those rights to another user.

67.6.2 Building a Page Hierarchy

This section explains how to use page hierarchy security to automatically cascade a parent page's role-based security settings to its child pages, and how to "delegate" security for individual page nodes.

Check or uncheck the Visible checkbox to specify whether the page or resource is displayed. Check the checkbox if you want the resource to be displayed to all users at all times. Uncheck the checkbox to hide the resource from all users at all times.

Check or uncheck permissions for the roles for this page and its child pages.

To specify permissions for another available user role, click the Add icon (+) and select the desired role. A new row will be created in the table for this role. To remove the permissions for an existing role, select the corresponding row in the table and click the Delete (X) icon.

Note:

The role names in the Add list correspond to the application roles that have been defined in the policy store for the application. Delegating security is limited to only application roles at design time. You can, however, add user and enterprise roles at runtime using the runtime Administration page, as described in "Managing Application Roles and Permissions" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

67.7Creating Login Pages and a Login Component

You can add login and logout links to your public welcome page or other page using a login backing bean (LoginBackingBean) so that users can explicitly log in and out while they are in the application. The bean provides methods that can be used by the user to log in and log out.

To use the bean, create a simple page and bind it to the bean to do the login and logout as described in the following steps:

Create a JSF page.

Add the LoginBackingBean to the faces-config.xml or taskflow.xml file.

Create a page with user name, password, login and logout links.

Bind the user name and password to the bean's user name and password.

Map the login and logout links to the doLogin and doLogout method respectively as shown in the example below:

Drag a PanelCustomizable onto the h:form tag that is inside the first cust:panelCustomizable tag you added to the login page.

From the Component Palette, select RichTextPortlet Producer, then select the Rich Text portlet from the list and drag it onto the PanelCustomizable component.

From the Component Palette, select ADF Faces Core and drag an ObjectSeparator below the Rich Text portlet on the PanelCustomizable component.

From the Component Palette, select OmniPortlet Producer, then select the OmniPortlet from the list and drag it onto the PanelCustomizable component.

Save the page.

Because the login page is called from the container as part of the login process, the request must be forwarded to the ADF binding filter to establish the appropriate portlet and security context. To do this, you must configure a mapping for the ADF Binding filter in the web.xml file. To do this, perform the following steps:

In the Applications Navigator, expand the WEB-INF node, right-click web.xml and select properties to open the property palette.

Select Filter Mappings in the left panel and click add to define a new mapping for the adfBindings Filter. This displays the Create Web Application Filter Mapping dialog box.

Specify adfBindings for the filter name and click the Servlet Name option and specify Faces Servlet as the servlet name. Ensure that the Forward and Include dispatcher types are selected as shown in Figure 67-11.

67.10Creating a Self-Registration Page

You can create a self-registration page using the WebCenter Spaces self-registration task flow, or build a custom self-registration page based on a provided sample that shows how to use the user and role APIs provided in CreateUserHelper. This type of self-registration provides a way for public users to create their own login and password for your application.

From the Resource Palette, expand the task flows and drag and drop the self-registration task flow onto the page.

Create a mail connection and an external application with public credentials and connect the external application to the mail connection. Make this the mail default connection.

Run the page with the self-registration task flow to see the runtime self-registration page.

67.10.2Building a Custom Self-Registration Page

The example self-registration page described below provides a simple page that accepts the user's firstname, lastname, mailid, login name and password. Use the sample files as a starting point for use within your local environment, or build your own self-registration page and logic using the user and role APIs provided in CreateUserHelper. You can use the property set of the user profile attributes provided in the sample and add more attributes to the user as required.

To create the sample self-registration page:

Unzip the security samples files in security-samples.zip found in the webcenter/customportal directory in the WebCenter extension bundle.

Copy the CreateUserBean.java and CreateUserHelper.java files into the application sources folder for your WebCenter Portal application.

Copy the TestCreateUserPage.jspx file into the public-html folder.

Edit the TestCreateUserPage.jspx file to suit the local environment and local requirements.

Run the TestCreateUserPage.jspx page to view the self-registration page.

Run the page with the self-registration task flow to see the runtime self-registration invitation page.

67.11Creating a Reset Password Page

The following example provides a simple reset password page that accepts a username and new password. Use the sample files as a starting point for use within your local environment, or build your own reset password page and logic using the user and role APIs provided in ResetPasswordHelper to change the password.

To create the sample reset password page:

Unzip the security samples files in security-samples.zip found in the webcenter/customportal directory in the WebCenter extension bundle.

Copy the ResetPasswordBean.java and ResetPasswordHelper.java files into the application sources folder for your WebCenter Portal application.

Copy the TestResetPasswordPage.jspx file into the public-html folder.

Edit the TestResetPasswordPage.jspx file to suit the local environment and local requirements.

Run the TestResetPasswordPage.jspx page to view the reset password page.

Portlet personalizations are tied to particular, authenticated users. Hence, when running a portlet that has an Edit mode, the Personalize option in the portlet's dropdown menu only appears to authenticated users of the application. Anonymous or public users will not have the option to personalize the portlet. If you are a developer creating portlets and pages, then you may want to quickly test the Edit mode of your portlet without creating a complete security model for your application. To perform this sort of testing, you can easily configure some very basic authentication for your application and then remove it when you have finished testing:

Note:

This procedure is useful for any portlet that has an Edit mode (Omniportlet, Web Clipping, JPS, and PDK-Java).

Run the page in the integrated WLS and log in as a valid user and test your portlet's edit mode.

When you are done testing your portlet's Edit mode, you can quickly remove this test security by do the following:

In the Applications Navigator, click the project that contains a page with the portlet you want to test.

From the Tools menu, choose ADF Security Wizard.

If the Welcome page appears, then click Next.

Choose Remove All ADF Security Settings.

Click Next until you come to the Finish page of the wizard. Click Finish. The security is removed. If you want to ensure that the security has been removed, then exit your browser and rerun the application. When you access the page, you are not prompted to login and the personalize option no longer available from the portlet's dropdown menu.

67.13 Working with External Applications

Oracle WebCenter Framework defines an external application as any application that implements its own authentication process. That is, an application that does not take part in the WebCenter Framework application's single sign-on process. In some cases, the identity management solution may be the same, but the authentication process can be different.

When WebCenter Framework Service interacts with an application that handles its own authentication, you can associate that service with an external application to allow for credential provisioning. Therefore, the use of an external application definition provides a means of accessing content from these independently authenticated applications.

To replicate a single sign-on experience from the end user's perspective, the external application service captures the username and password, and any other credentials for the external application, and supplies it to the WebCenter service requiring it. The WebCenter service then uses this and logs in on behalf of the end user. This username and password combination is securely stored in a credential store configured for the WebLogic domain where the application is deployed.

The user provides login credentials when prompted, and these credentials are mapped to the WebCenter application user and stored in the credential store configured for the domain. The credential store subsequently supplies that information during authentication to the external application. Unless the external application's credentials change, the user supplies the credentials only once as the mapped information is read from the credential store for future requests.

Note:

When logging in to an external application, if you clear the Remember My Login Information checkbox, then the credentials provisioned for that user session are lost if there is a failover in a high availability (HA) environment. You are prompted to specify the credentials again if you try to access the external application content in the same user session.

The external applications that are to be used by the WebCenter Portal application can be specified before deployment through a wizard in Oracle JDeveloper, or post-deployment through the application server management interfaces (WebLogic Scripting Tool and Oracle Enterprise Manager). See Oracle Application Server Administrator's Guide for more information.

67.13.1 Using External Applications

The WebCenter External Application Service provides a way for mapped user identities to be passed to a web application that requires its own authentication. The support for external applications and credential mapping provided by the WebCenter External Application Service can be used to set up a secured service connection and to provide a seamless automated single sign-on experience for the user.

67.13.1.1 Secured Service Connections

To use an external application definition with a secured service (such as a mail server or portlet producer) you associate the named external application with the connection configuration to the required service. For example, the connection to a mail server requires the user to supply a valid username and password to see their mail. Therefore, by associating an external application to the IMAP server connection definition, the user's credentials are automatically passed as part of the mail request as shown in Figure 67-12.

Note:

The following WebCenter Services must be configured with external applications for credential mapping support to be available:

When a portlet producer depends on an application that handles its own authentication, you can associate the producer with an external application so that when you register the producer it is a simple task to select the appropriate external definition that maps to the application that is exposed within the portlet, as shown in Figure 67-13.

At run time, the producer uses the information associated with the external application to authenticate the user to the application, and consequently consume its portlets. The producer code is responsible for actually performing the authentication interaction with the external application. The external application support provided with WebCenter Framework simply provides the information needed for authentication to the portlet producer. The use of external applications is supported for both Oracle PDK-Java as well as WSRP producers.

For example, a producer provides a stock portfolio portlet from a portlet-producing application that has its own authentication mechanism. In this case the developer:

Defines the external application. This can be done through the Oracle JDeveloper wizard or through Oracle Enterprise Manager.

Associates the external application with the portlet producer.

67.13.1.2 Automated Single Sign-On

With automated single sign-on, the user directly links to the application and is automatically authenticated to the secured web application, as their credentials are retrieved from the credential store. This provides the end user with a seamless single sign-on experience.

Note:

Automated login is not supported for:

External applications using BASIC authentication.

External applications configured for SSO.

External applications with a customized login form (built using ADF Faces) that does not implement the J2EE security container login method j_security_check for authentication.

External sites that do not support UTF8 encoding

Rather than using a URL directly to the web application, links to the application are proxied through the external application's automated login servlet (adfextapplogin). If the user is not authenticated to the external application and they have not previously stored their credentials in the credential store, they will be challenged for their password through the credential provisioning page discussed below. If, however, the user has previously defined credentials, they will be returned from the credential store and the user will automatically be logged on to the application.

The proxy URL references the external application in question and redirects to the URL that is specified in the external application definition.

/adfextapplogin?extappid=<extappid>

For example, if you had a WebCenter Portal application in which you defined an external application that represented the myoracle.com Web site (external application identifier is "myoracle"), the proxy URL would look like this:

/adfextapplogin?extappid=myoracle

The link's target attribute should also be set appropriately. For example, if you use <a href=>, then set the target attribute appropriately in addition to specifying the target in the href. The target attribute specified for the servlet will determine how the Cancel button functions as described below.

/adfextapplogin?extappid=<extappid> [target= _self | _blank]

If you specify target=_blank the link opens in new window. If you specify target=_self the link opens in current window. If the target parameter is not specified the link opens in current window.

This parameter also affects how the Cancel button on the credential provisioning page works. If _blank is specified, the new window is closed when Cancel is clicked; if _self is specified (or the target parameter is not used), the user is returned to the calling page.

Note:

Automated login for external sites is not supported for sites that do not support UTF8 encoding.

67.13.2 Supplying User Credentials

How you allow an end user to define their credentials for an external application depends on the use of the external application. For most services, the credential provisioning screen is incorporated into the task flow that the service exposes and for these no further configuration steps are required. You can, however, add the External Application - Change Password task flow component to applications using these services thereby allowing the end user to preemptively set the appropriate user name and password for each of the external applications that is registered with your WebCenter Portal application.

The External Application - Change Password task flow displays all external applications defined in the application that do not specify shared credentials (for more information about shared credentials, see Section 67.13.3, "Managing External Applications"). Note that the user must to be authenticated to view this task flow.

For the Instant Messaging and Presence service, however, you must explicitly add the External Application - Change Password task flow component to your application from the Resource Palette or Component Palette. For step-by-step instructions on how to configure security for the Instant Messaging and Presence service using the External Application - Change Password task flow component, see Section 34.2.2, "Adding the IMP Service at Design Time".

At run time, the credential provisioning screen displays login data fields composed of the data fields specified through external application registration. Users fill in the data fields with their login information for the specified external application and that login information is passed to the external application or service. Entering the credentials in the provisioning screen also results in the credentials being persisted in the credential store configured for the WebLogic domain.

By default, the login information the user entered is preserved in a credential store, which handles logins for future sessions. The user does not have to enter login information again (unless the user's credentials change). However, the end user can choose to use the information for the current session by deselecting the Remember my Login Information checkbox on the credential provisioning page.

67.13.3 Managing External Applications

This section provides information about registering external applications. Additionally, it describes the process of editing and deleting registration details. It contains the following subsections:

67.13.3.1Adding External Application Task Flows

The External Application task flow enables users to manage external application connections at runtime. This task flow provides an interface for users to update their credentials for all external applications as and when these credentials are changed at the back end. That is, users do not need to update credentials through the runtime Administration Console's Services tab if they use this task flow.

The external application task flows that you can add using Oracle JDeveloper are:

In addition, just like other task flows, you can add external application task flows to your application pages. This may be especially useful if you are not using the WebCenter Portal application template and the Administration pages are therefore not part of your project.Special permissions are required to manage or view external application connections through these task flows:

AppConnectionManager - Users with this role can register, modify, and delete external application connections at runtime.

AppConnectionViewer - Users with this role can view external application connections at runtime. By default, any user who is logged in (that is, has the authenticated-role) is granted this role.

By default, users with the Administrator role can manage external applications. If you want other users to manage connection through these task flows you must grant them the AppConnectionManager role.

Drag External Application from the Resource Palette and drop it onto the page inside of the af:formbegin and end tags.

Drag External Application - Change Password from the Resource Palette and drop it onto the page inside of the af:formbegin and end tags after the External Application task flow (af:region - # {bingings.extapp1.regionModel}).

Grant the AppConnectionManager role to one or more test users, if required:

67.13.3.2.1Registering an External Application in Oracle JDeveloper

Use the Register External Application Wizard to identify and store information about the type of data required to authenticate to an external application, such as the names of login fields.

To register an external application in Oracle JDeveloper:

In the Applications Navigator, right-click a WebCenter Portal application or project and select New from the context menu.

In the New Gallery, select External Applications under the General node.

In the right pane, select External Application, and click OK.

This displays the Register External Application Wizard.

On the Name page, use the Create external application in option to specify whether the external application can be reused in other WebCenter applications. Select Application Resources to make the external application available only in the WebCenter application in which it is registered, or select Resource Palette to make the external application available from the Resource Palette to any new WebCenter applications you create in Oracle JDeveloper.

If you choose Resource Palette, then the external application connection will be visible under IDE connections in the Resource Palette. If you want to use it in an application, you can right click the external application from resource palette and click Add to Application.

In the Name field enter a unique name to identify the application.

This name must be unique within the WebCenter Portal application, and among other connections as well. Note that you cannot edit this field afterward.

In the Display Name field enter a name for the application that end users will see in the credential provisioning screens.

In the User Name/ID FieldName field, enter the label that the application uses for the user name field, for example, User Name.

In the Password FieldName field, enter the label that the application uses for the password field, for example Password.

From the Authentication Method list, select the application's login method.

Choose from the following:

GET

Presents a page request to a server. Submits the login credentials as part of the login URL.

POST

Submits login credentials within the body of a form.

Click Next.

On the Additional Fields page, enter the names and values of any additional fields that are submitted with the external application's login form:

Click the Add Field button to create an input field:

Field Name

Enter a unique name for any additional field that requires user input on the external application HTML login form.

Field Value

Enter a default value for the corresponding field name.

Display to User

Select to display the field on the external application login screen. If the field is not displayed (unchecked), then a default value must be specified, which will be used to login into the external application for all users. If the value is user-specific, then the field must be displayed to the user provisioning page.

Note:

The Delete Field option can be used to delete selected rows.

Click Next.

On the Shared Credentials page, select the Specify Shared Credentials check box and specify a Username and Password if you want all authenticated users to access the external application using this credential. Authenticated users will not be challenged to provide their credentials when they access the external application.

Click Next.

On the Public Credentials page, select the Specify Public Credentials check box and specify a Username and Password to be used for all unauthenticated (public) users accessing the external application. This is required when the external application content is accessed through one of the WebCenter Services (such as Document Library, or Instant Messaging and Presence), and the taskflow is placed on a public page.

Click Finish to register the external application.

After registering your external application, you must configure the application to allow the end user to define the username and password. You can do this by dropping an External Application - Change Password task flow component into your application. This allows the end user to preemptively set the appropriate username and password for each of the external applications that is registered with your WebCenter Portal application.

To configure the application to allow the end user to define the username and password, perform the following steps:

To delete external application registration information, perform the following steps:

In the Application Navigator, from the Application Resources pane under the Connections node, right-click an external application and select Delete from the context menu.

Alternatively, you can select an external application in the Applications Navigator and from the Edit menu, select Delete.

In the External Application Delete dialog box, select Yes.

Oracle recommends that you remove any references to services, such as a portlet producer, with which the external application is associated. Failing to do so will likely result in runtime errors, because the components will attempt to communicate with the external application.

67.14Registering Custom Certificates with the Keystore

Secure Sockets Layer (SSL) Communication requires the use of trusted certificates issued by a certificate authority, which vouches for the authenticity of the certificates that it issues or signs. Widely accepted certificate authorities are listed in the keystore, the cacerts file, available in the <JDEV_HOME>\jdk\jre\lib\security directory. If a portlet producer uses a security certificate issued by a non-widely accepted certificate authority and you try to access portlets from this producer, a security alert is displayed informing you that the security certificate was issued from a certificate authority you do not trust. This means the certificate is not available in the keystore. To avoid being prompted each time you access such portlets, you must register this certificate with the keystore.

To register a certificate with the keystore, perform the following steps:

Navigate to JDEV_HOME\jdk\jre\lib\security.

Back up the cacerts file.

Access the producer URL in Internet Explorer to get the certificate.

Note:

Recent versions of FireFox do not provide a means to export certificates.

Individual actions on portlets and customizable components are not secured by default. Rather, the ability to customize a portlet or customizable component as a whole is inherited from the page permissions. If you want to grant more granular activities within a portlet or customizable component, then you can override the page-level security inheritance and define security directly on the required actions.

The ability of a user to perform actions on portlets and customizable components is inherited from the page security based on the value of the application-wide switch, enableSecurity, in the adf-config.xml file. If you selected the WebCenter Portal application template while creating your application, then the adf-config.xml file is located in the <APPLICATION_NAME>/.adf/META-INF directory. The enableSecurity element is not available by default in adf-config.xml. To override or extend the page-level security inheritance for portlets and customizable components, you must add the portlets security and customizable components security sections in the adf-config.xml file, as shown in Example 67-1 and Example 67-2 and set the enableSecurity element in those sections to true.

Security for actions on portlets and customizable components can be implemented at the following levels:

Page level: You can define security for portlets and customizable components such that page-level privileges are inherited by these components. This is the default behavior.

By default, portlets and customizable components inherit allowable actions from the defined page-level permissions such as personalize or customize. That is, a user who has customize privileges on the page has permission on the customize action for the components on that page. The enableSecurity element enables you to override the security inheritance behavior and can take either of the following values:

true: If set to true (the default), then the ability for a user to modify a component will first be determined from the page permissions and then adjusted according to the current set of actions defined for that type of permission. If a user has customize permission, then the actions that constitute the customize category (move, customize, and so on) are available to the user, but they will be overridden by the actions that are defined in the adf-config.xml file. For example, a page designer wants to allow the end user to be able to customize portlets, but not customize the page layout. By setting enableSecurity to true, the page designer enforces that users must first have customize permission on the page. Setting customizeActionsCategory to false for customizable components will prevent the customization of the page layout, yet still allowing portlet customization. (As the default for customizeActionsCategory is true, it does not need to be set explicitly for portlets.).

false: If set to false, then all the actions are available to users. The user's page permissions and actions configured in adf-config.xml are ignored.

Actions category level: You can define security on all actions for portlets or customizable components that belong to a named category.

You can add an actionsCategory element in the adf-config.xml file to define security on multiple actions simultaneously. Depending on the actionCategory attributes that you enable, appropriate privileges are provided on the portlets or customizable components.

Actions level: You can define security on individual actions for portlets or customizable components.

You can use the actions element in the adf-config.xml file to enable or disable individual actions. Depending on the actions attributes that you enable, appropriate privileges are provided on the portlets or customizable components.

Notes:

Privileges can be inherited from the parent only. Inheritance from a component in any other position in the hierarchy is not supported

Although the security override implementation for portlets and customizable components is similar, they are independent from each other. Therefore, if you place a portlet inside a customizable component (for example, in a PanelCustomizable component), the portlet will not inherit override settings from the customizable component. Instead it will use the security override settings that are defined for portlets.

Settings made at the actions category level or actions level are applicable for all component instances in the application. These settings cannot be made for a single instance of a portlet or customizable component.

67.15.1 Portlets Security

You can define portlet security if actions on portlets are inherited from the page at the application level by setting enableSecurity to true in the portlets security section of the adf-config.xml file. A value of true implies that the user's permissions are determined from the page permission and then augmented according to the actionsCategory and actions elements specified. By defining actions categories and individual actions, you can control the exposure of the individual actions available within the given page permissions.

To implement security for actions on portlets at various levels as described earlier, you must define security settings at the following sections:

67.15.1.1 Defining Security at the Actions Category Level

You can add an actionsCategory element in the portlets security section in the adf-config.xml file to define the group of actions that are exposed on the portlets within the application. Depending on the actionsCategory attributes that you enable, appropriate privileges are provided on the portlets. Table 67-3 describes the different actionsCategory attributes and the portlet actions they support by default.

Table 67-3 actionsCategory Attributes and Portlets Actions Mapping

Attribute Value

Actions Supported

viewActionsCategory

Render

isHelpModeAvailable

isNormalModeAvailable

isAboutModeAvailable

isPreviewModeAvailable

isDetailModeAvailable

isLinkModeAvailable

isPrintModeAvailable

customizeActionsCategory

showMoveAction

showRemoveAction

isCustomizeModeAvailable

showMinimizeAction

showMaximizeAction

isConfigModeAvailable

personalizeActionsCategory

isPersonalizeModeAvailable

Example 67-3 shows the actionsCategory entry that you can add to the portlets security section in the adf-config.xml file. In this example, customizeActionsCategory is set to false to prevent customization. You can use Expression Language (EL) for the values of these elements.

67.15.1.2 Defining Security at the Actions Level

You can use the actions element in the portlets security section of the adf-config.xml file to enable or disable individual portlet actions. Depending on the action attributes that you enable, appropriate privileges are provided on the portlets.

Example 67-4 shows an example of an actions entry that you can add to the portlets security section in the adf-config.xml file. You can use EL for the values of these elements. In this case you prevent customization by setting isCustomizeModeAvailable to false.

Using EL to Prevent Customization of Portlets Outside of Business Hours

An example to show when you may need to override inherited portlet security is an application that is configured to disable portlet customization outside of standard business hours. For this, you must first create a managed bean (for example, a managed bean called appBusinessRules), containing the method shown in Example 67-5.

In this example, the customizeActionsCategory will be set to true only if the application is run within business hours. Outside of these hours, the portlet cannot be customized even if the user had that permission granted on the page. All other categories that are not explicitly defined, will be inherited from the page.

Using EL to Prevent Personalization and Customization of Portlets Outside the Corporate Network

In this example the managed bean checks the IP address of the request to determine whether the user has accessed the application through the corporate proxy server or from within the corporate network. In this simple example, assume that if the request has the proxy server's IP address, then it is coming from outside the corporate network. In general it is not advised to base security strictly on IP addresses, because these can be compromised. For this, you must add the method shown in Example 67-7 to the managed bean:

In this example, the customizeActionsCategory and the personalizeActionsCategory will be set to true only if the IP address of the request for the application does not match that of the corporate proxy. The assumption is that the internal requests would have a valid client IP address. All other categories that are not explicitly defined, will be inherited from the page.

67.16 Identity Propagation Mechanisms

The following table lists the identity propagation mechanisms employed by WebCenter Services for propagating the end-user's identity to the various information sources from which content is being integrated into the WebCenter application.

Whenever possible, WS-Security is the preferred means of identity propagation. Where WS-Security cannot be used due to legacy restrictions or pre-defined store-specific standards or specifications, the primary mechanism used is the credential mapping capability provided by the External Applications service to obtain the user's credentials for a remote application using a distinct security provider. For more information about WS-Security, see the Oracle Application Server Web Services Security Guide. For more information about External Applications, see Section 67.13, "Working with External Applications".

The Web Services for Remote Portlets (WSRP) specification indicates that Web Services Security (WS-Security) can be leveraged for providing secure identity propagation between the consumer and the portlet producer. However, WSRP in and of itself does not provide secure identity propagation of the end user's identity to the portlet producer. The WSRP specification explicitly defers to other security standards for secure identity propagation and does not go into the specific WS-Security profiles or options that may be employed. In the absence of a secure mechanism, WSRP defines the concept of user categories, which can be mapped to security roles like the ones used by the JSR168 portlets. By using a combination of WSRP and WS-Security, you can ensure end-to-end security.

67.17.1 Identity Propagation Without WS-Security

When using WSRP without WS-Security, the userContext structure within the SOAP message contains user profile information and user category information. This information is not considered secure and should only be used for personalization and customization functionality. It should not be used for authorization of sensitive resources. This information is also exposed in the JSR168 APIs, isUserInRole(role) and getUserPrincipal. The code in Example 67-9 shows how a sample portlet's markup rendering code uses the isUserInRole API to decide what content to display.

67.17.2 Identity Propagation with WS-Security

When WS-Security is leveraged with WSRP, the user's identity is propagated outside of the SOAP message body in the WS-Security header. This is a user assertion, using the Username Token format, and is digitally signed to authenticate the consumer and to ensure the integrity of the assertion.

When this mechanism is used, the JSR 168 APIs isUserInRole and getUserPrincipal are established based on the security context resulting from the WS-Security authentication, rather than the information in the SOAP message's userContext.

The use of WS-Security adds some complexity to the configuration and management of the WebCenter Portal application and the set of producers it consumes. However, when the situation warrants its use, it becomes an important ingredient of the SOA architecture that ensures the security of the information being published by the WebCenter Portal application.

When a portlet producer is generating sensitive information, for example paystub information, it is imperative that it only responds to requests to show the information from a legitimate consumer.

By using WS-Security, and having the consumer digitally sign the security token and the message body, the producer can verify the signature using the public key of the legitimate consumer. If the signature cannot be verified, then it means that the request may have come from a fraudulent consumer. By requiring the verification of the digital signature, the sensitive information will only be sent to the legitimate consumer.

Assertion and Message Integrity

In addition to verifying the identity of the consumer making the Web Service requests, digitally signing the security token and the message body also ensures that the token and the message have not been tampered with. This prevents such problems as man-in-the-middle attacks where a legitimate request might be intercepted and the user name in the security token replaced with another user name to see the paystub information coming back for the other user. By digitally signing the token, it cannot be tampered with. Any modification to the token would result in the inability to verify the signature on the producer end, and would result in a SOAP fault to be returned instead of the requested paystub information.

Supported Producers

WS-Security implementation is supported by the Oracle WebCenter Suite WSRP container. Other WSRP vendors may also be able to support the WS-Security configuration of Username Token without password, with XML digital signature on the Username Token and the SOAP Message body.

Security Domain Implication

When using secure identity propagation as described in this section, the user name of the user authenticated to the consumer (WebCenter Portal application) is propagated to the producer without any remapping or providing any credentials. There is an inherent assumption that the producer understands this user name and can locate this user in its associated security domain. Consequently, it is highly desirable to ensure that the consumer and producer share the same security provider (identity store) to simplify the management of this configuration.

67.17.3 Configuring Security for WSRP Portlets

Before you configure the producer for WS-Security, you must first deploy your standards-compliant portlet producer to the Oracle WebCenter Suite WSRP Container by performing the steps described in Chapter 61, "Testing and Deploying Your Portlets".

After you have deployed the producer, configure the producer for WS-Security by performing the following steps:

When using this user identity for sensitive operations, it is important to ensure that you have configured this producer to use basic message authentication to secure the integrity of the identity assertion.

67.18.2.2 Authorization

67.18.2.3 Message-level Security

To this point, user authentication and authorization are covered, which do not check the authenticity of messages received by a producer. To completely secure your producers, you should also secure the communication with a producer. If the communication is not secured, then it is possible for someone to imitate an application instance and fool the producer into returning sensitive information. There are three types of communication security:

Server Authenticationrestricts access to a producer to a small number of recognized computers. This method compares the IP address or the host name of an incoming HTTP message with a list of trusted hosts. If the IP address or host name is in the list, then the message is passed to the producer. If not, it is rejected before reaching the producer.

Message Authentication provides consumer authentication and message integrity. It uses a shared key known to the client (WebCenter application) and the producer to digitally sign messages. See Section 67.18.5, "Message Authentication" for more information.

Message Encryptionrelies on the use of the HTTPS protocol for communication between applications and producers. Messages are strongly encrypted to protect the data therein. Encryption provides a high level of security, but it incurs a performance penalty due to the additional processing required for each message.

User Input Escape causes the application to escape any user input strings and treat them as text only to protect against XSS attacks, where an attacker attempts to pass in malicious scripts through user input forms. For example, if a portlet title is customizable, then an attacker might attempt to pass scripts or commands to the portlet through the title parameter entry. For this reason, the default behavior is to escape user input and thus disable any incoming scripts. See Section 67.18.6, "User Input Escape" for more information.

67.18.3 Single Sign-On

Portlets may act as windows into an application. They display summary information and provide a way to access the full functionality of the application. Portlets display some portions of the application in the WebCenter Portal application and typically enable the user to perform some application tasks.

An application may need to authenticate the user accessing the application through the portlet. The following are the possible application authentication methods:

External Application. In this case, the Oracle Portal (Oracle Portal) user is different from the application user, but the application user name and password are managed by the Oracle Portal user.

67.18.3.1 External Application

An external application uses a different authentication server than the WebCenter Portal application. This means that when a user is logged into the WebCenter Portal application, you want to also log them into the external application without having to type in their user name or password.

Applications that manage the authentication of users can be loosely integrated with the WebCenter Framework if the administrator registers them as external applications. When a user who was previously authenticated by the WebCenter Framework accesses an external application for the first time, WebCenter Framework attempts to authenticate the user with the external application. The authentication process submits an HTTP request that combines the registration information and the user's user name and password for the application. If the user has not yet registered their user name and password for the external application, then the user is prompted for the required information before making the authentication request. When a user supplies a user name and password for an external application, WebCenter Framework maps the new user name and password to the WebCenter Portal application user name and stores them. They will be used the next time the user needs authentication with the external application.

The advantages of an external application implementation are as follows:

Provides a single sign-on experience for users. However, users still must maintain different user names and passwords. In addition, the external application user name mapping must be maintained.

Allows integration with multiple portals independent of their user repositories and Oracle Single Sign-On.

Avoids the requirement of having access to the application source code.

The disadvantages of an external application implementation are as follows:

Does not share the same user repository as the portal, which requires additional maintenance of user information by the end user.

Transmits the user name and password to the producer in plain text, unless you implement Secure Sockets Layer (SSL).

67.18.3.2 No Application Authentication

The producer trusts the WebCenter Portal application instance sending the request completely. The producer can determine if the user is logged in and the portal user name, but the application has not authenticated the user.

The advantages of no application authentication are as follows:

Provides the easiest form of integration and the fastest to implement.

The disadvantages of no application authentication are as follows:

Provides the least security.

Provides the weakest integration with the WebCenter Portal application.

67.18.4 Portlet Security Managers

Portlet security managers may be implemented within a producer to restrict access to portlets depending on the user details. When a user views a page with a portlet instance on it, security managers determine whether the user has the appropriate privileges to see the portlet. Implementing access control methods in the producer restricts the retrieval of content from a portlet (that is, hides the portlet) from users without the appropriate privileges. Only if the specified characteristics, such as user details and preferences, pass the authorization logic will the content be retrieved for the user. If no portlet security methods are implemented in the producer, then any user name may be passed in, even fictitious, unauthenticated ones.

AuthLevelSecurityManager has access to the following information about authorization level:

Strongly authenticated.

The user has signed into the WebCenter application, and requested the portlet in the context of that session.

Public or not authenticated.

The user has not logged in within the context of the current session, and does not have a persistent cookie to indicate that such a state previously existed.

To incorporate these security services into your Java portlet, you must update provider.xml and set the security level to strong, weak, or public. Place the following XML right before the </portlet> tag in provider.xml:

67.18.4.1 Implementing Your Own Security Manager

If your portlet requires special security arrangements which are not provided by the implementations shipped with the PDK, then you must supply your own custom PortletSecurityManager controller class. To do this, extend the oracle.portal.provider.v2.security.PortletSecurityManager class and supply implementations for the two methods specified by the interface. Then replace the class attribute of the securityManager controller element in the XML producer definition with you new class name and configure child elements appropriately.

67.18.5 Message Authentication

Message authentication uses a digital signature. The signature is generated using a Hashed Message Authentication Code (HMAC) algorithm and is based on user information, the shared key, and a UTC (Universal Time, Coordinated) timestamp. The producer authenticates the message using its own copy of the shared key. This technique can be used in Secure Sockets Layer (SSL) communication with a producer instead of client certificates.

For caching purposes, show request signatures are calculated each time a session is set up so producers using message authentication must always have Producer Sessions enabled. This also means that there is a trade-off between performance and security. Shorter session timeouts mean less chance of a message being re-sent illegally, but there is a performance overhead associated with reestablishing a provider session.

A single producer instance cannot support multiple shared keys because it could cause security and administration problems. For instance, if one copy of the shared key is compromised in some way, then the producer administrator has to create a key and distribute it to all of the application clients, who then must update their producer definitions. The way around this problem is to deploy different producer services, specifying a unique shared key for each service. Each producer service has its own deployment properties file so that each service is configured independently of the others. The overhead of deploying multiple producer services within the same producer adapter is relatively small.

While the signature element provides protection against interception and resending of messages, it does nothing to prevent interception and reading of message contents. Messages are still transmitted in plain text. If you are concerned about the content of messages being read by unauthorized people, then this must used in conjunction with SSL to encrypt the message.

The advantage of message authentication is as follows:

Ensures that the message received by a producer comes from a legitimate WebCenter Portal application instance.

The disadvantages of message authentication are as follows:

Causes administration problems if a producer serves multiple portals. Entails performance implications if made very secure by having a short session timeout.

67.18.6 User Input Escape

By accepting user input without escaping it to text, you run the risk of an XSS attack, where an attacker attempts to pass in malicious scripts through user input forms. For example, if a portlet title is customizable, then an attacker might attempt to pass scripts or commands to the portlet through the title string. PDK-Java provides the following features to ensure that you can protect your portlets from such attacks:

67.18.6.1 Default Container Encoding

To prevent any script inside a portlet title from being executed, the framework default container renderer class encodes any script characters. This default behavior is controlled through a JNDI variable, escapeStrings. When set to true, the markup tags in portlet titles are rendered as visible tag characters. For example, a title customization of <i>title</i> will be rendered as <i>title</i> not title. This mode is secure, but, if it is not the desired behavior, then you can set escapeStrings to false for that producer.

escapeStrings applies to all logical producers within a producer. You can set the value of escapeStrings from the Fusion Middleware Control Console as you would any other JNDI variable. See Section 60.3.5.2, "Setting JNDI Variable Values" for more information.

67.18.6.2 Escape Methods

If you have code that renders customized values, then you must ensure that you escape those input values appropriately to avoid XSS attacks. This requirement applies to code for rendering pages in any mode. PDK-Java supplies two new static methods for this purpose. They are in the Java class oracle.portal.provider.v2.url.UrlUtils, and can be described as follows:

public static escapeString(string_text) escapes any script characters in a given string. For example, less than < becomes &lt. This method is unaffected by the escapeStrings JNDI variable and is the secure, recommended method to use.

public static escapeStringByFlag(string_text) escapes any script characters in a given string. This method is controlled by the escapeStrings JNDI variable and is therefore less secure and not the recommended method to use.

67.19.1 Error Message Appears When Running a Page with a Content Repository Data Control Method Being Consumed

Problem

When you run a page containing a content repository data control method, the following error message appears:

"Unable to locate the credential for key extapp in JPS credential store."

Cause

Credentials need to be provisioned explicitly using the change password task flow before you access the page that uses the data control method.

Solution

Since the data control is only a model and cannot do anything at the user interface level to allow credential provisioning, you must write an error handler that takes care of the redirection in the user interface. For information about writing an error handler, see the "Customizing Error Handling" section in the Oracle Application Development Framework Developer's Guide.