23 Managing External Applications

An external application is any application that implements its own authentication process. Specifically, it is an application that does not take part the single sign-on process for your portal application (that is, WebCenter Portal or your own Portal Framework application).

System administrators can use Fusion Middleware Control or the WLST command-line tool to register and manage external applications for WebCenter Portal and Portal Framework application deployments.

Application administrators can also register and manage external applications at runtime through out-of-the-box administration pages or using external application task flows.

All external application changes that you make for WebCenter Portal or Portal Framework applications post deployment, are stored in the MDS repository as customizations.

Note:

External application configuration is dynamic. Configuration changes are immediately reflected in WebCenter Portal and Portal Framework applications; it is not necessary to restart the application or the managed server.

This chapter includes the following sections:

Permissions:

To perform the tasks in this chapter, you must be granted the WebLogic Server Admin role through the Oracle WebLogic Server Administration Console and the Administrator role in the deployed application:

  • WebCenter Portal: Administrator role granted through Portal Builder Administration.

  • Portal Framework application: Administrator role granted through the Administration Console.

For more information about roles and permissions, see Section 1.8, "Understanding Administrative Operations, Roles, and Tools."

23.1 About External Applications

If WebCenter Portal your own Portal Framework application interacts with an application that handles its own authentication, you can associate that application with an external application definition to allow for credential provisioning. In doing so, you use an external application definition to provide 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 user name and password, and any other credentials for the external application, and supplies it to the WebCenter Portal tool or application requiring the credentials. The WebCenter Portal tool or other application then uses this information to log 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.

Note:

When logging in to an external application, if you clear the Remember My Login Information check box, then the credentials provisioned for that user session are lost in the event of 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 a Portal Framework application can be specified before deployment through a wizard in Oracle JDeveloper, or after deployment through Fusion Middleware Control Console (Figure 23-1) or using WLST commands. Post-deployment, external applications specified at design time in JDeveloper display automatically. However, after deployment you must reprovision design-time shared and public credentials using Fusion Middleware Control or WLST commands. For information, see Chapter 31, "Configuring the Identity Store," and Chapter 32, "Configuring the Policy and Credential Store."

Figure 23-1 Edit External Application

Description of Figure 23-1 follows
Description of "Figure 23-1 Edit External Application"

23.2 Registering External Applications

You can register external applications for WebCenter Portal and Portal Framework applications through Fusion Middleware Control or using WLST commands.

Before registering an external application, access the application's login page and examine the HTML source for the application's login form. All the registration details you require are located in the <form tag>.

For example, the underlying code for the Yahoo! Mail login form looks something like this:

<form method=post action="https://login.yahoo.com/config/login?" autocomplete="off" name="login_form">
...
<td><input name="login" size="17"</td>
...
<td><input name="passwd" size="17"</td>
...

In this example, to provide WebCenter Portal users with a direct link to the Yahoo! Mail application, the following sample registration information is required:

Registration Information Sample Value HTML Source

Login URL

https://login.yahoo.com/config/login?

action

User Name / User ID Field

login

name="login"

Password Field Name:

passwd

name="passwd"

Authentication Method

post

method

Note:

External application configuration is dynamic. New external applications and updates to existing applications are immediately available; there is no need to restart WebCenter Portal or your Portal Framework application.

For information about tools that use external applications, see the "Secured Service Connections" section in Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

This section includes the steps for:

23.2.1 Registering External Applications Using Fusion Middleware Control

To register an external application:

  1. Login to Fusion Middleware Control and navigate to the home page for your WebCenter Portal or Portal Framework application:

  2. Do one of the following:

    • For WebCenter Portal - From the WebCenter Portal menu, select Settings > Service Configuration.

    • For Portal Framework applications - From the Application Deployment menu, select WebCenter Portal > Service Configuration.

  3. From the list of services on the WebCenter Portal Service Configuration page, select External Applications.

  4. To register a new external application, click Add (Figure 23-2).

    Figure 23-2 Configuring External Application Connections

    Configuring External Applications

  5. Enter a unique name for the external application and a display name that application users working with this external application will see.

    See also Table 23-1.

    Table 23-1 External Application Connection - Name

    Field Description

    Application Name

    Enter a name for the application. The name must be unique (across all connection types) within the application.

    For example: yahoo

    Note: Once registered, you cannot edit the Application Name.

    Display Name

    Enter a user friendly name for the application that WebCenter Portal users will recognize. Application end-users working with this external application will see the display name you specify here.

    For example: My Yahoo

    If you leave this field blank, the Application Name is used.

  6. Enter login details for the external application.

    For details, see Table 23-2.

    Table 23-2 External Application Connection - Login Details

    Field Description

    Enable Automatic Login

    Select to allow automatically log users in to this application. Choosing this option requires you to complete the Login URL, HTML User ID Field Name, and HTML User Password Field Name fields

    With automated single sign-on, the user directly links to the application and is authenticated automatically, as their credentials are retrieved from the credential store. Selecting this option 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.

    • External applications that accept randomly generated hidden field values or cookies for successful login.

    Login URL

    Enter the login URL for the external application.

    To determine the URL, navigate to the application's login page and record the URL.

    For example: http://login.yahoo.com/config/login

    Note: A login URL is not required if the sole purpose of this external application is to store and supply user credentials on behalf of another service.

    HTML User ID Field Name

    Enter the name that identifies the "user name" or "user ID" field on the login form.

    Tip: To find this name, look at the HTML source for the login page.

    This property does not specify user credentials.

    Mandatory if the Authentication Method is GET or POST. Leave this field blank if the application uses BASIC authentication (see Authentication Method).

    HTML User Password Field Name

    Enter the name that identifies the "password" field on the login form.

    Tip: To find this name, look at the HTML source for the login page.

    Mandatory if the Authentication Method is GET or POST. Leave this field blank if the application uses BASIC authentication (see Authentication Method).

  7. Select the authentication method used by the external application.

    For details, see Table 23-3.

    Table 23-3 External Application Connection - Authentication Details

    Field Description

    Authentication Method

    Select the form submission method used by the external application. Choose from one of the following:

    • GET: Presents a page request to a server, submitting the login credentials as part of the login URL. This authentication method may pose a security risk because the user name and password are exposed in the URL.

    • POST: Submits login credentials within the body of the form. This is the default.

    • BASIC: Submits login credentials to the server as an authentication header in the request. This authentication method may pose a security risk because the credentials can be intercepted easily and this scheme also provides no protection for the information passed back from the server. The assumption is that the connection between the client and server computers is secure and can be trusted.

    The Authentication Method specifies how message data is sent by the browser. You can find this value by viewing the HTML source for the external application's login form, for example, <form method="POST" action="https://login.yahoo.com/config/login?" AutoComplete="off">

  8. Specify additional login fields and details, if required.

    For details, see Table 23-4, "External Application Connection - Additional Login Fields".

    Table 23-4 External Application Connection - Additional Login Fields

    Field Description

    Additional Login Fields

    If your application requires additional login criteria, expand Additional Login Fields.

    For example, in addition to user name and password, the Lotus Notes application requires two additional fields - Host and MailFilename.

    Click Add to specify an additional field for the login form. For each new field, do the following:

    • Name - Enter the name that identifies the field on the HTML login form that may require user input to log in. This field is not applicable if the application uses basic authentication.

    • Value - Enter a default value for the field or leave blank for a user to specify. This field is not applicable if the application uses basic authentication.

    • 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.

    Click Delete to remove a login field.

  9. Specify shared and public user credentials, if required.

    For details, see Table 23-5.

    Table 23-5 External Application Connection - Shared User and Public User Credentials

    Field Description

    Enable Shared Credentials

    Indicate whether this external application enables shared user credentials, and specify the credentials. Select Enable Shared Credentials, and then enter User Name and Password credentials for the shared user.

    When shared credentials are specified, every user accessing this external application, through either WebCenter Portal or your Portal Framework application, is authenticated using the user name and password defined here. WebCenter Portal users are not presented with a login form.

    Because WebCenter Portal users do not need to define personal credentials of their own, external applications with shared credentials are not listed in the external application's change password task flows such as My Accounts.

    See also the "Providing Login Information for External Applications" section in Oracle Fusion Middleware Using Oracle WebCenter Portal.

    Enable Public Credentials

    Indicate whether unauthenticated users (public users) may access this external application. Select Enable Public Credentials, and then enter User Name and Password credentials for the public user.

    When public credentials are specified, public users accessing this external application through either WebCenter Portal or your Portal Framework application's public pages, are logged in using the username and password defined here. If public credentials are not specified, public users will see an authorization error indicating this external application is not accessible to public users.

  10. Click OK to register the application.

23.2.2 Registering External Applications Using WLST

Use the WLST command createExtAppConnection to create an external application connection. For command syntax and examples, see createExtAppConnection in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

Use the WLST command addExtAppCredential to add shared or public credentials for an existing external application connection. For details, see addExtAppCredential in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

Use the WLST command addExtAppField to define additional login criteria for an existing external application connection. For details, see addExtAppField in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

23.2.3 Registering External Applications in WebCenter Portal

For information about registering external applications through Portal Builder Administration, see Section 8.3.2, "Configuring Tools and Services for WebCenter Portal".

23.2.4 Registering External Applications in Portal Framework Applications

For information about registering external applications in Portal Framework applications, see Section 23.4, "Managing External Applications with the WebCenter Portal Administration Console".

23.3 Modifying External Application Connection Details

This section shows you how to modify the external application connection details by:

23.3.1 Modifying External Application Connection Using Fusion Middleware Control

To update external application connection details:

  1. Log in to Fusion Middleware Control and navigate to the home page for your WebCenter Portal or Portal Framework application:

  2. Do one of the following:

    • For WebCenter Portal - From the WebCenter Portal menu, select Settings > Service Configuration.

    • For Portal Framework applications - From the Application Deployment menu, select WebCenter Portal > Service Configuration.

  3. From the list of services on the WebCenter Portal Service Configuration page, select External Applications.

  4. Select the name of the external application you want to modify, and click Edit.

  5. Edit connection details, as required. For detailed parameter information, see Table 23-2.

    Note that you cannot edit the name of the external application.

  6. Click OK to save your changes.

23.3.2 Modifying External Application Connection Using WLST

Use the WLST command setExtAppConnection to edit existing external application connection details. For command syntax and examples, see setExtAppConnection in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

Note:

To edit details relating to an additional login field, use setExtAppField. To edit existing shared or public credentials, use setExtAppCredential.

To delete an additional login field, use removeExtAppField. To delete shared or public credentials, use removeExtAppCredential.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

For information about modifying external applications in WebCenter Portal, see the "Editing External Application Connection Details" section in Oracle Fusion Middleware Using Oracle WebCenter Portal.

23.4 Managing External Applications with the WebCenter Portal Administration Console

To be able to register and manage external applications in a Portal Framework application, a user must be assigned the AppConnectionManager role. By default, users with the Administrator role have the AppConnectionManager role; and therefore, application administrators can configure external applications through the WebCenter Portal Administration Console.

An external application is any application that implements its own authentication process. Specifically, it is an application that does not take part in the Portal Framework application's single sign-on process. If your Portal Framework application interacts with an application that handles its own authentication, you can register an external application to allow for credential provisioning.

Application administrators can register, edit, and delete external applications for a Portal Framework application at runtime, through the WebCenter Portal Administration Console.

This section includes the following subsections:

Note:

System administrators can also register external applications for Portal Framework applications, using Fusion Middleware Control and WLST commands. For details, see Chapter 21, "Managing Portlet Producers."

23.4.1 Registering External Applications

To register an external application at runtime for a Portal Framework application:

  1. Navigate to the Services administration tab.

    See also, Section 43.2, "Accessing the Administration Console for Portal Framework Applications".

  2. Select External Application (Figure 23-3).

    Figure 23-3 WebCenter Portal Administration Console - External Applications

    Description of Figure 23-3 follows
    Description of "Figure 23-3 WebCenter Portal Administration Console - External Applications"

  3. Click Register.

  4. Enter connection details for the external application.

    If you need help with one or more fields, refer to the following tables:

  5. Click Test to verify your connection details.

  6. Click OK to register the application.

23.4.2 Editing and Deleting External Applications

To modify or delete external applications at runtime for a Portal Framework application:

  1. Navigate to the Services administration tab.

    See also, Section 43.2, "Accessing the Administration Console for Portal Framework Applications".

  2. Select External Application (Figure 23-3).

  3. Select the external application required and then click one of the following:

    • Click Edit to update connection details for an external application.

    • Click Deregister to remove the external application.

      Take care when deleting an external application connection as Portal Framework application users will no longer have access to that application, and any services dependent on the external application may not function correctly.

23.5 Testing External Application Connections

For external applications that are created using login URLs, ensure that their login URLs are accessible. For information about direct URLs, see the "Automated Single Sign-On" section in Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

23.6 Deleting External Application Connections

Take care when deleting an external application connection as users in WebCenter Portal or your Portal Framework application will no longer have access to that external application, and any tools or services dependent on the external application may not function correctly.

This section includes the following subsections:

23.6.1 Deleting External Application Connections Using Fusion Middleware Control

To delete an external application connection:

  1. Log into Fusion Middleware Control and navigate to the home page for your WebCenter Portal or Portal Framework application:

  2. Do one of the following:

    • For WebCenter Portal - From the WebCenter Portal menu, select Settings > Service Configuration.

    • For Portal Framework applications - From the Application Deployment menu, select WebCenter Portal > Service Configuration.

  3. From the list of services on the WebCenter Portal Service Configuration page, select External Applications.

  4. Select the name of the external application you want to remove, and click Delete.

23.6.2 Deleting External Application Connections Using WLST

Use the WLST command deleteConnection to remove an external application connection. For command syntax and examples, see deleteConnection in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

Note:

To delete an additional login field, use removeExtAppField. To delete shared or public credentials, use removeExtAppCredential.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

23.7 Troubleshooting External Application Issues

This section contains common issues and workarounds related to external applications.

This section contains the following subsections:

23.7.1 Users Experience Password Lockout

Problem

Using an external application to store or retrieve credentials for collaboration connections when your identity store uses a password change policy that causes the password to be changed in the identity store directly, may lead users to experience a password lockout.

Solution

The external applications cannot know that a password has been changed directly in the identity store and consequently cannot react to it. A partial solution is to define one external application for all your collaboration connections. For releases prior to PS6, contact support to apply patches for bugs 9327220, 12965480, 14174484, 14309006 in your environment.