3 Proxy Resources

This chapter describes how to configure Oracle WebCenter Ensemble resources. It is divided into the following sections:

• About Oracle WebCenter Ensemble Resources, describes what an Oracle WebCenter Ensemble resource is.

• Registering a Resource, describes how to create a basic Oracle WebCenter Ensemble resource.

• Advanced Resource Configuration, describes additional configurations of Oracle WebCenter Ensemble resources, including URL rewriting, resource roles, the Oracle WebCenter Interaction login token, and authentication.

• Migrating Resources, describes how to export and import Oracle WebCenter Ensemble resources and their associated pagelets.

• Working with Web Injectors, describes how to create web injectors, configure injection patters, and apply web injectors to resources.

About Oracle WebCenter Ensemble Resources

Oracle WebCenter Ensemble resources are web applications registered in Oracle WebCenter Ensemble. A registered resource maps an internal URL, accessible by Oracle WebCenter Ensemble, to an external URL, accessible by end users. Any web application can be registered as a resource.

Registering a web application as an Oracle WebCenter Ensemble resource allows Oracle WebCenter Ensemble to do the following:

• Proxy internal web applications to external addresses.

• Manage authentication, both at the proxy level (Oracle WebCenter Ensemble controls access to resources using Oracle WebCenter Ensemble policies and roles) and at the resource level (Oracle WebCenter Ensemble provides credentials to proxied web applications).

• Transform proxied web applications, including URL-rewriting and the use of Oracle WebCenter Ensemble and Oracle WebCenter Interaction adaptive tags.

• Customize the user experience through custom login, logout, interstitial, and error pages.

Registering a Resource

You register a resource in Oracle WebCenter Ensemble using the Ensemble Console. The simplest Oracle WebCenter Ensemble resource has three configured properties:

• Name.

• Internal URL prefix, which is the URL of the application to be proxied.

• External URL prefix, which is the URL that end users will use to access the application.

Once configured, all URLs starting with the Internal URL prefix are accessible via the External URL prefix. For example, if the Internal URL prefix is:

http://internalServer/foo

and the External URL prefix is:

http://externalServer/bar

the external path:

http://externalServer/bar/index.jsp

will map to:

http://internalServer/foo/index.jsp

and

http://externalServer/bar/baz/index.jsp

will map to:

http://internalServer/foo/baz/index.jsp

To register a simple resource in Oracle WebCenter Ensemble:

1. Launch the Ensemble Console.

2. Click the APPLICATIONS tab.

3. Click the Resources sub-tab.

4. To create a new resource, click Create new.

5. On the General page, in the Name box, type the name of the resource.

6. On the Connections page, in the Internal URL prefix box, type the URL to the internal web application to be proxied. For example, http://internalServer/foo/.

7. In the External URL prefixes box, type the URL to be used to access the resource. This URL must be on the Ensemble Proxy server. You may specify a fully-qualified URL or a path relative to the Ensemble Proxy server. For example, http://externalServer/bar/ or just /bar/.

   
   

   Note: A fully-qualified external URL prefix must include the same port used by the Ensemble Proxy server unless the Use Proxy Port option is checked, in which case any specified port will be changed to an asterisk and Oracle WebCenter Ensemble will assume that the proxy's port is in the external URL.

   
   

8. Click Save.

Advanced Resource Configuration

This section describes advanced configuration options for Oracle WebCenter Ensemble resources. It is divided into the following sub-sections:

• URL Rewriting and DNS

• Roles

• Proxy Authentication

• Credential Mapping

• The AquaLogic Interaction Login Token

URL Rewriting and DNS

When you enable URL rewriting, the Ensemble Proxy rewrites URLs in the proxied application that begin with the internal URL prefix so that they point to the external URL prefix. Oracle WebCenter Ensemble enables URL rewriting by default.

You should disable URL rewriting when the internal URL prefix and external URL prefix are identical. When this occurs, the user's DNS must resolve the URL to the Ensemble Proxy server, and the Ensemble Proxy server's DNS must resolve the URL to the internal resource. Because DNS only resolves IP and not port, both servers must listen to the same port.

To disable URL rewriting:

1. Launch the Ensemble Console.

2. Click the APPLICATIONS tab.

3. Click the Resources sub-tab.

4. Click the resource you want to edit.

5. On the General page, uncheck the box next to Enable URL Rewriting.

6. Click Save.

Roles

You can configure Oracle WebCenter Ensemble to send role information to proxied applications. You define the roles available for Oracle WebCenter Ensemble to send to the proxied application within the resource configuration. Policies determine which of these roles Oracle WebCenter Ensemble sends for a given user.

For details on policies and how they map to roles, see Chapter 6, "Policies and Rules."

Oracle WebCenter Ensemble sends roles in the HTTP header and are accessed by the proxied application using the Oracle WebCenter Interaction Development Kit (IDK) proxy API. For details on using the Oracle WebCenter Interaction Development Kit (IDK) proxy API, see the Oracle WebCenter Interaction Development Kit (IDK) documentation on the Oracle Technology Network at http://download.oracle.com/docs/cd/E13158_01/alui/idk/docs103/index.html.

To configure roles to send to a proxied application:

1. Launch the Ensemble Console.

2. Click the APPLICATIONS tab.

3. Click the Resources sub-tab.

4. Click the resource you want to edit.

5. On the Roles page, type the names of the role or roles. Click Add to create additional roles.

6. Click Save.

The roles entered on the Roles page are the values that Oracle WebCenter Ensemble can send to the proxied application, based on what policy or policies are associated with the user.

Proxy Authentication

Proxy Authentication describes how users log into Oracle WebCenter Ensemble resources. Oracle WebCenter Ensemble can facilitate authentication using a variety of methods, including basic authentication, HTML form-based authentication, and integration with third-party SSO products.

For details on Proxy Authentication, see Chapter 4, "Proxy Authentication."

Credential Mapping

Credential mapping allows Oracle WebCenter Ensemble to automatically supply credentials to proxied applications. The credentials can be a static set used for all users, credentials specific to the user and stored in the user's Oracle WebCenter Interaction user profile, or credentials used once by the user and captured and stored by Oracle WebCenter Ensemble in the Credential Vault. The Credential Vault allows users to authenticate once and then be logged in automatically by Oracle WebCenter Ensemble in future accesses to the proxied resource.

For details on credential mapping, see Chapter 5, "Credential Mapping."

The AquaLogic Interaction Login Token

The AquaLogic Interaction login token allows the Oracle WebCenter Ensemble resource to access the AquaLogic Interaction IPortletContext object. By default, the AquaLogic Interaction login token is not passed to the proxied resource.

To pass the login token to the proxied resource:

1. Launch the Ensemble Console.

2. Click the APPLICATIONS tab.

3. Click the Resources sub-tab.

4. Click the resource you want to edit.

5. On the CSP page, select Send ALI login token.

6. Click Save.

Migrating Resources

Ensemble Migration allows you to export and import Oracle WebCenter Ensemble resources and their associated pagelets. The exported resource configuration is stored in an XML file, which you can then import into another installation of Oracle WebCenter Ensemble.

Exporting Resources with Migration

To export a resource and its associated objects:

1. Launch the Ensemble Console.

2. Click the Administration tab.

3. Click the Migration sub-tab.

4. Click the Export tab.

5. Launch the resource picker by clicking Add Resource.

6. Select the resources you want to export. Click Add selected items.

7. Confirm the resources to be exported and click OK.

8. Click Export.

   The File Download dialog box appears.

9. Click Save.

   The Save As dialog box appears.

10. Navigate to the location on the local machine to which you want to save the file.

11. If desired, rename the file to something other than the default of ensemble_migration.xml.

12. Click Save.

The migration file is saved to the local machine. You can now import the migration file to any Oracle WebCenter Ensemble installation. now located on the local machine in the chosen location, and can be imported to any Ensemble installation.

Importing Resources With Migration

To import a resource from an existing migration package:

1. Launch the Ensemble Console.

2. Click the Administration tab.

3. Click the Migration sub-tab.

4. Click the Import tab.

5. Type the full path to the migration package in the Import this file box.

6. Choose how you want to deal with duplicate resources by selecting Rename imported resource or Overwrite existing resource.

7. Click Prepare Import.

8. Depending on the content of the migration package, you might be prompted to update values for specific object properties. Follow the instructions on the screen.

9. Click Import.

On success, the Ensemble Console displays a list of imported objects and any autofixes that were completed during the import process.

Working with Web Injectors

A web injector inserts content into a specified location in the proxied resource page. The content may be any text, including HTML, CSS, JavaScript, and pagelet declarations.

To use a web injector with a resource, you must first create the web injector and then, from the resource configuration, apply the web injector to that resource.

Creating Web Injectors

To create a new web injector:

1. Click the Applications tab.

2. Click the Web Injectors sub-tab.

3. Under the web injectors view, click Create New.

4. On the General tab, type a name and description.

5. On the Details tab, configure one or more injection patterns. For details, see Configuring Injection Patterns.

Configuring Injection Patterns

An Injection Pattern describes what the content is and where it is to be injected. An Injection Pattern can either be based on an existing web injector, or defined as a new pattern:

• To base the Injection Pattern on an existing web injector, click Add Existing Injector.

• To create a new pattern, click Define New Pattern.

The following table describes the configuration options for a new Injection Pattern:

Table 3-1 Injection Pattern Configuration Options

Field	Description
What to Inject	Type the content to be injected into the What to Inject box. Content may be any text, including HTML, CSS, JavaScript, and pagelet declarations. To automatically populate the What to Inject box with a pagelet declaration, select a pagelet from the Insert pagelet declaration for drop-down list and click Insert.
Where to inject	Define where in the resource's output the injection occurs by selecting one of the following: Top of the page puts the content first in the page. Do not use this option to inject pagelet declarations. Bottom of the page puts the content last in the page. The Before/After/In place of drop-down list puts the content into the page relative to what you type in the specific text box. To make the text identify an entire start tag, select Enclosing tag. This will match the tag regardless of what attributes are present, if any. For example, if your text is div and Enclosing tag is selected, <div> will match as will <div id="main">. To match the text regardless of case, select Ignore case. To match the text in pagelet output, select Apply to underlying pagelets. If Apply to underlying pagelets is not selected, the content of any pagelets in the page will not be considered when Ensemble determines where to make injections. Note: Even when Apply to underlying pagelets is selected, the pagelet declaration is a candidate for matching. If you have selected In place of and your text matches part of the pagelet declaration, your injected content will replace that part of the pagelet declaration. This might cause the pagelet to not be displayed or yield other undesired results.
Apply only to Content Types	To restrict the injector to specific kinds of content, type a comma separated list of MIME types in the Apply only to Content Types box. For example, text/html restricts the injector to HTML content, while text/css only restricts the injector to CSS content.

Applying Web Injectors to Resources

To apply a web injector to a resource:

1. Launch the Ensemble Console.

2. Click the Applications tab.

3. Click the Resources sub-tab.

4. Click the name of the resource to which you want to apply a web injector.

5. Click the Web Injectors tab.

6. From the drop-down list, select the name of the web injector to apply to the resource.

7. If desired, make the web injector applicable to a subset of the resource by typing a URL pattern into the URL Filter box. If the box is empty or contains only a /, the web injector is applied to the entire resource. If anything else is typed into the box, only URLs within the resource that begin with what is in the box will have the web injector applied.

8. To apply more than one web injector to the resource, click Add and repeat steps 6 and 7 for each web injector.