Contents
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.
To add the machine running the API Gateway as a client of Tivoli, perform the following steps:
-
Open a terminal window on the machine running the Tivoli Authorization Server and Management Server.
-
Start the
pdadmin
tool using the following command, whereoracle
is the password for the Management Server:C:\WINNT> pdadmin -a sec_master -p oracle
This starts the
pdadmin
terminal tool. -
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 of192.168.0.100
:pdadmin> user create TEST_CLIENT cn=PdPermission/192.168.0.100,o=Company,c=ie \ PdPermission/192.168.0.100 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.
-
Next you must activate the account for the new user. Use the following command:
pdadmin> user modify TEST_CLIENT account-valid yes
-
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.
To authorize a user to access a Web service, you must first add the user to Tivoli as follows:
-
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.
-
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 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. -
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>
Open the Tivoli Authorization screen, 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 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:
${message.attribute}
For example, to specify the original path on which the request was received by the API Gateway as the resource, enter the following selector:
${http.request.uri}
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 |
---|---|
You must never allow more than one the API Gateway instance use the same account with the Tivoli server. |
-
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=10.10.10.10
and another withcn=20.20.20.20
, can both be represented bycn=PdPermission/%IP%
in the Tivoli Username. Similarly, an API Gateway instance withcn=VS_1
and another withcn=VS_2
can both be represented bycn=PdPermission/%HOSTNAME%
. -
In the Security Master Password field, enter the master password.
-
In the Management Server field, enter the IP address or hostname of the Tivoli Management Server.
-
In the Authorization Server field, enter the IP address or hostname of the Tivoli Authorization Server.