Programming Guides › Programming Guide for Java › Java API Overview › Java Agent API

Java Agent API

Use the Java Agent API to build a custom agent for enforcing access control and for managing user sessions. Enforcing access control consists of the following:

• User authentication
• User authorization
• Auditing

When using the Java Agent API, code your agent in Java. The Agent API performs the connection to the Policy Server.

The SiteMinder Java Agent API has two implementations:

• The JNI Java Agent API, which relies on the native C/C++ Agent API libraries. This implementation uses the interface presented in the SiteMinder SDK, versions 5.x and later.
• The pure Java Agent API, which replaces the native code used in the JNI Java Agent API with pure Java components. The present version of this API uses the same interface as the JNI Java Agent API.

Because there are no native-mode components, the pure Java Agent API is highly portable to new operating environments. Applications written using the pure Java implementation require certification only against the Java Virtual Machine hosting the implementation, rather than against individual operating systems.

Important! To use the pure Java API, your Java JCE must be unlimited strength jurisdiction. You can download the files from Sun at the following URL:

http://java.sun.com/products/jce/javase.html#UnlimitedDownload.

Policy Management API

Use the Policy Management API to manage the following SiteMinder elements:

• Resources
• Policies
• Caches
• Security roles

You can manage policies by creating, deleting, associating, and modifying policy objects such as policy domains, realms, and policies.

Authentication API

Use the Authentication API to create a custom authentication scheme that implements authentication service not offered by any of the standard SiteMinder authentication schemes.

Authorization API

Use the Authorization API to implement custom functionality for controlling access to protected resources. The functionality is provided through custom Java classes that are referenced in Policy Server active expressions. An active expression is a string of variable definitions that appears in the following Policy Server objects:

• Active policy
• Active response
• Active rule

Delegated Management Services API

Use the Delegated Management Services (DMS) API to perform tasks such as:

• Manage directory entries
• Grant privileges to users and to groups
• Grant DMS roles to users and to groups

Utilities Package

Use the methods in the Utilities package to implement the APIs in the Policy Management API and the DMS API.

How Java Components Fit Together

The following figure shows how the Java components of the SiteMinder SDK fit together:

Network Architecture

You can use the Java APIs to write client applications that connect to a remote SiteMinder Policy Server. These applications have access to the following built-in functionality of the Java Agent API:

• Security
• Load balancing
• Failover

The network architecture of the Java APIs is shown in the following figure:

The Policy Management API and the DMS API use the Java Agent API to access the Policy Server. A single API client instance makes a single, secure, Agent API connection to the SiteMinder Policy Server. As long as they share the same process space, multiple API clients can use a single Agent API connection. For example, you can use the Java Agent API to establish a connection, then use that connection to make DMS API calls.

Java API Flow

The steps listed following are required when you are creating a client application with the Policy Management API or the DMS API:

1. Establish a Connection to the Policy Server.
2. Obtain a Session.
3. Make API Requests.
4. Handle Results and Exceptions.

Establish a Connection to the Policy Server

To establish a connection to the Policy Server, use the SmApiConnection class of the Utilities package. This class holds the Agent API handle through which Java API requests are sent.

There are two types of connection handles in this class:

• A default connection handle. A default connection handle:
  • Represents a single instance of an Agent API object.
  • Is static across the process.
  • Allows connections to the Agent API object from both Policy Management and DMS clients.

  You can establish multiple connections to the Policy Server through the single Agent API object instance.

• A user-defined connection handle. You can create multiple user-defined connection objects; each one can support multiple connections to the Policy Server.

Establish a Default Connection

If you have not already established a connection to the Policy Server, you can request an automatic connection. If SiteMinder establishes a connection for you automatically, it creates a default Java Agent API object and handle. However, if a valid user-defined handle already exists, SiteMinder does not create a default object and handle. A user-defined handle takes precedence over a default handle.

To establish a default connection to the Policy Server automatically

1. Use the following constructor to create an API connection object:

      SmApiConnection (boolean bDefaultAgentConnection
                                   boolean disableLoadBalancing)
   

2. In the constructor, set bDefaultAgentConnection to true—for example:

      SmApiConnection m_defaultConnection = 
                                   new SmApiConnection(true,false);
   

3. If bDefaultAgentConnection is false, you must explicitly establish the connection in your client code.

An automatic connection has the following requirements:

• Your Web Agent be installed on the same machine where you are running the Agent API.
• The property DefaultAgentName in the Web Agent configuration object contains an agent name. You define the Web Agent configuration object in the Policy Server.
• With Apache Web Agents, the path to the Agent configuration file is in the CLASSPATH. With Microsoft IIS Web Agents, this configuration information is in the Registry, so a CLASSPATH reference is not necessary.

Establish a User-Defined Connection to the Policy Server

You establish a user-defined connection in one of two ways:

• By referencing an existing Java Agent API connection handle in the constructor of the SmApiConnection object.
• By establishing a new connection manually through the setAgentApiConnection() method.

Note: If you already have a connection to the Policy Server, you can use it to make subsequent Policy Management API or DMS API calls.

To create a connection using an existing Agent API connection

1. Create your connection object through the following constructor:

      SmApiConnection (netegrity.siteminder.javaagent.AgentAPI
                                                 agentApiConnection)
   

2. In the constructor, use agentApiConnection to pass in the handle of the existing Agent API connection—for example:

      SmApiConnection myConnection = 
                         new SmApiConnection (myAgentApiConnection);
   

   The new Java Agent API handle is a user-defined handle.

If you do not already have a default connection and you want a user-defined connection object, you can use the Agent API to create the agent object and then create the new connection, as follows:

1. Create the agent object.

   You can create an agent object based on connection parameters from either of the following sources:

   • User-defined connection parameters defined in your code—for example:

     AgentAPI agent = new AgentAPI();
     ServerDef sd = new ServerDef();
     sd.serverIpAddress = POLICY_IP;
     sd.connectionMin = CX_MIN;
     sd.connectionMax = CX_MAX;
     sd.connectionStep = CX_STEP;
     sd.timeout = CX_TIMEOUT;
     sd.authorizationPort = AZ_PORT;
     sd.authenticationPort = AUTH_PORT;
     sd.accountingPort = ACC_PORT;
     InitDef init=new InitDef(AGENT_LOGIN,SHARED_SECRET,false, sd);
     agent.init(init);
     

   Note: With SiteMinder v6.0 and later, the authorization, authentication, and accounting servers are combined into a single server process. Consequently, authorizationPort, authenticationPort, and accountingPort can all be set to the same value.

   • Connection parameters stored in an Agent configuration file.

   Note: SiteMider v4.x webagent.conf files are no longer supported by the SM API.

2. Create the new connection.

   After creating the agent object, you create the new connection in either of these ways:

   • Pass the agent object you just created into the constructor of the new SmApiConnection object—for example:

     SmApiConnection myConnection = new SmApiConnection(agent);
     

   • Call setAgentApiConnection() and pass in the agent object you just created—for example:

     SmApiConnection myConnection=new SmApiConnection(false,false);
     myConnection.setAgentApiConnection(agent);
     

   If you establish the connection in this way, the Java Agent API handle is a user-defined handle.

   If you call setAgentApiConnection() and you do not have a connection, you can establish an automatic, static connection by passing in null.

Obtain a Session

After you obtain a connection to the Policy Server, get a user or administrator session.

Note: To use the Policy Management API, you must connect as a SiteMinder Administrator.

After you obtain a session object, pass it to the Policy Management API or the DMS API through the constructor for the SmPolicyApiImpl class, or the SmDmsApiImpl class.

To obtain a session, perform one of these actions:

If you have a session specification for a user that has been authenticated, you can use that session specification. You need not obtain a new session specification.

To use an existing session, create an SmApiSession object and associate the session specification with that object.

Log in as a SiteMinder Administrator

To authenticate a SiteMinder administrator, use the login() method in the SmApiSession class of the Utilities package. This method uses the administrator’s login credentials (username and password) to authenticate the administrator. Calling this login() method obtains a session specification and returns an SmApiResult object.

The syntax of the login() method is as follows:

result=mySession.login (username,
                        password,
                        IPaddress,
                        challengeReason);

Provide a value for the challengeReason parameter as follows:

• On the administrator’s initial login, set challengeReason to 0 (no reason).
• If the initial login fails, use challengeReason in the next login() call to specify the results of the previous authentication attempt.

  To retrieve the reason value to assign to challengeReason, call getReason() in the SmApiResult object.

To obtain a new session specification for a user, use the Java Agent API to obtain a session specification. Then, create an SmApiSession object and associate the session specification with that object.

Make API Requests and Handle Results

After you establish a session, you can call the methods in your client application.

A result is a response from the Policy Server to a Java API request. Results are returned in an SmApiResult object.

Exceptions are thrown from an unexpected client-side error. An exception contains a result with additional information, such as the origin and severity of the result. To create a result object to store the results of API requests, use the constructor of the SmApiResult class in the Utilities package—for example:

SmApiResult result = new SmApiResult();

You can verify whether a request was successful by calling the method isSuccess() on the result object. The method returns true if the request was successful, or false if it was not successful.

You can compare the current result object to a specified result object by calling the equals() method.

You can use the equals() method to compare the current result object with SmApiResult constants that represent different kinds of results. For example, in the following code, the result represented by the unique constant SERVER_INVALID_PASSWORD is compared against the current result object:

InetAddress address = InetAddress.getLocalHost();
SmApiResult result = apiSession.login(usr,pwd,address,0);
boolean resultStatus =
             result.equals(SmApiResult.SERVER_INVALID_PASSWORD);

Log Trace Information

To log tracing information on the client side, use the -D option of the java tool and set the system property SMJAVASDK_LOG_INFO to true. SiteMinder logs the information to the standard output.

For example, if your Java Development Kit is on Windows and you want to trace the Policy Management API sample application, the command line would be:

java -DSMJAVASDK_LOG_INFO=true -classpath .;..\..\java\smjavasdk2.jar;
..\..\java\smjavaagentapi.jar PolicyApiSample

Javadoc Reference

This guide includes frequent references to the Javadoc, which you can access through a link on the SiteMinder bookshelf. Use the Javadoc to learn about a particular class or method. These details typically include syntax, parameters, return values, and exception information.

The description of each package, class, and interface in the Javadoc reference sometimes includes a Since heading that indicates the SiteMinder or SDK version when the component was introduced. Individual methods and fields only include a Since heading if they were added in a later version of the class or interface.

Support for Custom Code

CA supports the Software Development Kit (SDK) as part of the standard offerings. Code written by customers or partners, however, is not supported. You are responsible for the code you write. If you require assistance designing or implementing SDK-based code, contact your CA customer account team.