Agent API in Java

The Agent API works with the Policy Server to create custom agent applications for leveraging the authentication and authorization capabilities of Policy Server. You can also construct a secure communication tunnel to transmit application-specific data. Developers creating applications that are built using the Agent API either directly or indirectly (through another agent) are shielded from the following implementation-specific details:
casso1283
The Agent API works with the Policy Server to create custom agent applications for leveraging the authentication and authorization capabilities of Policy Server. You can also construct a secure communication tunnel to transmit application-specific data. Developers creating applications that are built using the Agent API either directly or indirectly (through another agent) are shielded from the following implementation-specific details:
  • User namespaces such as LDAP directories, SQL databases, or NT domains
  • Authentication methods as simple as user name and password, or as complex as PKI systems
  • Authorizations based on group membership, or individual profile data
Additional benefits provided by the Agent API include full session management support, automatic encryption key rollover, and real-time policy updates.
The Agent API has a local or remote access type to Policy Server.
SiteMinder
Agents
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 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 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 Web Agents or
Access Gateway
.
The following figure shows the process flow that occurs when an agent uses the Agent API:
How Agents Use Agent API in Java.png
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 Administrative UI. For example, if you developed a custom FTP Agent, you would then need to configure an Agent Type for the FTP Agent in the Administrative UI.
Agent API Class Hierarchy
The primarypoint 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
: The Pure Java Agent API does not include all the classes provided by the JNI Agent API. Specifically, the Pure Java Agent API does not include ServiceAPI.class and ServiceSession.class.
Implement Agent API in Java
When using the Agent API in Java, code your agent in Java. The Agent API has two implementations:
  • The JNI API that relies on the native C/C++ Agent API libraries. This implementation uses the interface presented in SDK, versions 5.x and later.
  • The Pure Java Agent API that replaces the native code used in the JNI API with pure Java components. The present version of this API uses the same interface as the JNI API.
The Pure Java Agent API is highly portable to new operating environments as there are no native-mode components. Applications written using the pure Java implementation require certification only against the Java Virtual Machine hosting the implementation, rather than against individual operating systems.
Implement the JNI API
Follow these steps:
  1. Review the required software as listed in the accompanying release notes.
  2. Review the sample code.
  3. Write source code for your client application.
  4. Ensure the system can find the JNI support libraries when the Java Virtual Machine (JVM) is invoked. Include the path to the directory where the libraries are by modifying the following variables:
    • Windows: Change the PATH variable to include
      install_path
      \sdk\bin
      , so that smjavaagentapi.dll, smerrlog.dll, and smcommonutil.dll can be found.
    Note: The Java Agent API is not available for HP10.
  5. Ensure that can the JNI Java AgentAPI JAR file can be located 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, use the -classpath switch.
  6. Compile the Java Agent API application using javac.
    For an example, see java-build.bat or java-build.sh in the sample directory smjavaagentapi.
  7. Configure the Policy Server to use the Java Agent API application.
  8. 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
The following are the usages of Pure Java Agent API:
Backward compatibility
The pure Java Agent API maintains binary and source compatibility with the JNI API. The pure Java Agent API supports all of the other Java SDK interfaces that rely on the Agent API for connectivity to the Policy Server, including the Policy Management API and the 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 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 API with the following exceptions:
  • Migration of UNIX agents from the JNI API to the pure Java Agent API requires re-registration of the trusted host entity with the 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 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 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.
Follow these steps:
  1. Review the required software as listed in the accompanying release notes.
  2. Review the sample code.
  3. Write source code for your client application.
  4. Ensure that the pure Java Agent API .jar file can be found 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
    ,
    smcrypto.jar
    ,
    and
    bc-fips-1.0.1.jar
    to your CLASSPATH setting. When compiling, use the
    -classpath
    switch.
  5. Compile the Java Agent API application using javac. For an example, see java-build.bat or java-build.sh in the sample directory smjavaagentapi.
  6. Configure the Policy Server to use the Java Agent API application.
  7. Run the application.
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\smcrypto.jar;c:\ca\sdk\java\bc-fips-1.0.1.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 password