TAM adapter
The TAM-adapter allows to communicate with IBM Security Access Manager for e-business through the ISAM-administration API. Only a subset of the administrative tasks exposed by the ISAM-Administration API are made available by TrustBuilder:
Create User
Delete User
Modify User
Merge User
Import User
Create Group
Delete Group
Set Password
Change Password
Authenticate
IV Credentials
Create GSO
Update GSO
Delete GSO
Prerequisites
Setup secure Connection with IBM Security Access Manager
A secure connection must be setup in order to communicatie with the ISAM Policy Server, see the Setup Secure Connection with Tivoli Access Manager chapter The ISAM Java runtime will only work on an IBM Java JDK/JRE
Configuration
AdapterUniqueID
Unique name assigned to this adapter; the name is used to reference the adapter in the workflow. The ID has following requirements:
START with a letter or _ (underscore)
FOLLOWED by a combination of following characters: Letter, Number, '.' (dot), '-' (dash), '_' (underscore)
AdminUserID The userID to used to connect to pdadmin (eg. sec_master)
AdminPassword The password of the Admin user, this is automatic encrypted when saving (eg. some_password)
TamConfigUrl Path and file name of the configuration file used to connect to the TAM server. (eg. /opt/IBM/WAS8/java/jre/PolicyDirector/pdtb.conf)
ConnectionPoolSize The size of the pool that should be used to make authenticate requests (default 10). We should note that IBM does not recommend pooling the PDAuthorizationContext, which is what we do here. If you want to disable the pool, set the ConnectionPoolSize to 0. You can still configure the number of connections that PDAuthorizationContext can use by specifying the PDMAXCONNECTIONS java system property.
Workflow Settings
A request for the adapter is prepared by specifying the following properties/scripts in the adapter activity:
Input Property: the variable containing the instructions the adapter have to execute
Output Property: the variable the adapter will store the response in after execution
Before Adapter Script: script that will be executed before calling the adapter
After Adapter Script: script that will be executed after the adapter fulfilled its task
Request - API
Create User
Creates a user in the Policy Directory Management Server (PDMS). The description provided in the request is not added in the initial creation of the user.
var tr = tamCreateUserRequest( dnUser, nameFirst, nameLast, usernameTam, password);
tr.setAccountValid(true); // make account valid
tr.setPasswordValid(true); // make password valid
tr.setSSOUser(true); // Make the user an ssoUser
tr.setDescription("my description"); // Set a description
tr.addUserGroup("newUsers"); // add user to a group
tr.setPasswordPolicy(true); // enable password policy
Delete User
Deletes the user from the PDMS and also the user registry (LDAP if used)
tamDeleteUserRequest( username)
Modify User
Modifies the user. If a user is a member of any groups before the request is made and if the groups are not listed in the request then the user's membership of these groups is removed.
var tr = tamModifyUserRequest( usernameTam);
tr.setAccountValid(true); // make account valid
tr.setPasswordValid(true); // make password valid
tr.setSSOUser(true); // Make the user an ssoUser
tr.setDescription("my description"); // Set a description
tr.addUserGroup("newUsers"); // add user to a group
tr.setPasswordPolicy(true); // enable password policy
Merge User
If a user with the provided ISAM username in the request does not exist in the PDMS then a new user is created, if the user already exists then the user is modified.
tamMergeUserRequest( usernameTam, password, userDN)
Parameters:
usernameTam Non-null, non-empty String.
password Non-null, non-empty String.
userDN Non-null, non-empty String.
Import User
Available in version 6.0.2 and up If a user exists in the ldap database but is not a Isam user you can import the user.
var tr = tamImportUserRequest( dnUser, nameFirst, nameLast, usernameTam, groupName, ssoUser);
tr.setAccountValid(true); // make account valid
tr.setPasswordValid(true); // make password valid
tr.setSSOUser(true); // Make the user an ssoUser
tr.setDescription("my description"); // Set a description
tr.addUserGroup("newUsers"); // add user to a group
tr.setPasswordPolicy(true); // enable password policy
Parameters:
dnUser Non-null, non-empty String.
nameFirst Non-null, non-empty String.
nameFirst Non-null, non-empty String.
usernameTam Non-null, non-empty String.
groupName Non-null, non-empty String.
ssoUser true/false
Create Group
If the group does not already exist a new group is created in the PDMS and the user registry.
tamCreateGroupRequest( groupName, groupDN, groupContainer)
Delete Group
Deletes a group from the PDMS and optionally from the user registry.
tamDeleteGroupRequest( groupNameTam, registryDelete)
Set Password
Changes the password of the user and sets the password valid flag to true. No check is made against the original password first.
tamSetPasswordRequest( username, newPassword)
Change Password
Same as the set password functionality but the current password, provided in the request, is checked before the change is made. If the current password in the registry does not match the old password provided then the password is not changed.
tamChangePasswordRequest( username, oldPassword, newPassword)
Parameters:
username Non-null, non-empty string.
oldPassword Non-null, non-empty string.
newPassword Non-null, non-empty string.
About changing passwords
The changePasswordRequest isn't updating the password valid flag within IBM Tivoli Access Manager. This way its possible you that you change a password of a user and he is still locked out. The setPasswordRequest however is setting this flag to valid. Note that for setPasswordRequest you don't have to give the old password and this can lead to a security risk. Make sure you check first the password with a tamAuthenticateRequest before setting a new one with setPasswordRequest.
Authenticate
Performs an authentication to the ISAM server if successful the DN of the user is returned.
tamAuthenticateRequest( username, password)
Parameters:
username Non-null, non-empty string.
password Non-null, non-empty string.
Example : request example
workItem.request = tb.tamAuthenticateRequest(user,password);
Gives as result
TamResponse (
status = 0, substatus = 200
User DN = cn=user,o=example,c=org
UUID = e6dc8286-8d13-11e1-9b47-000c29c4fbe9
)
Create GSO
Creates a GSO object for a tam user. The Policy Manager needs to be online for this
tamCreateSSOCred(resourceName, resourceType, tamUser, resourceUser, resourcePassword)
Parameters:
resourceName Non-null, non-empty string.
resourceType Non-null, non-empty string.
tamUser Non-null, non-empty string.
resourceUser Non-null, non-empty string.
resourcePassword Non-null, non-empty string.
Update GSO
updates an existing GSO object for a tam user.
tamSetSSOCred(resourceName, resourceType, tamUser, resourceUser, resourcePassword)
Parameters:
resourceName Non-null, non-empty string.
resourceType Non-null, non-empty string.
tamUser Non-null, non-empty string.
resourceUser Non-null, non-empty string.
resourcePassword Non-null, non-empty string.
Delete GSO
Deletes an GSO object for a tam user.
tamDeleteSSOCred(resourceName, resourceType, tamUser)
Parameters:
resourceName Non-null, non-empty string.
resourceType Non-null, non-empty string.
tamUser Non-null, non-empty string.
IV Credentials
Allows for the creation or manipulation of a Prinicple's ISAM PAC being the representation of the credentials for use with WebSeal.
tamIVCredsRequest( options)
Parameters:
options Options object, containing properties
username If credentials not supplied
credentials If usernameTam not supplied
domain Can be null or empty
groups list of groups to add
attributes list of string arrays (key,value) to add
returnAttributes boolean to return attributes (eg. [ ['name','koen'],['a',1]] )
Example :
tamIVCredsRequest
function createTAMIVCredsUserRequest(workItem) {
var attributes = [];
attributes.push(["AUTHENTICATION_LEVEL", workItem.authLevel]);
var tamrequest = { username : workItem.username, // username string
groups : workItem.groups // Array of groups,
attributes : attributes // Attributes array as key value}
workItem.request = tb.tamIVCredsRequest(tamrequest);
}
Response :
TamResponse (
status = 0, substatus = 200
Credential PAC File = BAKs3DCCAZoMADCCAZQwggGQAgIHADArMCcwHgIE5tyChgIDAI0TAgIR4QICAJsCAUcEBgAMKcT7
6QwFZXdvbGQwAAIBATCCAVgwggFUMCQMEkFaTl9DUkVEX0FVVEhaTl9JRDAOMAwCAQQMBWV3b2xk
BAAwKQwQQVpOX0NSRURfTUVDSF9JRDAVMBMCAQQMDElWX0xEQVBfVjMuMAQAMC0MGUFaTl9DUkVE
X1BSSU5DSVBBTF9ET01BSU4wEDAOAgEEDAdEZWZhdWx0BAAwKQwXQVpOX0NSRURfUFJJTkNJUEFM
X05BTUUwDjAMAgEEDAVld29sZAQAMEgMF0FaTl9DUkVEX1BSSU5DSVBBTF9VVUlEMC0wKwIBBAwk
ZTZkYzgyODYtOGQxMy0xMWUxLTliNDctMDAwYzI5YzRmYmU5BAAwNAwUQVpOX0NSRURfUkVHSVNU
UllfSUQwHDAaAgEEDBNjbj1ld29sZCxvPXNpdCxjPWJlBAAwJwwQQVpOX0NSRURfVkVSU0lPTjAT
MBECAQQMCjB4MDAwMDA3MDAEAA==
)
Response - API
Common Properties
The response API can be applied to the variable specified in the "output property" (see "Workflow Settings"): to verify whether the action performed by the adapter was successful, to query for the data returned by the adapter.
All responses have four properties in common:
status Status flag indicating whether the response is ok (0) or not (1).
substatus Response specific number indicating what the problem was, eg. http status code
message Response specific message in case there was a problem (can be null)
rc Return Code, a human readable code based on the substatus
Response Codes
If all is ok, the status is zero, for non-zero statusses you can find the description below.
1 POOL_DEPLETED Maximum number of connections exceeded
2 POOLCREATIONERROR Error creating a connection
Examples
Retrieving a pacfile to return as a header.
workItem.tamRequest = tb.tamIVCredsRequest({
username: 'jdoe',
attributes: [
['demo_fname','John'],
['demo_lname','Doe']
],
groups: ''
})
Response
var status = workItem.tamResponse.status;
if (status === 0) {
tb.log("successfull response");
var pacFile = workItem.tamResponse.pacfile;
} else {
tb.log("bad response received from TamAdapter, status: " + status,'Tam','error');
}
Creating a user.
workItem.createrequest = tb.tamCreateUserRequest(workItem.userdetails.setdn, workItem.userdetails.firstname, workItem.userdetails.lastname, workItem.userdetails.username, workItem.userdetails.password);
workItem.createrequest.setPasswordValid(true);
workItem.createrequest.setAccountValid(true);
Response
var status = workItem.tamOutput.status;
if (status == 0) {
tb.log("successfull TAM call");
} else {
tb.log("Bad response received from TamAdapter, status: " + status,'Tam','error');
return "error";
}
Create, update & delete GSO
var resourceName = "gso_backend";
var resourceType = "web";
var tamUser= "jdoe";
var resourceUser = "Backend_user";
var resourcePassword = "Backend_password";
workItem.tamRequest = tb.tamCreateSSOCred(resourceName, resourceType, tamUser, resourceUser, resourcePassword);
Response
var response = workItem.tamResponse;
if(response.status == 0) {
tb.log("Successful response, GSO Created");
}
Update GSO
var resourceName = "gso_backend";
var resourceType = "web";
var tamUser= "jdoe";
var resourceUser = "Backend_user";
var resourcePassword = "Backend_password";
workItem.tamRequest = tb.tamSetSSOCred(resourceName, resourceType, tamUser, resourceUser, resourcePassword);
Response
var response = workItem.tamResponse;
if(response.status == 0) {
tb.log("Successful response, GSO Updated");
}
Delete GSO
var resourceName="gso_backend";
var resourceType="web";
var tamUser="jdoe";
workItem.tamRequest = tb.tamDeleteSSOCred(resourceName, resourceType, tamUser);
var response = workItem.tamResponse;
if(response.status == 0) {
tb.log("Successful response, GSO Deleted");
}
Setting TTL timings in the java environment
This settings will adjust the settings to wait for a context creation and controls how long a context can live in the environment.
TAM.TIMEOUTINSEC : Configures the timeout for context creation
TAM.TTLINSEC : Configure the timeout a context can live in the pool
This settings can be set as global JVM environments. For example:
JAVA -DTAM.TTLINSEC=300 -DTIMEOUTINSEC=5
Setup Secure Connection with IBM Security Access Manager
Installation ISAM Java Runtime
The ISAM Java runtime can be installed on multiple Operating Systems, to have a complete list of compatible system check out the link to the IBM website. http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/com.ibm.itame.doc6.1.1/am611install126.htm?path=32044#jrun
Configuring JAVA to use ISAM Java Runtime
After installation it is necessary to configure the JAVA Runtime Environment to be able to use the ISAM Java runtime.
#Configuring Java runtime
/opt/PolicyDirector/sbin/pdjrtecfg -action config -java_home <JAVA_HOME> -host <POLICY_SERVER_HOST> -config_type full -domain <TAM_DOMAIN>
This will copy over all necessary JAR files to the JAVA RTE.
You must make sure that there is only 1 PD.jar file present under your JAVA installation (classpath). Multiple PD.jar files can lead to unexpected results. for more information about the utility:
Registering JAVA inside the ISAM environment
With the configuration of the ISAM Java runtime, it will be possible to setup a connection to the ISAM environment. The component (in this case the JAVA installation) needs to be authorized to preform tasks within this domain.
#Configuring the Authorization of the java application server.
export JAVA_HOME=<PATH_TO_JAVA_INSTALLATION>
export PATH=$JAVA_HOME/bin:$PATH
java com.tivoli.pd.jcfg.SvrSslCfg -action config -admin_id <ADMIN_USER> -admin_pwd <ADMIN_PASSWD> -host <HOSTNAME> -appsvr_id <APP_ID> -port 7130 -mode remote -policysvr <FQDN_POLICY_SERVER>:<POLICY_SERVER_PORT>:1[,<FQDN_STANDBY_POLICY_SERVER>:<STANDBY_POLICY_SERVER_PORT:2, ...] -authzsvr <FQDN_AUTH_SERVER>:<AUTH_SERVER_PORT>:1[,<FQDN_AUTH_SERVER2>:<AUTH_SERVER2_PORT>:2, ...] -cfg_file <LOCAL_CONFIG_FILE> -key_file <LOCAL_KEYFILE> -certrefresh true -cfg_action create
-action
The action preformed with the utility. config: The utility will configure a component to be able to use the administration and authorization API's inside the ISAM environment unconfig: will remove the component from the ISAM environment.
-admin_id
The Administrator of ISAM, usually sec_master
-admin_pwd
Password for the administrative username
-host
Host name of application server
-appsvr_id
Functional name of the component, this is shown inside ISAM when preforming a server list command.
-policysvr
Ip and port of the policy directory server that is being connected to. This is a comma seperated list with the following notation FQDN:PORT:WEIGHT
-authzsvr
IP and port of the Authorization Server that is being connected to, 7136 is the default port. This is a comma seperated list with the following notation FQDN:PORT:WEIGHT
-cfg_file
Path and file name on the client where to save the configuration file that is created by this command. This is what is set in the TamConfigUrl in the TrustBuilder configuration in the previous chapter.
-key_file
Path and file name on the client where to save the certificates for connection to the ISAM server.