IBM Tivoli Access Manager How To
|IBM Security Access Manager|
|TAM How To's|
|General · ITIM Integration · WebSphere Portal Integration|
|General TAM Topics|
|How To · Troubleshooting · Technical Notes|
|Security Identity Manager · Security Directory Integrator · Tivoli Directory Server|
 How to add TAM schema to LDAP (an alternative way)
If the LDAP server has TAM runtime installed and configured then do:
./opt/PolicyDirector/sbin/ivrgy_tool -d -h SERVER -p 389 -D cn=root -w password schema
 How to allow TAM to change passwords in AD
Enable ssl (ldaps) on AD and use it to change passwords.
 How to audit switch user functionality
[ba] ba-auth = both [authentication-mechanisms] su-password = /opt/pdwebrte/lib/libsuauthn.a [aznapi-configuration] logaudit = yes auditcfg = authn
 How to change default login and logout pages
- modify /opt/pdweb/www-default/html/C/login.html and logout.html
- use "/pics" based refs to the images inside these .htmls
- put all images in www-default/docs/pics
- attach a non restrictive acl to the pics folder, like this
pdadmin -u sec_master -w password acl attach /WebSEAL/mpuwsl-default/pics WPS_All_access
- confirm by pointing a browser to /pics/some_image_jpg
there is no need to restart webseal, it will pick up changes on the fly.
Edit d:\program files\tivoli\pdweb\www-default\html\C\login.html Assuming images for this page are hosted on webseal do the following. Use "/pics/:" based references to the images that you want to put on this page. Put all images on the IHS server in /pics (not tested. if it fails try putting them on WebSEAL in d:\program files\tivoli\pdweb\www-default\docs\pics. Attach a non restrictive acl:
pdadmin -u sec_master -w **** "acl attach /WebSEAL/:-default/pics WPS_All_access
Confirm access by browsing to /pics/some_image. There is no need to restart WebSEAL.
 How to change the sec master password
Docs say you can't unless TAM is unconfigured, but that is not correct. Try to do it in LDAP admin for cn=SecurityMaster,secAuthority=Default. Then check it by running
ldapsearch -D "cn=SecurityMaster,secAuthority=Default" -w password -h xx.xx.7.141 -b "secAuthor
To reset the secmaster password, perform either of the following:
- use the LDAP DMT (Directory Management Tool) to reset the password for the user account directly in LDAP.
- If Access to a DMT is not available, then use the ldapmodify command as follows:
ldapmodify -h LDAP_HOST -v -D cn=root -w rootpw -f mymod.ldif
where the mymod.ldif file contains the following information:
dn: cn=SecurityMaster,secAuthority=Default userpassword: yournewpassword
check by doing this
ldapsearch -D cn=root -w password -h host -b "cn=SecurityMaster,secAuthority=default" -s sub (objectclass=*)
However be very cautious and try not to do it in a Production environment.
 How to configure PD JRTE manually
pdjrtecfg -action config -config_type full -host xxx-port 7135 -java_home d:/WebSphere/AppServer/java/jre
 How to configure TAM and Plumtree portal
Configure plumtree to understand iv-user and configure the junction with -c iv-user (to send iv-user) and -b supply - to submit the basic auth for "trust" (not necessary)
 How to configure aznAPI failover
The aznAPI can be configured in remote mode for Java-based applications. The aznAPI can also configured in remote mode for C-based applications, however this is never done, so we will concentrate on the java space. For Java based applications using the TAMeb Java aznAPI, there is a requirement for the existence of a TAMeb Authorization Server. This Authorization Server acts as the decision maker for authorization calls as well as being the authentication provider for verifying credentials with the TAMeb directory infrastructure. The java authorization API also has internal mechanisms for communicating with Authorization Servers. The connections are secured by SSL and are of an internal proprietary format. Hence the principals described by figure 4 above can be applied.
In order to configure the internal failover of TAMeb within the Java aznAPI, it is a simple case of executing the "svrsslcfg -action addsvr" command after the configuration of the aznAPI. After this, the failover of the Authorization server instances will occur transparently. Note that load balancing is not supported across multiple Authorization servers within the Java Authorization API.
As an example of this, let's assume a customer is using the AMWAS application which leverages the TAM Java aznAPI, the WAS server is up and running, and AMWAS has created the initial authenticated context with the Authorization Server. So when a web client connects to WebSphere, here is what happens:
- WebSphere receives request.
- The application container requires a role based access control decision.
- The container communicates to AMWAS for 'isuserinrole()' type decision.
- The role mapping is not within the AMWAS cache.
- AMWAS formulates an authorization decision and asks the java runtime to consult the pdacld for the decision.
- Java runtime extracts the authenticated context and uses this to communicate with the pdacld over a previously negotiated SSL channel.
- Pdacld confirms the context is valid.
- Pdacld returns the authorization decision.
- AMWAS caches this information.
- AMWAS returns the decision to the container.
- Container acts appropriately.
In the case of a failover event, the connection is sent to the configured failover Authorization Server, which will renegotiate an SSL session and context at the time of failover. 
 How to configure complex TAM LDAP failover
LDAP master-slave or LDAP peer-to-peer server configurations it can succumb to data inconsistencies since the write access to LDAP data is not synchronized within ITAM but based upon LDAP server capabilities. Therefore is only a kind of "load balancing" possible for the read-requests issued from the TAM run time environment.
- The host entries in the ldap.conf file MUST point on ALL ITAM related systems to the same LDAP master server (Only way to assure a consistent content of LDAP from write operations).
- A replica statement in a ldap.conf file CAN NOT refer to the same server as the host statement.
- Additional available LDAP slave server can be used as primary server for read requests by defining appropriate replica statements in the ldap.conf file with a higher priority than 5.
- Additionally it must be manually assured, that all the ivacl.conf, pd.conf, ivmgrd.conf, webseald.conf files are configured correctly on each of the systems to reflect the ldap.conf definitions.
- It is also recommended that you have on systems with configuration activities the read-write server as your highest priority server. Otherwise failures can occur e.g. when the user is created on one server but the bind for that server is sent to another user data copy before replication completes.
 How to create WebSEAL junction to allow LTPA SSO into Domino
Domino is setup to allow LTPA tokens for authentication and needs to setup a junction that has WebSEAL generate the LTPA token to the Domino server to do authentication. You create the junction as follows if to a Win32 based backend Domino serve that accepts LTPA tokens for authentication
pdadmin> s t webseald-[host] create -t tcp -i -w -A -F c:\ltpa.key -Z [LTPA password] -h domino_host /junction_name
 How to create a junction that creates an LTPA token for SSO to a backend server
Perform the following:
pdadmin> s t webseald-[host] create -t tcp -i -w -A -F c:\ltpa.key -Z password -h backend_host /junction_name
-i and -w are only required if the backend is a win32 based server
 How to create an LTPA SSO
- In Websphere Application Server, go to the LTPA section
- enter password twice hit generate keys, click save, save again
- enter password twice, enter the file name (/var/tmp/file is fine) and hit export
- copy and paste the contents of the file (to avoid issue with the endlines) if you are using unix and windows into a new file on a websealbox
pdadmin> object create /WebSEAL/newroot "WebSEAL_objectspace" 5 ispolicyattachable yes
 How to create customized login pages based on junctioned applications (TAM skinning)
The login page on the WebSEAL server is modified to evaluate the URL and apply appropriate layout and stylesheets.
- Pro: easy to setup and use
- Con: limited flexibility
- Local response redirection
TAM is configured to refer authentication decisions to an external application. That application decides on what login pages to present
- Pro: unlimited functionality
- Con: reliance on an external server for core TAM functions
A very basic login page is included inside of the back-end login pages. Back-end login pages are configured for unauthenticated access
- Pro: Login pages reside on the back-end servers
- Con: Complex to setup/Easy to break
- Multiple instances.
One instance of WebSEAL service is created per the page needed to be skinned
- Pro: each instance is essentially an out-of the box installation with only login page required to be modified.
- cons: Resource contentions - instances on a same server must be assigned to different ports and/or host names/IPs
 How to enable LDAP tracing in connection with Access Manager
When you need to see what calls are being made between the Access Manager and the LDAP, enable it by setting an environment variable in the environment where Policy Server or webseald is started, before starting Policy Server or webseal. The following example will allow the trace information to be written to a file. The advantage of this technique is that all the trace information is collected even from the very start of the webseal process:
On unix for the Policy Server and webseal
where xxxxx is the path and file name of the file to be used for the output.
Also, in addition to taking the Policy Server/webseal trace information, you can also turn on the ldap client tracing for the time that Policy Server webseal is running. This can be done by exporting the following environment variables.
export LDAP_DEBUG=65535 export LDAP_DEBUG_FILE=xxxxxx
set LDAP_DEBUG=65535 set LDAP_DEBUG_FILE=xxxxxx
where xxxxx is the path and file name of the file to be used for the output.
These environment variables affect only applications run in the same shell (or command window) session. You can also call ldap_set_option() in your application to enable and disable the library's trace messages.
 How to enable TAM Auditing
Events are logged in XML format
Edit webseal-default.cfg, [aznapi-configuration] stanza. Set:
logaudit=yes auditlog = log location auditcfg = azn auditcfg = authn auditcfg = http
Policy Server Auditing
Edit ivmgrd.conf, [aznapi-configuration] stanza. Set:
logcfg = audit.azn:file path= d:\program files\Tivoli\policydirector\audit\pdmgrd.log,flush_interval=20,rollover_size=2000000,log_id=PDMgrAudit logcfg = audit.authn:file log_id=PDMgrAudit logcfg = audit.mgmt:file log_id=PDMgrAudit
 How to enable TAM webseal log rollover
Enabling logfile roll-over for msg_webseald.log file
The contents of the msg_webseald.log file come from webseal's STDERR, as controlled in the /opt/pdweb/etc/routing file
FATAL:STDERR:- ERROR:STDERR:- WARNING:STDERR:-
The routing file can be modified to redirect these messages to a file, and the log file management can be configured at the same time. For example...
FATAL:UTF8FILE.10.10000:/var/pdweb/log/msg__webseald.log ERROR:UTF8FILE.10.10000:/var/pdweb/log/msg__webseald.log WARNING:UTF8FILE.10.10000:/var/pdweb/log/msg__webseald.log
If you have multiple webseal instances on the same system, the default is that they will all use the same routing file. Because it's not desirable to have logging from more than one webseal in the same file, it is necessary to get each instance to use a separate routing file (each configured with a separate log file).
The environment variable PD_SVC_ROUTING_FILE can be set to point to a specific routing file which webseal will use when starting up. This allows you to have a different routing file for each instance, which allows you to configure a different log file for each instance.
Then you could write a script which will set the PD_SVC_ROUTING_FILE to point to the appropriate routing file before starting the instance, such as...
PD_SVC_ROUTING_FILE=/opt/pdweb/etc/routing.instance1 export PD_SVC_ROUTING_FILE /opt/pdweb/bin/pdweb_start start instance1
Ideally your script could be made to work like the pdweb_start command so that if you don't specify an instance, it starts them all, or if you specify a specific one, it only starts that particular instance.
 How to enable WebSEAL traffic tracing
In webseald-<instance>.conf add the following to the [aznapi-configuration] stanza:
[aznapi-configuration] trace = pdweb.snoop 9 logcfg = trace.pdweb.snoop+9:file path=d:/temp/snoop.log
 How to erase TAM LDAP data
ldapcfg -a ldapdb2 -w ldapdb2 -d amdb -c -l /usr/db2data
and choose to wipe all the data
 How to fall back to forms based authentication in case SPNEGO fails
You CAN enable both spnego and forms (contrary to the documentation) - it will fail over to forms if spnego is not available.
 How to force WPM into unconfigured state without unconfiguring it (unconfigure manually)
Change state=configured line to state= in the PolicyDirector\etc\amwpmcfg.properties then unconfigure jrte, configure it back. then you can configure WPM back
 How to forward root context to a junction.
<meta http-equiv="refresh" content="0;url=https://xxxxportal.server.com/lwp/myworkplace">
 How to get WebSEAL domain name
pdadmin -user sec_master
Then type "server list". It is the one with "webseal" in the middle.
 How to get WebSEAL object space name
pdadmin -user sec_master
Then type "object list /WebSEAL"
 How to import users from Active Directory or LDAP
Start Tivoli/Policy Director/bin/pdadmin.exe
pdadmin>login ( user sec_master, pass sec_master ) pdadmin sec_master>user import -gsouser wasadmin "CN=wasadmin,CN=Users,DC=domain,DC=com" pdadmin sec_master>user modify wasadmin account-valid yes pdadmin sec_master>user import -gsouser wasadmin1 "CN=wasadmin1,CN=Users,DC=domain,DC=com" pdadmin sec_master>user modify wasadmin1 account-valid yes pdadmin sec_master>user import -gsouser wasadmin2 "CN=wasadmin2,CN=Users,DC=domain,DC=com" pdadmin sec_master>user modify wasadmin2 account-valid yes
 How to make TAM switch back to an LDAP replica
There is an optional stanza called prefer-readwrite-server. If this stanza is added, the WebSeal will always check the read-write server first to see if it is available. If not, it will then go to the replicas.
The default is that this is disabled. Try adding this and see if that solves your issue. I don't have any way of testing this in my lab, but from what I understand here, that is how it should work.
 How to manage GSO credentials from a command line
pdadmin -a sec_master -p password -v 'rsrccred modify <GSOname> rsrrctype web set -rsrcuser <gsouserid> -rsrcpwd <gsopwd> user <username>'
 How to migrate or switch LDAPs
AKA Automatically populating LDAP and Re-configuring TAM components for a newly installed LDAP after the TAM was configured for another LDAP
- Check New LDAP
- Backup old LDAP data and move it to the new one as needed. See "manually populating LDAP"
- Make sure new LDAP is functioning properly
ldapsearch -D cn=root -w tivoli -b "" -s base objectclass=*
- Reconfigure TAM
- Backup conf files from /opt/PolicyDirector/etc
- Remove the component names /opt/PolicyDirector/.configure
- Remove all keyring files from /var/PolicyDirector/keytab/
- Add the ldap hostname in /etc/hosts
- Run pdconfig
- configure Runtime
- configure Policy Server.
- configure Authorization Server
- configure WebSEAL (do not omit this step)
- If configuration of any component fails try to un-configure it and then configure it again.
- Reconfigure TAM Web Portal Manager
- On a WPM machine do
c:\Program Files\Tivoli\Policy Director\sbin pdjrteconfig -action unconfigure -host tamserver -interactive (unconfigure everything) pdjrteconfig -action configure -host tamserver -interactive (configure websphere jre) amwpmcfg -action unconfigure -interactive amwpmcfg -action configure -interactive
Add proper TAM ACLs to LDAP. See am51_admin.pdf pages 344-345. If you are adding WebSphere Portal Server later on you might have to add wpsadmin/wpsbind into remote-acl-users group so that the LDAP ACLs do not interfere with what WPS needs for wpsadmin/wpsbind. For more info look into the WPS-TAM integration cookbook
 How to perform TAM tracing
If there are multiple WebSEAL instances, and it is not possible to recreate the problem by using only a single WebSEAL instance, all data must be collected concurrently from all WebSEAL instances involved. Note that all example file names use Unix conventions - please substitute Windows conventions (i.e., c:\temp\ rather than /tmp/) if the WebSEAL instance is on Windows.
Ensure that 'requests = yes' in the [logging] stanza of the webseald.conf file. If the setting is changed, restart the WebSEAL instance.
Enable WebSEAL tracing.
pdadmin> server task <webseald-server> trace set pdweb.debug 9 file path=/tmp/pdweb.debug.trace pdadmin> server task <webseald-server> trace set pdweb.snoop 9 file path=/tmp/pdweb.snoop.trace
Start a network trace on the WebSEAL system. If multiple interfaces are used, traffic on each interface must be collected (this usually requires that multiple simultaneous traces be collected). If limiting the collected traffic, the TCP traffic to the ports WebSEAL and the backend servers are listening for requests on, and ICMP traffic, must be collected. This is generally only needed for performance issues, or SSL certificate problems. The WireShark (formerly Ethereal) network protocol analyzer may be used to collect network traces on all Access Manager WebSEAL platforms. Native network trace utilities (such as iptrace on AIX) may also by used.
Recreate the problem. If possible, use a new browser after clearing the browser cache. Stop the network trace. Wait 1 minute, then disable WebSEAL tracing.
pdadmin> server task <webseald-server> trace set pdweb.debug 0 pdadmin> server task <webseald-server> trace set pdweb.snoop 0
- The output of the `pdversion` and `gsk7ver` commands on the policy server system (all output should be captured as text, not as screen shots).
- The output of the `pdversion`, `gsk7ver`, and `/opt/pdweb/bin/webseald -version` commands on the WebSEAL server system.
- The webseald.conf file from the WebSEAL instance.
- The junction XML files from the junction-db directory specified in the webseald.conf file.
- The fsso.conf files for any FSSO junctions. If used, the jmt-map (jmt.conf) and/or dynurl-map (dynurl.conf) files specified in the webseald.conf file.
 How to redirect HTTP to HTTPS
change the index.html to forward to some location on https, allow both http and https connections. Now create pop for "privacy" and attach it to the resources that you want to be accessed through SSL only.
In more details:
Customize the WebSEAL error page for Forbidden (HTTP status code 403) to detect if the user has made the request over HTTP, and automatically redirect to HTTPS to login. Add the following code fragment at the top of the file <PDWEB>/www-<instance>/lib/errors/<locale>/38cf0427.html.
 How to restart TAM
/opt/PolicyDirector/bin/pd_start start /opt/PolicyDirector/bin/pd_start stop
 How to restart WebSEAL
/opt/pdweb/bin/pdweb_start stop /opt/pdweb/bin/pdweb_start start
or bounce WebSEAL service or
 How to setup SPNEGO authentication with kerberos using a loadbalancer for more than one webseal server
Listed here are the only main differences from the suggested setup procedure of the Webseal Admin guide (Windows desktop single sign-on section)
- You probably created 2 Active Directory users for each webseal. However, only one is needed which will actually be mapped to the load balancer during the ktpass command.
The document for unix specifies:
"On UNIX, ensure that the user name matches the host name of the WebSEAL server host. Do not use the full domain name. For example, for the system diamond.subnet2.ibm.com, create a user diamond. Do not require the user to change password at next log in. Do not set the password to expire."
If you want to remain consistent you can create a new user that uses the shortname of the loadbalancer. However, in the end we just need a user to map with.
- For the ktpass use the hostname of the load balancer. Therefore
the command will look something like the following:
ktpass -princ HTTP/<load balancer hostname>@IBM.COM -pass mypassw0rd -mapuser <user created in step 1> -out /opt/pdweb/keytab/<loadbalancer>_HTTP.keytab -mapOp set
Please ensure the DNS lookup for the load balancer matches the reverse lookup (ie a lookup of ip matches the hostname, lookup of hostname matches the same ip)
- copy the one keytab file created in step 2, to both webseal server boxes. Then execute the 'kinit' test to verify both can authenticate using the Http principal.
kinit -k -t /var/pdweb/keytab-WebSEAL1/uatsso-hac_HTTP.keytab HTTP/uatsso-hac.us.com@DOMAIN.ADROOTTEST.COM
- for the following:
[spnego] # UNIX ONLY spneg-krb-service-name = HTTP@<load balancer hostname>
Use load balancer hostname.
- Configure explorer trusted site to be the load balancer hostname. Not the webseals hostnames.
 How to start services (TAM WebSEAL IDS) on boot in AIX
/etc/inittab pd:2:wait:/etc/pd/pd start > /dev/console 2>&1 ldapd:2:once:/bin/ibmslapd > /dev/console 2>&1 #autostart LDAP/DB2 Services
 How to update schema in a non-root domain AD environment
If you configured Tivoli Access Manager in the single domain, and the domain is the non-root domain, you must run adschema_update.exe manually on the root domain controller.
Creating an Active Directory administrative user To create an Active Directory administrative user for Tivoli Access Manager initialization, follow these steps: 1. On the Active Directory server system, select Start > Programs > Administrative Tools > Active Directory Users and Computers. 2. Create a new user and add this new user to the groups of Administrators, Domain Admins, Enterprise Admins and Schema Admins. This user is an Active Directory user only, not an Tivoli Access Manager user. You can select any name as the user login name, except sec_master, which is reserved for the Tivoli Access Manager administrator.
C:\Program Files\Tivoli\Policy Director\sbin\adschema_update.exe -u tampolicy -p password
 How to use POST to login to TAM pkmslogin
prompt> telnet webseal.example.com 80 Connected to webseal.example.com. Escape character is '^]'. POST /pkmslogin.form HTTP/1.1 host: webseal.webseal.com content-length: 56 username=testuser&password=my0passwd&login-form-type=pwd
User can issue a post to pkmslogin.form?filename=test.html where test.html is the file user wants to be redirected too after login.
The location of the test.html must be placed in the /www/lib/html/C directory for this to be successful.
Example: C:\Program Files\Tivoli\PDWeb\www\lib\html\C\test.html
Note that the POST must come from an non protected area of WebSEAL to successfully login and redirect properly to the test.html.
 How to verify TAM installation on AIX
lslpp -l | grep gsk lslpp -l | grep pd lslpp -l | grep ldap lslpp -l | grep db2
 How to run SPNEGO on Linux
Some vendors of Linux may include outdated versions of Kerberos5 which may require upgrading. A newer version of MIT Kerberos5 may need to be downloaded and installed. The required minimum level is MIT Kerberos5 version 1.2.8, the recommended level is MIT Kerberos5 version 1.4.2. These may be down-loaded from MIT's website at the following location: 
The following steps are the recommended method to compile and install the upgraded Kerberos5 on your Linux based system:
- Build - After extracting the source code, cd into the kerberos base directory and run as root:
./configure --enable-static --without-krb4 make
If you have problems running any of the above commands, please check the MIT documentation.
- Install - The default installation is /usr/krb5/lib. You can edit the Makefile to change this if needed, then run as root:
Again, if problems running the above command are encountered, check the included MIT documentation.
- Configure - At this point, the kerberos code should be compiled and installed. To modify your system to use the updated libraries (this includes TAM), run as root:
- Check - To check that the libraries are properly installed, run as root:
ldconfig -v | more
The output should look similar to this:
/usr/krb5/lib: libgssrpc.so.1 -> libgssrpc.so.1.4 libgssapi_krb5.so.1 -> libgssapi_krb5.so.1.4 libkrb5.so.1 -> libkrb5.so.1.4 libk5profile.so.1 -> libk5profile.so.1.4 libksvc.so.1 -> libksvc.so.1.4 libkdb5.so.1 -> libkdb5.so.1.4 libkadm5clnt.so.1 -> libkadm5clnt.so.1.4
This example shows the output after installing MIT Kerberos5 1.4.2 in the default directory. Your output may vary based on the exact version/options you use.
Note that after installing the upgrade, both the pdmgrd and webseald processes will require restarting before they will use the new libraries. Failure to restart these processes may result in said processes crashing.
Once the above steps have been completed, follow the configuration steps for Solaris in the "Windows desktop single sign-on configuration" section of the Tivoli Access Manager 5.1 WebSEAL Administration Guide.