Configuring Trusted Authentication

In this section:

This section describes how to configure Managed Reporting to trust the authentication being performed by the Web server. Managed Reporting does not perform authentication when configured with the trusted option. Instead, WebFOCUS reads the user ID from REMOTE_USER or from a configurable HTTP header variable and passes it to Managed Reporting. Managed Reporting then uses the ID for authorization purposes.

Supported options include Basic authentication, Integrated Windows Authentication (IWA), and third-party security products, including Netegrity SiteMinder, Oracle Oblix, RSA ClearTrust, and Tivoli Access Manager. Custom-developed security systems can also be supported in many cases. For additional information regarding integration with third-party security products, see http://techsupport.informationbuilders.com/tech/wbf/wbf_faq_integration.html.

Top of page
x
Enabling Trusted Authentication

How to:

You use the WebFOCUS Administration Console to select trusted authentication for Managed Reporting. To understand what happens when you make this change, see Internal Processing for Trusted Authentication.

x
Procedure: How to Enable Trusted Authentication
  1. Go to the WebFOCUS Welcome page (http://hostname:port/ibi_apps/, where hostname is the host name of the machine on which the WebFOCUS Client is installed, and port is the port on which it listens) and click the WebFOCUS Administration Console link.
  2. Log on to the Console as an administrator (the default administrator ID is admin with no password).
  3. Click General under MR Security Settings in the Configuration block.
  4. Select the Trusted option. Depending on the requirements at your site, you must choose the type of Web server variable that will be used to implement this option:
    • Use Web server REMOTE_USER variable. Optionally, you can include the Windows domain with the user ID. If you select the Include Windows domain option, you must create the MR user ID with the domain in the MR Administration Tool.

      MR Administration Tool dialog box

    • Use Web server HTTP variable. If you choose this option, you must type the name of the HTTP Header variable that will contain the user ID.

      MR Administration Tool dialog box

    In some cases, special configuration steps may be necessary to populate REMOTE_USER or to create the HTTP header variable containing the user ID. You can troubleshoot these settings by loading the page /ibi_apps/diagnostics/wfsysinf.jsp into your browser and checking what your servlet container sees for headers and for the value of REMOTE_USER. You may also find useful information in Web Server Authentication Considerations.

  5. Click Save. You are asked to reload the repository driver at this time.

    Reload pop up image

  6. Click OK to process your changes.

    To understand what happens when you click OK (or Cancel) on this dialog, see Internal Processing for Trusted Authentication.
Top of page
x
Using Developer Studio

When used with an environment configured for trusted authentication, you do not supply Managed Reporting credentials in the Developer Studio environment dialog box. These credentials would be ignored, as explained in Internal Processing for Trusted Authentication.

Instead, do one of the following:

If your Web server has a security system not listed here, you may be able to use the Basic option described above. Check with your security administrator.

The following diagram shows how to select Basic authentication and enter the Web server ID and password.

Web Component Authentication diagram

Note: In each case, the credentials you enter in the ID and password fields are encrypted and stored locally in your Documents and Settings\username\wfscom.wfs file. Alternatively, you can leave these fields blank, in which case you will be prompted for your user ID and password dynamically at the beginning of each session.
Top of page
x
Web Server Authentication Considerations

Reference:

This section provides Web server authentication considerations when configuring WebFOCUS.

x
Reference: Troubleshooting HTTP Headers and REMOTE_USER

Generally speaking, the Web server performs authentication and may set an environment variable called REMOTE_USER containing the authenticated user ID. Because Managed Reporting is only supported with the WFServlet implementation of the WebFOCUS Client, the value contained in the Web server REMOTE_USER variable must be propagated to the application server/servlet container. Some servlet containers (for example, ServletExec) pick up and set REMOTE_USER automatically. See the following sections for information about Tomcat and WebSphere.

HTTP headers are used to transport information about the request (and response) such as credentials and preferred content type. An HTTP header is a name:value pair. The header name is not case-sensitive. Some security products automatically set an HTTP header containing the user ID (for example, sm_user, iv-user, ct_user) and some allow the header name to be configurable.

Problems implementing trusted authentication often occur because of misunderstandings about the spelling of an HTTP header or the configuration requirements for making REMOTE_USER available to the WFServlet. To help troubleshoot these issues, review the information shown on the HTTP Request Info panel of the Diagnostics page of the console. You can access a similar diagnostic page outside the console under the URL /ibi_apps/diagnostics/wfsysinf.jsp.

Note: IWA requires the HTTP Keep-Alives Enabled option selected in IIS.
x
Reference: Enabling REMOTE_USER in an IIS/Tomcat Configuration

You can configure IIS to authenticate users (such as with Basic authentication or IWA) and propagate the authenticated user ID to Tomcat so that it can be used by WebFOCUS. However, you need to customize the Tomcat server.xml file. Add the attribute tomcatAuthentication="false" anywhere inside the connector element that defines your Jakarta AJP13 listener. This is typically the connector element that contains the port="8009" attribute.

x
Reference: Enabling REMOTE_USER in a WebSphere Configuration

When using WebSphere with IIS, you must disable WebSphere security in order for the user ID to be propagated to WebFOCUS in REMOTE_USER.

x
Reference: WebFOCUS Reporting Server Considerations

You must set the IBIMR_user variable when using REMOTE_USER, WF_REMOTE_USER or an HTTP header variable and using Trusted authentication on the reporting server. For more information about passing the IBIMR_user variable to the WebFOCUS Reporting Server, see Propagating the Managed Reporting ID to the WebFOCUS Reporting Server.
Top of page
x
Support for Integrated Windows Authentication

In this section:

Integrated Windows Authentication (also known as IWA, NTLM, and Windows Challenge/Response) is a popular protocol for implementing single sign-on in a Windows environment. Review the following information about limitations and additional configuration steps to enable WebFOCUS support for IWA.

x
Web Server Access Rights
x
ReportCaster Distribution Server Support
x
WebFOCUS Reporting Server Considerations

You cannot propagate the user context to the WebFOCUS Reporting Server because IWA is not supported over the JLINK and Java NG communication subsystems used by WFServlet. However, you should review the alternatives in Propagating the Managed Reporting ID to the WebFOCUS Reporting Server.
x
IWA and Proxy Servers

There are issues routing IWA over topologies with forward and reverse proxies. HTTP tracing tools, which are proxies, cannot be used to troubleshoot IWA problems. Contact your Web and/or network administrators to help troubleshoot IWA connectivity problems in your enterprise.
x
Reference: Browser Settings Required for IWA Support

Integrated Windows Authentication is only supported with Internet Explorer, and its use is governed by security settings in the browser and your network configuration. There are several approaches to enabling IWA support in the browser. The following procedure is a recommendation for Internet Explorer 6.0, but your network administrator may have different instructions.

By default, Internet Explorer 6.0 supports IWA with computers belonging to the Local intranet security zone. A Web site is considered to be on the local intranet when its address does not contain a dot, for example: http://webfocus/ibi_apps.

You can also access a Web site with a fully qualified domain name, for example, http://webfocus.ibi.com/ibi_apps. However, you must explicitly specify the fully qualified host or domain name in your Local intranet security zone.

  1. From the Internet Explorer menu select Tools, Internet Options, Security, Local intranet, and then Sites.

    Internet Options Security dialog box

  2. Select Advanced.

    Iternet security advanced settings

  3. Enter the fully qualified domain name of the Web site, or indicate its domain as shown below, and click Add. Then click OK three times to save the change. You do not need to restart the browser.

    Internet options security settings

  4. If you are still not able to access the Web site or if you are challenged to provide credentials, check your security settings for the Local intranet security zone.
    1. Select Security, Local intranet, and then Custom Level.

      Internet options security settings

    2. Scroll the options and verify that User Authentication, Logon, and then Automatic logon only in Intranet zone are selected.

      User Authetication Logon dialog box

There are two sub-protocols encapsulated in IWA: NTLM and Negotiate. The Negotiate protocol is a wrapper around both NTLM and Kerberos that the browser will try first when its Enable Integrated Windows Authentication (requires restart) property is checked.

Enable Integrated Windows Authentication dialog box

WebFOCUS is designed to work with the check box checked and unchecked. If you are having trouble however, you may wish to uncheck the box and see if the behavior changes. You can also use the wfsysinf.jsp page to determine which IWA protocol is being used in your environment by checking the value of the Authorization header. For information, see Troubleshooting HTTP Headers and REMOTE_USER.

If you still cannot sign-on to WebFOCUS with IWA, ensure that you can access the Web site with IWA before contacting Information Builders Customer Support Services for assistance with WebFOCUS.
Top of page
x
Support for Common Access Cards (CAC) Using PKI

In this section:

How to:

A Common Access Card (CAC) is a smart card issued by the United States Department of Defense for the identification of all Department of Defense personnel and contractors. These cards in conjunction with the appropriate card reader configuration on an end-user machine can be used to perform certificate-based authentication when the Web server has been configured to require client-side certificates following the Public Key Infrastructure (PKI) standard. WebFOCUS has the ability to retrieve the Common Name or User Principal Name attributes from the supplied user certificate to populate the REMOTE_USER variable so that CAC can be used to provide a trusted logon to Managed Reporting.
x
Pre-Installation Requirements

The Web server must be configured to prompt users for client-side certificates using PKI and the ActivIdentity card-reading software must be properly installed on end-user machines before the WebFOCUS Client can be configured to trust the client certificate. Please consult the documentation provided by the Department of Defense on the proper method to set up the Active Identity software.

In addition, before switching Managed Reporting over to use the REMOTE_USER value for automatic logon as outlined in Configuring Trusted Authentication, you must first follow the steps outlined in Preparing for Trusted or External Authentication and create at least one Managed Reporting Administrator that matches the value of the certificate attribute chosen for PKI_userid_source. For example, if the Managed Reporting Administrator has a Common Name (CN) of Joe.Smith.1122334455 and the PKI_userid_source is set to CN, the Managed Reporting UserID must be Joe.Smith.1122334455. If the Managed Reporting Administrator has a User Principal Name (UPN) of 1122334455@mil and the PKI_userid_source is set to UPN, the Managed Reporting UserID must be 1122334455@mil.
x
Procedure: How to Enable Trusted Logon Using a PKI Client Certificate
To enable a trusted logon using a PKI client certificate you must configure several properties within the WebFOCUS Administration Console.

  1. Go to the WebFOCUS Welcome page and click the WebFOCUS Administration Console link.
  2. Log on as an administrator.
  3. Click Configuration and then, under Application Settings, click Security.
  4. Edit the Security Settings as necessary and save your changes.
    These attributes are activated as soon as they are saved. You do not need to recycle the application server.
x
Reference: Security Settings for Trusted Logon Using a PKI Client Certificate
PKIFilter.enabled

Enables the PKI filter which will extract the attribute specified in PKI_userid_source to populate the REMOTE_USER variable. Managed Reporting and ReportCaster must be configured to use the REMOTE_USER variable for logon separately. For more information, see Configuring Trusted Authentication.

PKI_allow_ip

Specifies a list of IP addresses, separated by semi-colons, that will be allowed to pass the PKI filter even if there is not a valid client certificate in the request. The ReportCaster distribution server IP address must be included in this list for the ReportCaster distribution server to be able to retrieve Managed Reporting content. A sample list might look like:

127.0.0.1;127.0.0.2

If an IP address is not specified here and a client certificate is not provided, the PKI filter will return a 403 forbidden error when accessed.

PKI_userid_source

Specifies the certificate attribute that should populate REMOTE_USER for the user ID. The possible values are:

CN

The common name for the certificate. For example,

Joe.Smith.1122334455

UPN

The userPrincipalName attribute from the Subject Alternate Name section of the certificate. For example,

1122334455@mil

Due to the way the UPN is encoded, you must have a copy of the Bouncy Castle Java Cryptography library within your classpath. It can be downloaded from the Bouncy Castle Web site at http://www.bouncycastle.org/java.html.
x
ReportCaster Considerations

To schedule Managed Reporting content within ReportCaster, there must be a path to the WebFOCUS Client that does not require a client certificate, and the IP addresses of the machines where the ReportCaster distribution servers reside must be included in the PKI_allow_ip list.

It is recommended that you configure PKI on a separate Web server which forwards the request to the application server with the certificate. The ReportCaster distribution server can then be configured to go directly against the application server and bypass the Web server.

For example, on a Windows host, PKI can be configured on IIS, which forwards the requests to Apache Tomcat. The default Tomcat port can be left open on 8080 and you can configure ReportCaster to go to this port by updating the Repository Node on the MR Info tab of the ReportCaster Configuration.

If the ReportCaster distribution server is installed on the same machine as the WebFOCUS Client, it is advisable to set the host name to localhost and include the IP address 127.0.0.1 in the PKI_allow_ip list to keep all traffic local to the machine.

Note: When enabled, the PKI filter will prevent any access to the WebFOCUS Client unless the source IP address of the request is within the PKI_allow_ip. As a result it will not be possible for a regular user to bypass the PKI authentication and go directly to the application server.
x
Developer Studio Considerations

At this time Developer Studio does not support supplying a client certificate using PKI, and so it is not possible to use Developer Studio in an environment where this has been configured.
Top of page
x
Internal Processing for Trusted Authentication

When you save your Trusted authentication settings in the WebFOCUS Administration Console, a message asks if you would like WebFOCUS to update/replace your Managed Reporting repository driver.

If you click OK, the following occurs:

  1. The value of REPOSITORY_DRIVER in cgivars.wfs is set to ibi.uas.drivers.WFMRX_MRRealmDriverFactory.
  2. The value of AUTHENTICATION.MODE in mrrealm.cfg file is set to TRUSTED.
  3. A series of WebFOCUS script commands are generated and inserted into the mrsso.wfs file. This file is included during WebFOCUS processing (if it exists) by ibistdd.wfs. The script commands vary depending on your choices.
  4. The current repository driver loaded in memory is replaced by the Managed Reporting Realm Driver.

If you click Cancel instead, only the first three steps are performed by WebFOCUS, and your changes will not be realized until you reload your WebFOCUS Web application.

The mrsso.wfs file is created in the WebFOCUS/client/wfc/etc directory. The script commands inside this file instruct WebFOCUS how to obtain the authenticated user ID so that it can set the Managed Reporting ID of the user to this value. The mrsso.wfs file is processed with each WebFOCUS request, but the commands inside it are conditional on the MR_SIGNON action. For all non-sign-on requests the file has no effect on processing, and access control to Managed Reporting is controlled by MR_COOKIE, as described in Managed Reporting Processing Details.

If you selected REMOTE_USER and did not select the Include Windows domain (domain\userid) option, the mrsso.wfs file contents are:

<VER 1>
_mrssotype = WFREMOTEUSER
<set> MR_CHANGE_PASS(protect)
<ifndef> IBIMR_tid
<if> IBIMR_action EQ "MR_SIGNON"
IBIMR_user = &WF_REMOTE_USER
<endif>
<endif>

If you selected both REMOTE_USER and the Include Windows domain (domain\userid) options, the mrsso.wfs file contents are:

<VER 1>
_mrssotype = REMOTEUSER
<set> MR_CHANGE_PASS(protect)
<ifndef> IBIMR_tid
<if> IBIMR_action EQ "MR_SIGNON"
IBIMR_user = &REMOTE_USER
<endif>
<endif>

If you selected the HTTP header option and entered iv-user for the header, the contents are:

VER 1>
_mrssotype = HTTPHEADER
<set> MR_CHANGE_PASS(protect)
<ifndef> IBIMR_tid
_httpheader=iv-user
_wfsvar=AUTH_ID
<call> CopyHTTPHeaderToWFVar(_httpheader,_wfsvar)
<if> IBIMR_action EQ "MR_SIGNON"
IBIMR_user = &AUTH_ID
<endif>
<endif>

As shown above, the binding of IBIMR_user to REMOTE_USER (or the specified header) is bypassed when WebFOCUS detects an MR Trusted Key sign-on. This logic is required to support Dashboard sign-on processing in an IWA environment and for ReportCaster.

Important: The CopyHTTPHeaderToWFVar( ) function is implemented in the default WebFOCUS Servlet plug-in (WFEXTDefault class). If you need to write your own plug-in functions, you must extend the WFEXTDefault class so that you can still use its methods. For information, see Copying WebFOCUS Variables Using the WebFOCUS Servlet Plug-in.

WebFOCUS