Tivoli authorization


Tivoli Access Manager provides authentication and access control services for web resources. It also stores policies describing the access rights of users.

The API Gateway can integrate with this product through the Tivoli connector. The API Gateway Tivoli connector can query Tivoli for authorization information for a particular user on a given resource. In other words, the API Gateway asks Tivoli to make the authorization decision. If the user has been given authorization rights to the web service, the request is allowed through to the service. Otherwise, the request is rejected.

For details on prerequisites for integration with IBM Tivoli, see the Tivoli integration topic.

Add a Tivoli client

To add the machine running the API Gateway as a client of Tivoli, perform the following steps:

  1. Open a terminal window on the machine running the Tivoli authorization server and management server.

  2. Start the pdadmin tool using the following command, where oracle is the password for the management server:

    C:\WINNT> pdadmin -a sec_master -p oracle

    This starts the pdadmin terminal tool.

  3. Use the user create command to add a user. The parameters are as follows:

    pdadmin> user create <username> <dn> <cn> <sn> <password>

    The following is an example where the API Gateway is running on a machine called TEST_CLIENT with an IP address of

    pdadmin> user create TEST_CLIENT cn=PdPermission/,o=Company,c=ie \ 
    PdPermission/ PdPermission myPass1234

    Make sure the DName you assign the user is exactly identical to the DName in your user's certificate. This includes case and attribute order. Also make sure that you put the IP address or hostname in the CN.

  4. Next you must activate the account for the new user. Use the following command:

    pdadmin> user modify TEST_CLIENT account-valid yes

  5. Finally, the user must be included in the remote access control list (ACL) client list:

    pdadmin> group modify remote-acl-users add batman

    The machine running the API Gateway has now been added as a client to Tivoli.

Add users and web services to Tivoli

To authorize a user to access a web service, you must first add the user to Tivoli as follows:

  1. Add the user as before using the user create command as follows:

    pdadmin> user create <username> <dn> <cn> <sn> <password>

    Ensure that the DN you assign the user is identical to the DName in the user's certificate.

  2. Next, you must insert the server that runs your web service into Tivoli's object space. Use the following command to do this:

    pdadmin> object create /API Gateway/<object-name> <description> 9

    [Note] Note

    The 9 parameter indicates that you are adding a web resource. In addition, it is the responsibility of the Policy Decision Point (API Gateway) to map an attempt to access a web service to a given object. The Tivoli authorization server does not contain any mapping between its object space nodes and URLs.

  3. Finally, you must create a binding between the user and the object by creating an ACL for the object, and adding the user to that list:

    pdadmin> acl create <acl-name>
    pdadmin> acl modify <acl-name> set user <username> rx
    pdadmin> acl attach <object-name> <acl-name>


Configure the following fields on the Tivoli Authorization window:


Enter an appropriate name for the filter.

Object Space:

The object space represents the resource for which the client must be authorized. Enter the name of the resources in the Object Space field. You can also enter selectors that represent the values of message attributes. At runtime, the API Gateway expands the selector to the current value of the corresponding message attribute.

Selectors have the following format:


For example, to specify the original path on which the request was received by the API Gateway as the resource, enter the following selector:


For more details on selectors, see Select configuration values at runtime.


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


You can specify a list of user attributes to retrieve from the Tivoli server. You can add 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, 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, do not select the Set attributes for SAML Attribute token option.

[Note] Note

The permissions for the primary action group are available by default. You can also configure custom action groups and make them available for selection in the filter. The groups created here 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 is displayed. You must enter an Action Bit (for example, r) and a Description (for example, 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 are then available for selection in the table on the main filter window.

Tivoli Configuration Files:

A Tivoli configuration file that contains all the required connection details is associated with a particular Oracle API Gateway instance. Click the Settings button to display the Tivoli Configuration dialog.

On the Tivoli Configuration dialog, select the API Gateway instance whose connection details you want to configure, then follow the steps as outlined in the Tivoli integration topic.