XPSRegClient Demystified

What is XPSRegClient and what does it do? XPSRegClient is a registration utility for R12 components such as the WAMUI and Report Server.  When run, it prepares the policy server for an incoming registration request from the component.  This article discusses the different options of this utility and when to use them, and things to look for during the process.

The XPSRegClient utility does not actually complete the registration.  In the case of a WAM UI, registration is not completed until you login to the WAMUI for the first time.  The policy server uses the credentials specified in the command to verify the registration request when you log in.

There are two different syntax formats when running the utility.  There has been confusion about which form to run and when.

When you run the command it creates a file in the /siteminder/bin directory called ‘siteminder.XPSReg’:

If you open the file you will see a digest value.  This value is used to generate the shared secret for the client during the handshake on initial login.  Also, you will notice that there is a line saying “this file is not valid after 2013-01-15 22:38:10 GMT”.  This is why the documentation states you must register within a certain time period after running the command.  This file is automatically deleted during successful registration.

What is the appropriate syntax to use and when?

When registering a WAMUI for the first time you must use the following syntax:

XPSRegClient siteminder:passphrase –adminui-setup [options]

  • Where ‘siteminder:passphrase’ refers to the siteminder superuser and the password
  • The ‘–adminui-setup’ parameter tells the policy server that the WAMUI is being registered with a policy server for the first time.

When you launch the WAMUI for the first time you should have a blank login screen.

Specify the SiteMinder superuser and password.  Under ‘Server’ enter the hostname or IP of the Policy Server you are connecting to: 

If you are able to login and get the home page registration is complete.  On the WAM UI machine, navigate to C:\Program Files (x86)\CA\siteminder\adminui\server\default\data\siteminder.  You should see a configuration file with a long string for a name:

This file is generated upon registration.  As you can see it stores the shared secret that is used by the WAM to connect with the policy server.  It also stores the policy server connection information and FIPS mode.  This file is equivalent to SmHost.conf for a webagent:

 

If you open XPSExplorer and lookup Administrators you will see that a new Admin Object gets created called SMWAMUI: 

Under Trusted Hosts you will see a host object generated by XPSRegClient

If you want to register another new WAMUI to the same policy server you still need to run XPSRegClient with the same syntax since it has not been registered with other policy servers.

If you register additional WAMUI with this same policy server you will see a new SMWAMUI administrator, and a new Trusted Host gets added with each registration:

Now, if you have ALREADY registered a WAMUI with a policy server, but want to register it against other policy servers you need to run XPSRegClient on the new Policy Server with a different syntax:

(*Please note this requires setting up an External Administrator store first.)

XPSRegClient client_name:passphrase –adminui [options]

  • Where ‘client_name’ can be whatever you want to call this client, and will be needed when creating the policy server connection.
  • The ‘passphrase’ can be anything you like, it will also be needed when creating the policy server connection for this client.
  • Leaving off the ‘-setup’ parameter tells the policy server that this WAM has already been registered with another policy server.

Run this command on the remote policy servers where you want to connect.   Here is an example:  XPSRegClient smui1:passphrase -adminui

Navigate to /siteminder/bin and notice the file created has the client name you specified while running the command:

Navigate to /siteminder/bin and notice the file created has the client name you specified while running the command:

If registration is successful you will now be able to connect to both policy servers from the single WAM.  You can do this by selecting the connection from the ‘Connect to server’ dropdown menu at the login screen, or from the dropdown after you have logged in:

Open XPSExplorer on the second policy server and lookup trusted hosts.  You will see a new host object with the name of the client you specified:

Lookup Administrators and you will see a new SMWAMUI admin object, which refers to the smui1 client:

Hopefully this has helped take some of the mystery out of what XPSRegClient does and how it should be run.   Thanks for reading!