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

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

Adding 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>

Configuring Tivoli Authorization

Open the Tivoli Authorization screen, and configure the following fields:


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 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 Selecting Configuration Values at Runtime.

Access Method:

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 he has the relevant permissions checked in the Access Types listbox.

Tivoli Connection Settings:

You must enter details on how the API Gateway should connect to the Tivoli Access Manager in this section. The API Gateway must have been added to Tivoli as a user for it to connect to the Access Manager. Consult your Tivoli administrator for more information on how to do this.

[Important] Important

You must never allow more than one the API Gateway instance use the same account with the Tivoli server.

  1. In the Username field, enter the username that the API Gateway uses to connect to the Tivoli server. This is the distinguished name of the API Gateway's X.509 certificate. You can use %IP% and %HOSTNAME% to generically represent the IP and hostname of the API Gateway instance. For example, the following entries are both valid:

    cn=PdPermission/%IP%, o=Company, c=ie

    cn=PdPermission/%HOSTNAME%, o=Company, c=ie

    This means that multiple the API Gateway instances, each of which has been set up as a Tivoli user, can share this global setting. For example, one the API Gateway installation with cn= and another with cn=, can both be represented by cn=PdPermission/%IP% in the Tivoli Username. Similarly, an API Gateway instance with cn=VS_1 and another with cn=VS_2 can both be represented by


  2. In the Security Master Password field, enter the master password.

  3. In the Management Server field, enter the IP address or hostname of the Tivoli Management Server.

  4. In the Authorization Server field, enter the IP address or hostname of the Tivoli Authorization Server.

Tivoli Authentication Refresh

At start up, the API Gateway contacts the Tivoli server over SSL, and authenticates using the Security Master password. If you change the Security Master password in the Policy Studio, you must stop and start the API Gateway for this change to be picked up.