Skip to main content
Skip table of contents

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.

CODE 
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)

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

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

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

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

CODE 
tamCreateGroupRequest( groupName, groupDN, groupContainer)
Delete Group

Deletes a group from the PDMS and optionally from the user registry.

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

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

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

CODE 
tamAuthenticateRequest( username, password)

Parameters:

  • username Non-null, non-empty string.

  • password Non-null, non-empty string.

Example : request example

CODE 
workItem.request = tb.tamAuthenticateRequest(user,password);

Gives as result

CODE 
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

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

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

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

CODE 
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

CODE 
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 :

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

CODE 
workItem.tamRequest = tb.tamIVCredsRequest({
    username: 'jdoe',
    attributes: [
        ['demo_fname','John'],
        ['demo_lname','Doe']
    ],
    groups: ''
})

Response

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

CODE 
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

CODE 
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

CODE 
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

CODE 
var response = workItem.tamResponse;
if(response.status == 0) {
    tb.log("Successful response, GSO Created");
}

Update GSO

CODE 
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

CODE 
var response = workItem.tamResponse;
if(response.status == 0) {
    tb.log("Successful response, GSO Updated");

}

Delete GSO

CODE 
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:

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

CODE 
#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.

CODE 
#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.

For more information about the utility

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close