Legacy Authentication Options

Several Oracle Business Intelligence legacy authentication options are still supported for backward compatibility.

The best practice for upgrading systems is to begin implementing authentication using an identity store and authentication provider as provided by the default security model. An embedded directory server is configured as the default identity store and authentication provider during installation or upgrade and is available for immediate use.

See Introduction to Security in Oracle Business Intelligence and Understanding the Default Security Configuration.

Authentication is the process by which the user name and password presented during login is verified to ensure the user has the necessary credentials to log in to the system. The BI Server authenticates each connection request it receives. The following legacy authentication methods are supported by the BI Server for backward compatibility in this release:

External LDAP-based directory server.
External initialization block authentication.
Table-based.

This section contains the following topics:

Setting Up LDAP Authentication Using Initialization Blocks

You can set up the Oracle BI Server to pass user credentials to an external LDAP server for authentication.

The legacy LDAP authentication method uses Oracle Business Intelligence session variables that you define using the Variable Manager in the Oracle BI Administration Tool. See Using Variables in the Oracle BI Repository in Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

Create an LDAP Server as follows:
1. Select Manage then Identity in the Administration Tool to launch the Identity Manager.
2. Select Directory Servers from the left pane in Identity Manager.
3. Right-click in the right pane in Identity Manager and select New LDAP Server. The LDAP Server dialog is displayed.
4. Create the LDAP server by completing the fields.
Create an LDAP initialization block and associate it with an LDAP server.
Define a system variable named USER and assign the USER variable to an LDAP attribute, for example, uid, sAMAccountName, cn.

Session variables get their values when a user begins a session by logging on. Certain session variables, called system session variables, have special uses. The system session variable USER is used with authentication.
If applicable, delete users from the repository file.
Associate the USER system variable with the LDAP initialization block.

Note:

When using secure LDAP you must restart the Administration Tool before testing if you have done the following: set the key file name and password, tested the LDAP parameter setting successfully in the Administration Tool, and then changed the key file name and password again.

Setting Up an LDAP Server

For instances of Oracle Business Intelligence that use ADSI as the authentication method, the following options should be used when setting up the Active Directory instance:

In Log On To, select All Computers, or if you list some computers, include the Active Directory server as a Logon workstation.
Ensure that User must change password at next logon is not selected.

In the Administration Tool, the CN user used for the BIND DN in the LDAP Server section must have both ldap_bind and ldap_search authority.

Note:

The BI Server uses cleartext passwords in LDAP authentication. Make sure your LDAP Servers are set up to allow this.

Open a repository in the Administration Tool in either offline or online mode.
From Identity Manager, select Action, then New, then LDAP Server.
In the LDAP Server dialog, in the General tab, complete the necessary fields. The following list of options and descriptions contain additional information to help you set up the LDAP server:
- Name. The name to identify this connection (for example, My LDAP).
- Host name. The name of your LDAP server.
- Port number. The default LDAP port is 3060.
- LDAP version. LDAP 2 or LDAP 3 (versions). The default is LDAP 3.
- Base DN. The base distinguished name (DN) identifies the starting point of the authentication search. For example, if you want to search all of the entries under the o=Oracle.com subtree of the directory, o=Oracle.com is the base DN.
- Bind DN and Bind Password. The optional DN and its associated user password that are required to bind to the LDAP server.
  
  If these two entries are blank, anonymous binding is assumed. For security reasons, not all LDAP servers allow anonymous binding.
  
  These fields are optional for LDAP V3, but required for LDAP V2, because LDAP V2 does not support anonymous binding.
  
  These fields are required if you select the ADSI option. If you leave these fields blank, a warning message appears asking if you want to leave the password empty anyway. If you click Yes, anonymous binding is assumed.
- Test Connection. Use this button to verify your parameters by testing the connection to the LDAP server.
Click the Advanced tab, and enter the required information. The BI Server maintains an authentication cache in memory that improves performance when using LDAP to authenticate large numbers of users. Disabling the authentication cache can slow performance when hundreds of sessions are being authenticated.
The following list of fields and descriptions contain additional information to help you set up the LDAP server:
- Connection timeout. When the BI Server attempts to connect to an LDAP server for user authentication, the connection times out after the specified interval.
- Domain identifier (Optional). Typically, the identifier is a single word that uniquely identifies the domain for which the LDAP object is responsible. This is especially useful when you use multiple LDAP objects. If two different users have the same user ID and each is on a different LDAP server, you can designate domain identifiers to differentiate between them. The users log in to the BI Server using the following format:
  
  domain_id/user_name
  
  If a user enters a user name without the domain identifier, then it is authenticated against all available LDAP servers in turn. If there are multiple users with the same name, then only one user can be authenticated.
- ADSI. (Active Directory Service Interfaces) A type of directory server. If you select the ADSIoption, Bind DN and Bind password are required.
- SSL. (Secure Sockets Layer) Select this option to enable SSL.
- User Name Attribute Type. This parameter uniquely identifies a user. In many cases, this is the attribute used in the RDN (relative distinguished name). Typically, you accept the default value. For most LDAP servers, you would use the user ID. For ADSI, use sAMAccountName.

Defining a USER Session Variable for LDAP Authentication

To set up LDAP authentication using initialization blocks, you define a system session variable called USER and associate it with an LDAP initialization block that is associated with an LDAP server.

When a user logs in to the BI Server, the user name and password are passed to the LDAP server for authentication. After the user is authenticated successfully, other session variables for the user could also be populated from information returned by the LDAP server.

Note:

If the user exists in both an external LDAP server using the legacy method and in an LDAP-based identity store based on Oracle Platform Security Services, the user definition in the identity store takes precedence. The legacy LDAP mechanism is only attempted if authentication fails against Oracle Platform Security Services.

The information in this section assumes that an LDAP initialization block has been defined.

For users not defined in an LDAP-based identity store, the presence of the defined system variable USER determines that external authentication is performed. Associating USER with an LDAP initialization block determines that the user is authenticated by LDAP. To provide other forms of authentication, associate the USER variable with an initialization block associated with an external database.

Open a repository in the Administration Tool in either offline or online mode.
Select Manage, then Variables from the Administration Tool menu.
Select Session and Initialization Blocks in the left pane.
Right-click in the right pane and select New Initialization Block.
In the Session Variable - Initialization dialog box, enter Authentication in the Name field.
Click Edit Data Source.
Select LDAP Server from the Data Source Type list.
Browse to select the appropriate LDAP server from the list.
Click OK.
Click Edit Data Target.
Click New.
Enter USER in the Name field.
Click OK.
Click Yes to the warning message about the USER session variable having a special purpose.
Enter in the Mapped Variable field, the LDAP attribute that holds the user ID.
Click OK.
Select the Required for Authentication checkbox.
Click OK.

Setting the Logging Level

Use the system variable LOGLEVEL to set the logging level for users who are authenticated by an LDAP server.

Setting Up External Table Authentication

You can maintain lists of users and their passwords in an external database table and use this table for authentication purposes.

The external database table contains user names and passwords, and could contain other information, including group membership and display names used for Oracle BI Presentation Services users. The table could also contain the names of specific database catalogs or schemas to use for each user when querying data.

Note:

If a user belongs to multiple groups, the group names should be included in the same column, separated by semicolons. This only applies if you are not using row wise variable for groups or roles.

External table authentication uses session variables that you define using the Variable Manager in the Administration Tool. See Using Variables in the Oracle BI Repository in Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

Session variables get their values when a user begins a session by logging on. Certain session variables, called system variables, have special uses. The variable USER is a system variable that is used with external table authentication.

To set up external table authentication, you define a system variable called USER and associate it with an initialization block that is associated with an external database table. Whenever a user logs in, the user ID and password are authenticated using SQL that queries this database table for authentication. The initialization block uses the database connection in the physical layer to connect to the database. The connection in the physical layer contains the log in information. After the user is authenticated successfully, other session variables for the user could also be populated from the results of this SQL query.

The presence of the defined system variable USER determines that external authentication is performed. Associating USER with an external database table initialization block determines that the user is authenticated using the information in this table. To provide other forms of authentication, associate the USER system variable with an initialization block associated with a LDAP server or XML source. See Setting Up LDAP Authentication Using Initialization Blocks.

Import information about the external table into the Physical layer.
Select Manage, then Variables in the Administration Tool to open the Variable Manager.
Select Initialization Blocks in the left pane.
Right-click in the right pane and select New Initialization Block.
In the Initialization Block dialog box, enter a name for the initialization block.
Select Database from the Data Source Connection list.
Click Browse to search for the name of the connection pool this block uses.
In the Initialization String area, enter the SQL statement that is issued at authentication time.
The values returned by the database in the columns in the SQL statement are assigned to variables. The order of the variables and the order of the columns determine which columns are assigned to which variables. Consider the SQL in the following example:
```
SELECT username, grp_name, SalesRep, 2 FROM securitylogons WHERE username = ':USER' and pwd = ':PASSWORD'
```
This SQL contains two constraints in the WHERE clause:
- :USER (note the colon) equals the name the user entered when logging on.
- :PASSWORD (note the colon) equals the password the user entered.
The query returns data only if the user name and password match values found in the specified table.

You should test the SQL statement outside of the BI Server, substituting valid values for :USER and :PASSWORD to verify that a row of data returns.
If this query returns data, then the user is authenticated and session variables are populated. Because this query returns four columns, four session variables are populated. Create these variables (USER, GROUP, DISPLAYNAME, and LOGLEVEL) by clicking New in the Variables tab.

If a variable is not in the desired order, click the variable you want to reorder and use the Up and Down buttons to move it.
Click OK to save the initialization block.

About Oracle BI Delivers and External Initialization Block Authentication

Oracle BI Scheduler Server runs Oracle BI Delivers jobs for users without accessing or storing their passwords.

Using a process called impersonation, Oracle BI Scheduler uses one user name and password with Oracle Business Intelligence administrative privileges that can act on behalf of other users. Oracle BI Scheduler initiates an Agent by logging on to Oracle BI Presentation Services with the Oracle Business Intelligence administrative name and password.

For Delivers to work, all database authentication must be performed in only one connection pool, and that connection pool can only be selected in an initialization block for the USER system session variable. This is typically called the Authentication Initialization Block. When impersonation is used, this initialization block is skipped. All other initialization blocks must use connection pools that do not use database authentication.

Caution:

An authentication initialization block is the only initialization block in which it is acceptable to use a connection pool where :USER and :PASSWORD are passed to a physical database.

For other initialization blocks, SQL statements can use :USER and :PASSWORD. However, because Oracle BI Scheduler Server does not store user passwords, the WHERE clause must be constructed as shown in the following example:

SELECT username, groupname, dbname, schemaname FROM users
WHERE username=':USER' 
NQS_PASSWORD_CLAUSE(and pwd=':PASSWORD')NQS_PASSWORD_CLAUSE

When impersonation is used, everything in the parentheses is extracted from the SQL statement at runtime.

See the Oracle BI Delivers examples in Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

Order of Authentication

The BI Server populates session variables using the initialization blocks in the desired order that are specified by the dependency rules defined in the initialization blocks.

If the server finds the session variable USER, it performs authentication against an LDAP server or an external database table, depending on the configuration of the initialization block with which the USER variable is associated.

Authentication against the identity store configured in Oracle WebLogic Server Administration Console occurs first, and if that fails, then initialization block authentication occurs.

Authenticating by Using a Custom Authenticator Plug-In

You can create a customized authentication module using initialization blocks.

An authenticator is a dynamic link library (DLL), or shared object on UNIX, written by a customer or developer that conforms to the Oracle BI Authenticator API Specification. You can use the authenticator with the BI Server to perform authentication and other tasks at run time. The authentication module is a BI Server module with a cache layer that uses the authenticator and performs related tasks at run time.

You can find sample custom authenticator code in the Oracle BI EE Sample Application downloadable from Oracle Technology Network (OTN).

After you create an authentication object (authenticator plug-in) and specify a set of parameters for the authentication module such as the configuration file path, number of cache entries, and cache expiration time, you must associate the authentication object with an initialization block. You can associate the required USER variable and other variables with the initialization blocks.

When a user logs in, if the authentication is successful, a list of variables is populated as specified in the initialization block.

A custom authenticator is an object in the repository that represents a custom C authenticator plug-in. This object is used with an authentication init block to enable the BI Server component to authenticate users against the custom authenticator. The recommended method for authentication is to use Oracle WebLogic Server's embedded LDAP server. You can continue to use a custom authenticators.

In the Administration Tool, select Manage, then Identity. Select Custom Authenticators from the navigation tree. Select from the following options:
- To create a new custom authenticator: Right-click in the right pane and select New Custom Authenticator.
- To edit a custom authenticator: Double-click the name.
In the Custom Authenticator dialog, complete the necessary fields.
- Authenticator plug-in: The path and name of the plug-in DLL for this custom authenticator.
- Configuration parameters: The parameters that have been explicitly exposed for configuration for this custom authenticator.
- Encrypted parameter: The parameters that have been encrypted, such as passwords for this custom authenticator.
- Cache persistence time: The interval at which the authentication cache entry for a logged on user is refreshed, for this custom authenticator.
- Number of cache entries: The maximum number of entries in the authentication cache for this custom authenticator, preallocated when the Oracle BI Server starts. If the number of users exceeds this limit, cache entries are replaced using the LRU algorithm. If this value is 0, then the authentication cache is disabled.
Click OK.

Managing Session Variables

System session variables obtain their values from initialization blocks and are used to authenticate Oracle Business Intelligence users against external sources such as LDAP servers or database tables.

Every active BI Server session generates session variables and initializes them. Each session variable instance can be initialized to a different value. See Using Variables in the Oracle BI Repository in Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

Managing Server Sessions

The Administration Tool Session Manager is used in online mode to monitor activity.

The Session Manager shows all users logged in to the session, all current query requests for each user, and variables and their values for a selected session. Additionally, an administrative user can disconnect any users and terminate any query requests with the Session Manager.

How often the Session Manager data is refreshed depends on the amount of activity on the system. To refresh the display at any time, click Refresh.

Using the Session Manager

The Session Manager contains an upper pane and a lower pane:

The top pane, the Session pane, shows users currently logged in to the BI Server. To control the update speed, from the Update Speed list, select Normal, High, or Low. Select Pause to keep the display from being refreshed.
The bottom pane contains two tabs:
- The Request tab shows active query requests for the user selected in the Session pane.
- The Variables tab shows variables and their values for a selected session. You can click the column headers to sort the data.

The tables describe the columns in the Session Manager dialog.

Column Name	Description
Client Type	The type of client connected to the server.
Last Active Time	The time stamp of the last activity on the session.
Logon Time	The time stamp that shows when the session initially connected to the BI Server.
Repository	The logical name of the repository to which the session is connected.
Session ID	The unique internal identifier that the BI Server assigns each session when the session is initiated.
User	The name of the user connected.

Column Name	Description
Last Active Time	The time stamp of the last activity on the query.
Request ID	The unique internal identifier that the BI Server assigns each query when the query is initiated.
Session ID	The unique internal identifier that the BI Server assigns each session when the session is initiated.
Start Time	The time of the individual query request.

See Using Variables in the Oracle BI Repositoryin Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

In the Administration Tool, open a repository in online mode and select Manage then Sessions.
Select a session and click the Variables tab.
To refresh the view, click Refresh.
To close Session Manager, click Close.

Follow these steps to disconnect a user from a session.

In the Administration Tool, open a repository in online mode and select Manage then Sessions.
Select the user in the Session Manager top pane.
Click Disconnect.

The user session receives a message that indicates that the session was terminated by an administrative user. Any currently running queries are immediately terminated, and any outstanding queries to underlying databases are canceled.
To close the Session Manager, click Close.

Follow these steps to terminate an active query.

In the Administration Tool, open a repository in online mode and select Manage then Sessions.
Select the user session that initiated the query in the top pane of the Session Manager.

After the user is highlighted, any active query requests from that user are displayed in the bottom pane.
Select the request that you want to terminate.
Click Kill Request to terminate the selected request.

The user receives a message indicating that the query was terminated by an administrative user. The query is immediately terminated, and any outstanding queries to underlying databases are canceled.

Repeat this process to terminate any other requests.
To close the Session Manager, click Close.