Oracle® Fusion Middleware
Part 6. General configuration

Oracle API Gateway is a dedicated network device for offloading processor-intensive tasks from applications running in general purpose application servers. The API 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 API 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 API Gateway integrates with Tivoli Access Manager by providing the following functionality:

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

The Oracle API 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 API 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 API Gateway.

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

The following processing stages are executed:

IBM Tivoli integration requires the following:

Install Tivoli runtime

The Tivoli Access Manager runtime must be installed on the machine running the API Gateway.

	Note
	The Tivoli Access Manager runtime for Java is not required. The Tivoli runtime is not packaged with the API Gateway product, so the IBM installers need to run to install the runtime.

The Tivoli Access Manager runtime can 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 API 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 API Gateway using Oracle Policy Studio or manually copied into a location on the API 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 API Gateway 
-s remote -P passw0rd -S passw0rd -r 7777 -h test.vordel.com

The available arguments are described as follows:

Argument	Description
-config	Creates the configuration files required for the API Gateway to communicate with Tivoli.
-f	Name of the main Tivoli configuration file. This file is generated by the command.
-d	Name of the directory that is to contain the SSL key file (.kdb) for the server. This command generates the key file.
-n	Name of the application connecting to Tivoli (the API Gateway).
-s	Mode in which the application (the API Gateway) runs. The most likely scenario is that the API Gateway runs remotely.
-P	Administrator's password.
-S	Password for the API Gateway.
-r	Listening port for the API Gateway..
-h	Name of the host on which the API 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 available arguments are described as follows:

Argument	Description
-add_replica	Adds a Tivoli authorization server replica. The API Gateway contacts this server to make authorization decisions.
-f	Name of the main Tivoli configuration file. This file is generated by the command.
-h	name of the Tivoli authorization server.

The following files are generated after running these commands:

• c:\conf\config.conf - The main Tivoli configuration file.

• c:\conf\API Gateway.kdb - The SSL key file.

• c:\conf\API Gateway.sth - The stash file for the SSL key file.

• c:\conf\API Gateway.conf.obf - The database configuration file.

	Note
	Depending on the version of the API Gateway you are running, the above file names might have spaces in them.

See the Tivoli documentation for more information on running these command line utilities.

> 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

> user show jsmith
> objectspace list
> acl show VordelACL

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

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

The Tivoli authorization filter can be found in the Authorization category of filters. To configure this filter, see the Tivoli authorization topic.

It is possible to authenticate clients against a Tivoli Access Manager repository. In this way, the API 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, assume that you want to use the HTTP basic authentication filter to authenticate a client against a Tivoli repository using a user name and password combination.

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

Name:

Enter a name for the authentication filter.

Realm:

The Realm entered here is presented to the client at the same time as they are entering their user name 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 user name presented to the API Gateway during the HTTP basic handshake can be of many formats, usually either user name or distinguished name. Since the API Gateway has no way of inherently telling one format from the other (the client's user name 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:

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 user name and password combination.

If you wish to force clients to always send the HTTP basic Authorization header to the API Gateway, disable the Allow client challenge check box. If, on the other hand, you wish to allow clients to engage in the HTTP basic authentication challenge-response handshake with the API Gateway, make sure this feature is enabled by checking this option.

Remove HTTP Authentication Header:

Select this check box to remove the HTTP Authorization header from the downstream message. If this option is left unchecked, the incoming Authorization header is 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 list. 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 is then available for selection in authentication filters, such as the HTTP basic authentication filter, as described above.

The Retrieve from Tivoli 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. To configure this filter, see the Retrieve attribute from Tivoli topic.