Configuring External Authentication

In this section:

This section describes how to configure Managed Reporting to gather user credentials and pass them to an external source for authentication. Supported external sources include:

For information about how to develop a custom authentication solution for Managed Reporting, see Developing a Managed Reporting Realm Driver Extension.

Note: When using the MR to WebFOCUS Reporting Server authentication option, your session may time out prematurely because the credentials being maintained for you are lost when your JSESSIONID cookie expires. This may occur as soon as 30 minutes.


Top of page

x
Configuring External Authentication Properties

How to:

Once you have decided which type of authentication to use and before you can enable external authentication, you must configure the properties that enable Managed Reporting to communicate with the external directory.

You can configure these authentication properties in the WebFOCUS Administration console by going 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 clicking the WebFOCUS Administration Console link.

Log on to the WebFOCUS Administration Console as an administrator (default ID is admin with no password). Click Configuration and click External Directories in MR Security Settings.

 MR Security Settings in WebFOCUS Admin Console

To configure properties for a specific external directory, double-click the prefix for that directory, which opens the Modify Settings window. Alternatively, select the radio button in front of the directory prefix and click the Modify button at the bottom of the screen. The built-in directories that are described in this section are listed in the following table.

Directory

Prefix

Active Directory

AD

LDAP

LDAP

WebFOCUS Reporting Server

WFRS

Note:

Now you can configure the appropriate authentication properties as described in the following sections.



x
Procedure: How to Configure WebFOCUS Reporting Server Authentication Properties

Configure these settings if you selected the WFRS directory prefix and clicked the Modify button:

  1. Update the hostname:port placeholder with the appropriate values.

    Directory Configuration diagram

    • If the server is on MVS, supply the appropriate service name after the SERVER= keyword.
    • If the server is on IBM UNIX System Services (USS), you need to append a code page setting to the URL as follows:
      jdbc:eda://hostname:port;SERVER=servername;code_page=437
  2. Click Save.

    If your WebFOCUS Reporting Server is configured for operating system security, you must start the Reporting Server in SECURITY ON mode. However, if your Reporting Server is configured for LDAP or DBMS security, you must start it in the appropriate security mode. For information about configuring the Reporting Server for these security modes, see Chapter 2, Server Security, in the Server Administration for UNIX, Windows, OpenVMS, IBM i, and z/OS manual.

    When using this option, the Reporting Server credentials of each user are preserved in their individual session object on the Web-tier. By default, this session expires after 30 minutes of inactivity, resulting in a subsequent prompt for the Reporting Server credentials. You can extend the timeout period by editing the <session-timeout> attribute found in the WebFOCUS Web application deployment descriptor (web.xml).

    Note: If the prefix you are saving is named under Current Settings on the MR Security Settings - Directory Configuration panel, you will be prompted to reload the repository driver. Click OK.

    To understand what happens when you configure these settings, see Internal Processing for Reporting Server Authentication.

For more information, see the online help in the IBI_EDACONNECTOR setting.

Now that you have configured your authentication properties, you can enable external authentication using this prefix. To do so, remain logged on to the WebFOCUS Administration Console and follow the instructions in How to Enable External Authentication.



x
Procedure: How to Configure LDAP and Active Directory Authentication Properties

Configure these settings if you selected the LDAP or AD directory prefix and clicked the Modify button.

The WebFOCUS Administration Console places the following properties in mrrealm.cfg when you choose Active Directory or LDAP for authentication.

  1. Edit the following properties to configure LDAP or Active Directory authentication:
    MANAGER.CLASS

    Is set to ibi.uas.service.WFMRX_LdapSecurityManager when you select LDAP or Active Directory as your authentication directory. This property cannot be edited.

    REPOSITORY_MANAGER.CLASS

    Is set ibi.uas.service.WFMRX_LdapRepositoryManager when you select LDAP or Active Directory as your authentication directory. This property cannot be edited.

    HOST

    Is the host name or IP address of your directory server and port on which the directory server listens. For example, server1:389. If you are authenticating to Active Directory, you should consider specifying the host that runs your Global Catalog, which is configured on port 3268 by default. You must specify the Global Catalog host/port when your users are in more than one domain. You can also specify multiple servers for failover support using a comma-delimited format. For example, server1:3169,server2:4310.

    SECURECONNECTION

    Determines whether the connection is encrypted. A value of false means no encryption. A value of true means SSL encryption is used. Typically, SSL requires additional setup on the directory server (for example, a certificate). For more information, see your directory server documentation. You may also need to register the SSL certificate in your directory with the JVM running your application server, especially if it is a self-signed or expired certificate.

    For more information, see WebFOCUS Encryption Features.

    REQUIRECREDENTIALS

    Specifies whether to perform an anonymous or credential-based search for the user in the directory as a preliminary step in authenticating the user. The default value for LDAP is false, and the default value for Active Directory is true.

    For example, a user John Doe enters the user ID JD123 and his password on the Business Intelligence Dashboard logon page.

    If REQUIRECREDENTIALS=false, the Realm Driver first performs an anonymous search to locate the distinguished name (DN) of John Doe. For example, "cn=Doe\, John,ou=People,dc=informationbuilders,dc=com". Next, the Realm Driver performs an LDAP bind with the DN and password of the user in order to authenticate him.

    If REQUIRECREDENTIALS=true, the first connection is made with a DN with sufficient rights to search the directory and locate user entries of a service account.

    Note: Active Directory does not allow an anonymous search.

    SECURITY.PRINCIPAL

    Contains the DN of a service account with sufficient access rights to locate user entries in the directory. This value is used only when REQUIRECREDENTIALS=true.

    SECURITY.CREDENTIALS

    Contains the password of the service account. This value is used only when REQUIRECREDENTIALS=true.

    USER.BASE

    Specifies the root DN where the user search starts. For performance reasons you should set this value as close as possible to your user entries. The default value for LDAP is ou=People,dc=domain,dc=com, and for Active Directory is cn=Users,dc=domain,dc=com. You must replace this with an appropriate DN for your directory.

    USER.SCOPE

    Specifies the scope of the search. Valid values are:

    subtree indicates that the scope is a subtree rooted at the start node. This is the default value.

    onelevel indicates the immediate children of the start node only.

    USER.CLASS

    Specifies the object class used when searching for user entries. The default value for LDAP is inetOrgPerson, and for Active Directory it is User.

    USER.ATTRIBUTE

    Specifies the LDAP attribute used when searching for user entries. The default value for LDAP is uid, and sAMAccountName is the default value for Active Directory.

    One possible reason to change the default value would be to allow users to log on to Managed Reporting with an e-mail address instead of user ID. In this case, you might change the value to mail (if this corresponds with the name of the appropriate attribute in your directory).

    You may also want to change this when your Active Directory includes several child domains. In this case, there can be two people with the same ID. You can change the property to userPrincipalName so that users are required to present their ID to Managed Reporting in a domain-qualified (for example, jt01234@ibi.com) format.

  2. After editing the properties, click Save to save the values or Cancel to leave them as they were before.

    Note: If the prefix you are saving is named under Current Settings on the MR Security Settings - Directory Configuration panel, you will be prompted to reload the repository driver. Click OK.

Now that you have configured your authentication properties, you can enable external authentication using this prefix. To do so, remain logged on to the WebFOCUS Administration Console and follow the instructions in How to Enable External Authentication.



x
Procedure: How to Configure LDAP and Active Directory Connection Pooling Properties

Optionally configure these settings if you selected the LDAP or AD directory prefix and you want to take advantage of LDAP connection pooling. Your servlet container must use Sun Java 1.4.1 or higher. For more information on these settings, refer to the Sun Java documentation.

POOL.ENABLE

To enable the connection pool feature, set this property to true and adjust the other POOL properties as desired. The default value is false.

POOL.PROTOCOL

Defines which types of connections are taken from the pool. The default value is plain, which means that only non-SSL connections are drawn from the pool. You can change this to ssl or to plain ssl to alter the behavior.

POOL.INITSIZE

Defines the initial size of the connection pool. The default value is 1.

POOL.MAXSIZE

Defines the maximum size of the connection pool. The default value is 0, which means no limit. If the limit is reached, the Realm Driver waits for the period specified by POOL.TIMEOUT and then returns an error.

POOL.PREFSIZE

Defines the preferred size of the connection pool. When specified, connections are added and idle connections are removed to achieve value specified. The default value is 0, which means no preferred size.

POOL.TIMEOUT

Defines how long in milliseconds the Realm Driver waits for a connection from the pool. This is initially set to a value of 60000 in the configuration file (one minute). A value of 0 means no timeout.



x
Procedure: How to Create a Copy of Your Directory Settings
  1. When you open the properties window for a directory prefix, you can supply a different value in the Directory Prefix field. For example, if you selected WFRS, you can create a new prefix, such as WFRSTEST.

    Directory Configuration diagram

    In this case, the Save button becomes the Save As button.

  2. Click the Save As button to make a copy of the directory settings under the new directory prefix.

Top of page

x
Enabling External Authentication

How to:

After completing the appropriate tasks described in Preparing for Trusted or External Authentication and configuring the appropriate authentication properties, you can enable external authentication.



x
Procedure: How to Enable External Authentication
  1. Click General under MR Security Settings in the Configuration block of the WebFOCUS Administration Console.
  2. Select the External Directory radio button and then choose the prefix for the external directory that will perform authentication.

    MR Security Settings diagram

  3. Click Save. You will be asked whether to reload the repository driver at this time.

    Reload repository pop up image

  4. Click OK to process your changes.

Note: If you are using ServletExec and you are configuring either LDAP or Active Directory authentication, you must add the five JAR files found in WebFOCUS77/utilities/ldap to your WebFOCUS77 Web application WEB-INF/lib directory (or to the ServletExec classpath). Other application servers generally include these libraries by default.


Top of page

x
Internal Processing for External Authentication

Reference:



x
Reference: Internal Processing for Active Directory or LDAP Authentication

When you save your settings, 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 following settings are made in the mrrealm.cfg file:

    For Active Directory:

    AUTHENTICATION.PREFIX=AD
    AUTHENTICATION.MODE=EXTERNAL
    AUTHORIZATION.MODE=INTERNAL
    AD.MANAGER.CLASS= ibi.uas.service.WFMRX_LdapSecurityManager
    AD.REPOSITORY_MANAGER.CLASS=
                   ibi.uas.service.WFMRX_LdapRepositoryManager

    The additional properties you configured in the WebFOCUS Administration Console are not shown here but are added to the mrrealm.cfg file with the AD prefix prepended.

    For LDAP:

    AUTHENTICATION.PREFIX=LDAP
    AUTHENTICATION.MODE=EXTERNAL
    AUTHORIZATION.MODE=INTERNAL
    LDAP.MANAGER.CLASS= ibi.uas.service.WFMRX_LdapSecurityManager
    LDAP.REPOSITORY_MANAGER.CLASS=
                   ibi.uas.service.WFMRX_LdapRepositoryManager

    The additional properties you configured in the WebFOCUS Administration Console are not shown here but are added to the mrrealm.cfg file with the LDAP prefix prepended.

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



x
Reference: Internal Processing for Reporting Server Authentication

The primary advantage of Reporting Server authentication is that your Managed Reporting credentials are persisted and are automatically propagated to the Reporting Server on subsequent report requests.

When you save your settings, 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 following settings are made in the mrrealm.cfg file, where hostname:port reflect what you supplied in the console:
    AUTHENTICATION.PREFIX=WFRS
    AUTHENTICATION.MODE=EXTERNAL
    AUTHORIZATION.MODE=INTERNAL
    WFRS.MANAGER.CLASS=ibi.uas.service.WFMRX_DBSecurityManager
    WFRS.DRIVER.CLASS=ibi.jlink.EdaDriver
    WFRS.DRIVER.URL=jdbc:eda://hostname:port;SERVER=
  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 options, as explained below.
  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 WebFOCUS77/client/wfc/etc directory. The script commands inside this file instruct WebFOCUS to store the credentials supplied by the user during sign-on in the user session on the Web-tier. These credentials are then retrieved from the session and sent to the Reporting Server with subsequent report requests.

Note: The mrsso.wfs file is maintained by the WebFOCUS Administration Console. If you manually edit this file, any changes you make to it will be lost the next time the console writes the file.

Important: This authentication option makes use of functions in the default WebFOCUS Servlet plug-in (WFEXTDefault class) that is configured automatically. If you need to write your own plug-in functions, you should extend the class for the existing plug-in so that you can still use its methods. For more information, see Copying WebFOCUS Variables Using the WebFOCUS Servlet Plug-in.

The contents of the mrsso.wfs file are:

<VER 1>
_mrssotype = WFRS
<set> MR_CHANGE_PASS(protect)
<if> IBIMR_action EQ "MR_SIGNON"
httpsession=_ibuser
<call> CopyWFVarToSessionVar(IBIMR_user,httpsession)
httpsession=_ibpass
<call> CopyWFVarToSessionVar(IBIMR_pass,httpsession)
<endif>
# Use stored credentials for all server connections.
<if> IBIMR_action NE "MR_SIGNON"
wfvar=IBI_REPORT_USER
httpsession=_ibuser
<call> CopySessionVarToWFVar(httpsession,wfvar)
wfvar=IBI_REPORT_PASS
httpsession=_ibpass
<call> CopySessionVarToWFVar(httpsession,wfvar)
<endif>

Managed Reporting performs authentication in this option but relies on the Reporting Server to validate the credentials. It is important to note that these credentials may be validated by the Reporting Server operating system (this includes Active Directory when the Reporting Server is installed on a machine running Windows), an LDAP server, or a number of RDBMS platforms, depending on the Reporting Server security configuration. You must ensure that Reporting Server security is not disabled or set to PTH mode since no authentication takes place in those cases. For more information about Reporting Server security options, see WebFOCUS Reporting Server Security.


Top of page

x
Using Developer Studio

When using Developer Studio with an environment in which Managed Reporting is configured for external authentication, you should enter your credentials in the Managed Reporting / ReportCaster Credentials fields as shown below.

Image of where to enter credentials


Top of page

x
User ID Case

Managed Reporting treats user IDs as case-insensitive, which means that two user IDs cannot exist that differ only by their case (such as jt01234 and JT01234). Most security systems have a similar behavior, but not all. For example, UNIX systems treat the user ID as case-sensitive.

The setting USERID.CASE, configurable from the Advanced panel under MR Security Settings in the Configuration block of the WebFOCUS Administration Console, controls:

The setting USERID.CASE has three possible values. When set to Lower, the default, the user ID typed by the administrator in the MR Administration interface or supplied by the user on the sign-on page is down cased prior to processing. When set to Upper, the value is upper cased prior to processing. When set to Default, the value is processed as specified.


WebFOCUS