Tivoli Integration

Overview
Integration Architecture
Prerequisites
Global Tivoli Configuration
Tivoli Authorization
Tivoli Authentication
Tivoli Attribute Retrieval

Overview

Oracle Enterprise Gateway is a dedicated network device for offloading processor-intensive tasks from applications running in general purpose application servers. The Enterprise Gateway performs application networking by routing traffic based on both content and sender. Its patented high performance XML acceleration engine, coupled with acceleration hardware ensures wirespeed network performance.

Tivoli Access Manager is a commonly used product for securing web resources. The Tivoli message filter allows the Enterprise Gateway to leverage existing Access Manager policies, thus avoiding the need to maintain duplicate policies in both products. At runtime, the Tivoli filters can delegate authentication and authorization decision to Access Manager, and can also retrieve user attributes. Therefore, the Enterprise Gateway integrates with Tivoli Access Manager by providing the following functionality:

Connects to Tivoli Access Manager
Authenticates a user against Access Manager
Authorizes a user against Access Manager
Retrieves user attributes from Access Manager

The Enterprise Gateway has been built to integrate with Tivoli Access Manager 6.0.

Integration Architecture

The Oracle Enterprise Gateway contains a set of message filters that directly or indirectly restrict access to Web Services. For example, filters that directly control access include XML-signature verification, CA certificate chain verification, and SAML assertion verification. With this class of filters, policy decisions are made and enforced within the Enterprise Gateway's core engine itself.

On the other hand, filters that indirectly control access offload the policy decision to an external system, such as Tivoli Access Manager. With indirect filters, the policy decision is made by the external system but then enforced by the Enterprise Gateway.

The objective of this integration solution is to implement a message filter that will forward policy decisions to IBM's Tivoli Policy Director/Access Manager. The architecture can be seen in the following diagram.

Integration Architecture

The following processing stages are executed:

The client sends an XML message to the Enterprise Gateway.
The Enterprise Gateway dispatches the message to the appropriate policy. The filters configured for that policy will then be executed.
Assuming that the Tivoli filter is one of the filters that has been configured for this policy, the Enterprise Gateway asks Tivoli Access Manager to authenticate, authorize, or retrieve attributes for a given user. Tivoli Access Manager makes its security decision and returns it to the Enterprise Gateway, where the decision is enforced.
If Tivoli Access Manager successfully authenticates or authorizes the user, or can retrieve attributes about that user, the message will be routed on to the configured target system. Otherwise, the message will be blocked and a SOAP Fault will be returned to the client.

Prerequisites

IBM Tivoli integration requires the following:

Tivoli API:
IBM Tivoli Access Manager requires the IBM Tivoli Access Manager for e-business Authorization C API.

Enterprise Gateway
When adding third-party binaries to the Enterprise Gateway, you must perform the following steps:

Add the binary files as follows:
- Add .jar files to the InstallDir/ext/lib directory.
- Add .dll files to the InstallDir\win32\lib directory.
- Add .so files to the InstallDir/platform/lib directory.
Restart the Enterprise Gateway.

Policy Studio
When adding third-party binaries to the Policy Studio, you must perform the following steps:

Add .jar files to the InstallDir/plugins/thirdparty.runtime.dependencies_6.0.3 directory.
Restart the Policy Studio.

Tivoli Runtime:
The Tivoli Access Manager Runtime must be installed on the machine running the Enterprise Gateway. Note that the Tivoli Access Manager Runtime for Java is not required. The Tivoli runtime is not packaged with the Oracle product, so the IBM installers need to be run to install the runtime.

Please note that the Tivoli Access Manager Runtime may be installed using the native utilities instead of the Installation Wizard. This is advised so that the IBM Java Runtime 1.4.2 does not get installed. The Java Runtime 1.4.2 is required by the Installation Wizard, but not by any of the runtime software.

Tivoli Configuration Files:
The Enterprise Gateway uses information stored in the Tivoli configuration files in order to connect to a Tivoli server. These configuration files can be generated using the svrsslcfg command line utility, which is shipped with the Tivoli Access Manager Runtime discussed in the previous section. The generated configuration files are then either uploaded to the Enterprise Gateway via Oracle Policy Studio or manually copied into a location on the Enterprise Gateway's file system.

The following example shows how to run the svrsslcfg utility (using Windows file paths):


	svrsslcfg -config -f "C:\conf\config.conf" -d "C:\conf" -n Enterprise Gateway -s remote -P passw0rd -S passw0rd -r 7777 -h test.vordel.com

The following list describes the available arguments:

-config
Create the configuration files required for the Enterprise Gateway to communicate with Tivoli.
-f
The name of the main Tivoli configuration file. This file will be generated by the command.
-d
The name of the directory that is to contain the SSL key file (.kdb) for the server. This command will generate the key file.
-n
The name of the application that is connecting to Tivoli, i.e. the Enterprise Gateway.
-s
The mode in which the application (i.e. the Enterprise Gateway) runs. The most likely scenario will be that the Enterprise Gateway runs remotely.
-P
The administrator's password.
-S
The password for the Enterprise Gateway.
-r
The listening port for the Enterprise Gateway.
-h
The name of the host on which the Enterprise Gateway is running.

After the svrsslcfg utility has been run with the -config option, the following command must be run:


	svrsslcfg -add_replica -f "c:\conf\config.conf" -h tivoli.qa.vordel.com

The following list describes the available arguments:

-add_replica
Add a Tivoli authorization server replica. The Enterprise Gateway contacts this sever to make authorization decisions.
-f
The name of the main Tivoli configuration file. This command adds settings to this file.
-h
The name of the Tivoli authorization server.

Note that the following files will be generated after running these commands:

c:\conf\config.conf - The main Tivoli configuration file.
c:\conf\Enterprise Gateway.kdb - The SSL key file.
c:\conf\Enterprise Gateway.sth - The stash file for the SSL key file.
c:\conf\Enterprise Gateway.conf.obf - The database configuration file.

Please note that depending on the version of the Enterprise Gateway you are running, the above file names may or may not have spaces in them.

Please refer to the Tivoli documentation for more information on running these command line utilities.

Creating a Tivoli Object Space:
An object space, user, and ACL (Access Control List) may be created within Tivoli using the pdadmin command as follows:

 
> login -a sec_master  passw0rd
> objectspace create /vordel/test "For testing purposes" 9
> user create -gsouser jsmith "cn=John Smith, o=Vordel" "John Smith" Smith passw0rd
> user modify jsmith account-valid yes
> acl create VordelACL
> acl modify VordelACL set user jsmith brT
> acl attach /vordel/test VordelACL

The following commands allow you to view the details of the newly added user:


	> user show jsmith > objectspace list > acl show VordelACL

Please refer to the Tivoli documentation for more information on running the pdadmin utility.

Global Tivoli Configuration

Policy Studio is used to configure all Tivoli connections and settings within the Enterprise Gateway. It can be run from the /bin directory of your product installation.

There are 2 global Tivoli-specific settings that can be configured:

Tivoli Connections
Tivoli Repositories

Tivoli Connections:
Tivoli Connections determine how a particular Oracle Process connects to an instance of a Tivoli server. Each Process can connect to a single Tivoli server. This connection can be configured by right-clicking on the Process in the tree on the left hand side of the Policy Studio and clicking the Tivoli menu option.

Alternatively, a global Tivoli Connection can be added by right-clicking on the Tivoli Connection node in the tree and clicking the Add a Tivoli Connection option. The newly added connection can then be assigned to a particular Process.

In both cases, the Tivoli Configuration dialog is used to add the connection details required for the Enterprise Gateway to connect to the Tivoli server. As stated in the Prerequisites section above, the connection details are stored in the Tivoli configuration files that are generated by the svrsslcfg utility. This dialog allows you to upload these files to the Enterprise Gateway.

The Policy Studio can be used to upload the Tivoli configuration files to the machine on which the Enterprise Gateway is running or, alternatively, the configuration files may be copied manually using the tool of your choice onto the Enterprise Gateway's file system. We will now describe how to perform each of these methods in turn.

Complete the following steps to upload a configuration file to the Enterprise Gateway:

Enter a name on the Tivoli Configuration dialog. Note that a previously configured Tivoli Connection can be selected in order to base the new configuration on.
Select the Upload Tivoli configuration files option.
Select the version of the Tivoli server that this connection will connect to. Both Tivoli 5.1 and 6.0 are supported.
Check the Connection enabled checkbox if you want to immediately enable the connection. It can be disabled at a later stage by toggling this checkbox. Click the Next button.
On the Upload Tivoli configuration files screen, click the Load File button and browse to the location of the main Tivoli configuration file. The contents of this file will then be displayed in the text area. Note that any of the details can be edited in the text area at this stage if required.
For example, it may be necessary to change the file locations of the configuration files. This is because when you use the "Upload ..." option, the Enterprise Gateway writes out the files on startup and on server update to the following directory, where PROCESS_NAME is "Enterprise Gateway and INSTALL_DIR refers to the root of your product installation:
[INSTALL_DIR]\conf\plugin\tivoli\[PROCESS_NAME]
Note that spaces are substituted with "-" in the Process name.
In addition, the Enterprise Gateway names each file as config.[EXTENSION]. For example, the directory, [INSTALL_DIR]\conf\plugin\tivoli\Enterprise Gateway will contain config.conf, config.kdb, config.sth and config.conf.obf. The Enterprise Gateway overwrites these files each time at startup or refresh (for example, when configuration updates are deployed). This means that any changes to the main configuration file must be made using the Policy Studio and not directly to the file on disk.
Click the Next button.
Click the Load File button and browse to the location of the Tivoli SSL key file. Once again, the contents of this file will be displayed in the text area. Note that in this case, the (base-64 encoded) SSL keys can not be edited in the text area. Click the Next button.
Click the Load File button and browse to the location of the Tivoli SSL stash file. Click the Next button.
Click the Load File button and browse to the location of the Tivoli Configuration database configuration file. Click the Finish button to upload all the selected files.

Alternatively, the configuration files may be copied manually onto the Enterprise Gateway's file system. Having done this using some out-of-bounds method, complete the following steps to configure the Enterprise Gateway to pick up the uploaded files:

Enter a name on the Tivoli Configuration dialog.
Select the Set file location for main Tivoli Configuration file option and click the Next button. Click the Next button.
Enter the full path to the main Tivoli configuration file on the server's file system in the Server-side Tivoli configuration field. Click the Finish button.
If you have not already manually copied the configuration files on to the Enterprise Gateway's file system you should do so now. Please ensure that the settings contained in the main configuration file that point to other configuration filenames are set correctly. Note that when the Set file location option is selected, the Enterprise Gateway does not overwrite the files at startup or refresh time. You may edit the main configuration file directly using an editor of your choice.

Tivoli Repositories:
A Tivoli Repository is used to authenticate clients against a running instance of a Tivoli server. All authentication filters can pass identity credentials to the Tivoli Repository in order to authenticate clients. The Tivoli server decides whether or not to authenticate the client and the Enterprise Gateway subsequently enforces the decision.

Tivoli Repositories can be configured globally by right clicking on the Tivoli Repositories node in the tree on the Policy Studio and selecting the Add option.

Enter a name for the Repository in the Repository Name field on the Authentication Repository dialog. Select the Finish button to complete the configuration. You may specify Tivoli Connection details from the Repository Configuration screen or via the Settings button. On the Tivoli Configuration dialog, select the Process whose connection details you want to configure, then follow the steps outlined above in the Tivoli Connections section.

When configuring an authentication filter, it will be possible to select this globally configured Tivoli Repository to authenticate clients against. The authentication filter will use the connection details of whatever Process was selected.

Tivoli Authorization

The Tivoli Authorization filter can be found in the Authorization category of filters. To configure this filter, drag and drop it onto the circuit editor and configure the following fields:

Name:
Enter a name for the Tivoli filter here.

Object Space:
The object space represents the resource for which the client must be authorized. Enter the name of the resource in the Object Space field.

You can also enter a property that represents the value of a message attribute. At runtime, the Enterprise Gateway expands the property to current value of the corresponding message attribute.

Properties have the following format:
${message.attribute}
For example, to specify the original path on which the request was received as the resource, enter the following property:
${http.request.uri}

Permissions:
Clients can access a resource with a number of permissions such as read, write, execute, and so on. A client will only be authorized to access the requested resource if he has the relevant permissions checked in the Action Bit table. You can edit existing permissions by clicking the Edit button.

Attributes:
It is possible to specify a list of user attributes to retrieve from the Tivoli server. Individual attributes to be retrieved can be added by clicking the Add button and entering the attribute name in the dialog. If you want all attributes to be retrieved, simply leave the table blank and select the Set attributes for SAML Attribute token option. These attributes can then be made available to the Insert SAML Attribute Assertion filter at a later stage. If you do not require any attribute retrieval, then do not select the Set attributes for SAML Attribute token option.

Note that the permissions for the "primary" action group will be available by default. It is also possible to configure custom action groups and make them available for selection in the filter. The groups created here will reflect custom groups created on the Tivoli server. To create a new group with custom action bits, click the Edit button to display the Tivoli Action Group dialog.

Enter a name for the group in the Name field. Click the Add button to add a new action bit to the group. The Tivoli Action dialog will be displayed. You must enter an Action Bit (e.g. "r") and a Description (e.g. "Read permission") for the new action bit. Click the OK button on the Tivoli Action dialog to return to the Tivoli Action Group dialog.

Add as many action bits as required to your new group before clicking OK on the Tivoli Action Group dialog. The new action bits will then be available for selection in the table on the main filter screen.

Tivoli Configuration Files:
As stated earlier, a Tivoli configuration file that contains all the required connection details is associated with a particular Oracle Process, e.g. "Enterprise Gateway". Click the Settings button to display the Tivoli Configuration dialog.

On the Tivoli Configuration dialog, select the Process whose connection details you want to configure, then follow the steps as outlined above in the Tivoli Connections section.

Note that you do not have to configure the Tivoli Connection for each filter or Authentication Repository. The Settings button is placed on the filter screen as a convenient way to access the Tivoli Connection settings. The Tivoli Connection needs to be configured once per Process.

Tivoli Authentication

It is possible to authenticate clients against a Tivoli Access Manager repository. In this way, the Enterprise Gateway can leverage existing Tivoli security policies without the need to duplicate policies across both products.

The Tivoli repository is available from all authentication filters. However, for demonstration purposes, we will assume that you want to use the HTTP Basic Authentication filter to authenticate a client against a Tivoli Repository using a username and password combination.

Drag the HTTP Basic filter from the Authentication category of filters and drop it onto the circuit editor of the Policy Studio. Complete the following fields:

Name:
Enter a name for the authentication filter here.

Realm:
The Realm entered here will be presented to the client at the same time as they are entering their username and password. The client is then said to be logging into this realm. It is useful in cases where a given user might belong to many different realms, and so, by presenting the realm to the client, he can specify which realm he wants to log into.

Credential Format:
The username presented to the Enterprise Gateway during the HTTP Basic handshake can be of many formats, usually either username or distinguished name. Since the Enterprise Gateway has no way of inherently telling one format from the other (i.e. the client's username could be a DName), it is necessary to specify the format of the credential presented by the client.

Allow Client Challenge:
HTTP Basic Authentication can be configured to work in two ways:

Direct Authentication:
The client sends up the "Authorization" HTTP Basic Authentication header in its first request to the server.
Challenge-Response Handshake:
The client does not send the "Authorization" header when sending its request to the server (i.e. it does not know that the server requires HTTP Basic Authentication). The server responds with a HTTP 401 response code, instructing the client to authenticate to the server by sending up the "Authorization" header. The client then sends up a second request, this time including the "Authorization" header and the relevant username and password.

The first case is used mainly for machine-to-machine transactions in which there is no human intervention. The second case is typical of situations where a browser is talking to a Web Server. When the browser receives the HTTP 401 response to its initial request, it pops up a dialog to allow the user to enter the username and password combination.

If you wish to force clients to always send the HTTP Basic "Authorization" header to the Enterprise Gateway, disable the Allow client challenge checkbox. If, on the other hand, you wish to allow clients to engage in the HTTP Basic Authentication challenge-response handshake with the Enterprise Gateway, make sure this feature is enabled by checking this option.

Remove HTTP Authentication Header:
Select this checkbox to remove the HTTP Authorization header from the downstream message. If this option is left unchecked, the incoming Authorization header will be forwarded onwards to the target system.

Repository Name:
The Repository Name field specifies the name of the Authentication Repository where all User profiles are stored. You can select a previously configured Tivoli repository by simply selecting the name of this repository from the Repository Name dropdown. Alternatively, a new repository can be added by clicking the Add button.

On the Authentication Repository dialog, select "Tivoli Repository" from the Repository Type field, and then enter a name for this type of store in the Repository Name field.

Select the OK button on the Authentication Repository dialog and then Finish button on the HTTP Basic filter to complete the configuration.

Connections to Tivoli authentication repositories can be configured globally by expanding the Authentication Repository Profiles node in the Policy Studio, right-clicking on the Tivoli Repositories node and selecting the Add a New Repository menu option. The globally configured repository will then be available for selection in authentication filters, such as the HTTP Basic authentication filter, as described above.

Tivoli Attribute Retrieval

The Tivoli Attribute Retrieval filter can be used in cases where you would like to retrieve user attributes independently from authorizing the user against Tivoli Access Manager. This filter can be found in the Attributes category of filters. The following fields should be configured:

Name:
Enter a name for the filter in this field.

User ID:
Enter the ID of a user to retrieve attributes for. You can enter this as a static username, Distinguished Name (DName), or property representing a message attribute. 0The property is expanded at runtime to the value of the message attribute.

For example, it is possible to enter ${authentication.subject.id} in this field. This means that the ID of the authenticated user, which is normally a DName, will be used to retrieve attributes for. For this to work correctly, an authentication filter must have been configured to run before this filter in the circuit.

Tivoli Configuration Files:
A Tivoli configuration file that contains all the required connection details is associated with a particular Oracle Process, e.g. "Enterprise Gateway". Click the Settings button to display the Tivoli Configuration dialog.