A SiteMinder Agent is a client of the Agent API. The agent enforces access control policies served by the Policy Server. The Policy Server is a general-purpose policy engine with no specific knowledge of resources. The specific knowledge of resources is provided by SiteMinder agents. Agents establish resource semantics and act as gate keepers to protect resources from unauthorized users.

Different agent types protect different kinds of resources. Some agent types are pre-defined, standard agents that are shipped as part of the SiteMinder product—for example, the Web Agent, which provides HTTP access control for Web Servers. However, you can also use the Agent API to implement custom agents.

The Agent API lets you create a custom agent that can authenticate and authorize users in a variety of context-specific ways. For example, you could create an agent for FTP transfers that does the following:

Implements certificate-based authentication instead of basic name and password credentials.
Allows uploads and downloads based on an individual user’s authorization level.

Custom agents can participate in a single sign-on environment with standard SiteMinder Web Agents.

Agent Type

The Agent Type defines the behavior of an agent. After you have developed a custom agent, you must configure a new Agent Type for the agent in the Policy Server User Interface. For example, if you developed a custom FTP Agent, you would then need to configure an Agent Type for the FTP Agent in the Policy Server User Interface.

Note: For information on configuring an Agent Type for your custom agent, see the SiteMinder Programming Guide for C.

Agent API Class Hierarchy

The primary point of access to the Java Agent API is the AgentAPI class. Several other classes are provided to hold data required by the AgentAPI class:

Attribute
AttributeList
BinaryBuffer
InitDef
ManagementContextDef
RealmDef
ResourceContextDef
ServerDef
SessionDef
TokenDescriptor
TunnelServiceRequest
UserCredentials

Implement the JNI Java Agent API

Applications that are built using the JNI Java AgentAPI either directly or indirectly (through another agent) are insulated from underlying implementation details, including:

User namespaces, such as LDAP directories, SQL databases, or NT domains
Authentication methods as simple as username/password or as complex as PKI systems
Authorizations based on group membership or individual profile data

Additional benefits provided by the Java Agent API include full session management support, automatic encryption key rollover, and real-time policy updates.

To implement the JNI Java Agent API

Review the required software as listed in the accompanying release notes.
Review the sample code.
Write source code for your client application.
Ensure that your system can find the JNI support libraries when the Java Virtual Machine (JVM) is invoked, as follows:
- On Windows: Change PATH to include the following, so that smjavaagentapi.dll, smerrlog.dll, and smcommonutil.dll can be found:
<install_path>\sdk\bin
- On Solaris: Change LD_LIBRARY_PATH to include the following, so that libsmjavaagentapi.so, libsmerrlog.so, libsmcommonutil.so can be found:
<install_path>/sdk/bin
- On AIX: Change LIBPATH to include the following, so that libsmjavaagentapi.so, libsmerrlog.so, and libsmcommonutil.so can be found:
<install_path>/sdk/bin
- On Linux: Change LD_LIBRARY_PATH to include the following, so that libsmjavaagentapi.so, libsmerrlog.so and libsmcommonutil.so can be found:
<install_path>/sdk/bin
- On HP-UX 11: Change SHLIB_PATH to include the following, so that libsmjavaagentapi.so, libsmerrlog.so, and libsmcommontuil.so can be found:
<install_path>/sdk/bin

Note: The Java Agent API is not available for HP10.
Ensure that SiteMinder can find the JNI Java AgentAPI JAR file when you compile or run an agent that uses the Java Agent API. The JAR file, smjavaagentapi.jar, is stored in the following locations:
- Windows platforms:
<install_path>\sdk\java
- UNIX platforms:
<install_path>/sdk/java

Add smjavaagentapi.jar to your CLASSPATH setting. When compiling, you can use the -classpath switch.
Compile the Java Agent API application using javac.
For an example, see java-build.bat or java-build.sh in the sample directory smjavaagentapi.
Configure the Policy Server to use the Java Agent API application.
Run the application.
For an example, see java-run.bat or java-run.sh in the sample directory smjavaagentapi.

Implement the Pure Java Agent API

Applications that are built using the pure Java Agent API either directly or indirectly (through another agent) are insulated from underlying implementation details, including:

User namespaces, such as LDAP directories, SQL databases, or NT domains
Authentication methods as simple as username/password or as complex as PKI systems
Authorizations based on group membership or individual profile data

Additional benefits provided by the Java Agent API include full session management support, automatic encryption key rollover, and real-time policy updates.

To implement the pure Java Agent API

Review the required software as listed in the accompanying release notes.
Review the sample code.
Write source code for your client application.
Ensure that SiteMinder can find the pure Java Agent API .jar file when you compile or run an agent that uses the Java Agent API. The JAR file, smagentapi.jar, is stored in the following locations:
- Windows platforms:
<install_path>\sdk\java
- UNIX platforms:
<install_path>/sdk/java

Add smagentapi.jar, crypto.jar, cryptoFIPS.jar to your CLASSPATH setting. When compiling, you can use the -classpath switch.
Compile the Java Agent API application using javac.
For an example, see java-build.bat or java-build.sh in the sample directory smjavaagentapi.
Configure the Policy Server to use the Java Agent API application.
Run the application.

Pure Java Agent API Usage

Backward compatibility

The pure Java Agent API maintains binary and source compatibility with the JNI Java Agent API. The pure Java Agent API supports all of the other SiteMinder Java SDK interfaces that rely on the Agent API for connectivity to the SiteMinder Policy Server, including the SiteMinder Policy Management API and the SiteMinder DMS API, in addition to extending the portability of those interfaces.

Configuration limitations

The pure Java Agent API does not change the configuration of either the SiteMinder Application Server Agents or any agents developed with the SiteMinder SDK. The configuration of the pure Java Agent API is identical to the configuration of the JNI Java Agent API with the following exceptions:

Migration of UNIX agents from the JNI Java Agent API to the pure Java Agent API requires re-registration of the trusted host entity with the SiteMinder Policy Server because the shared secret in the JNI Java API is computed differently from the pure Java implementation.
On both Unix and Windows systems (due to file-locking incompatibilities with the native code Agent API), the SmHost.conf file cannot be shared between agents using the C/C++ or JNI Java Agent API and agents using the pure Java Agent API. Therefore, a separate copy of the bootstrap configuration file must be kept for pure Java Agent API agents.
To register a host for a 5.x-type custom pure Java Agent you must use smreghost.bat (or smreghost.sh on UNIX), not smreghost.exe.
Upgrades from the JNI Java Agent API on Unix systems requires users of custom 4.x-based agents that use shared secrets encrypted with the 4.x encryptkey tool to update their shared secret on the agent side for upgraded agents.

Enable Pure Java Agent API Tracing

The pure Java Agent API supports detailed trace messages, which are printed to the console. These messages can be useful when running a command line tool that uses the Agent API, such as smreghost.

To enable trace messages, set a system property named enableDebug to "true". From the command line, add -Dcom.ca.siteminder.sdk.agentapi.enableDebug="true". For example:

>SM_SMREGHOST_CLASSPATH="c:\ca\sdk\java\smagentapi.jar;c:\ca\sdk\java\cryptoj.jar"
>java -Dcom.ca.siteminder.sdk.agentapi.enableDebug="true" -classpath %SM_SMREGHOST_CLASSPATH% com.ca.siteminder.sdk.agentapi.SmRegHost -i 127.0.0.1 -hc host_conf1 -hn trustedhost3 -u siteminder -p firewall