Programming Guides › Programming Guide for Java › Using the Java APIS

Using the Java APIS

This section contains the following topics:

Purpose of the Java APIs

Installation Path

Code Samples

Policy Server Prerequisite

Java Components of the SiteMinder SDK

Java Agent API

Policy Management API

Authentication API

Authorization API

Delegated Management Services API

Utilities Package

How Java Components Fit Together

Network Architecture

Java API Flow

Log Trace Information

Javadoc Reference

Support for Custom Code

Purpose of the Java APIs

The SiteMinder SDK provides Java APIs for performing the following tasks:

• Creating SiteMinder Agents
• Creating Policy Management applications
• Creating Delegated Management Services (DMS) applications

Installation Path

The Java APIs, documentation, and samples are installed to the following location:

• UNIX platforms: <install_path>/sdk
• Windows platforms: <install_path>\sdk

<install_path> refers to the installation path where you installed the SDK software.

Code Samples

The SiteMinder SDK includes tested samples of SiteMinder client applications. The source files for these samples are located as follows:

• UNIX platforms:

  <install_path>/sdk/samples/<api-name>

• Windows platforms:

  <install_path>\sdk\samples\<api-name>

Notes on the Java samples:

• The samples use properties defined in smjsdksample.properties, located in /sdk/properties. Before you run the Java samples, modify this file with settings for your environment.
• The smjsdksample.properties file also externalizes literal strings used for logging.
• The samples smjavaagentapi and javadmsapi use the policy store created by the sample javapolicyapi. Run smjavapolicyapi before running smjavaagentapi or javadmsapi.
• All the samples use the same logging options and output format.
• When executing the Java samples on a 64-bit UNIX operating environment, note the following:
  • Use a 64-bit JVM. Running the 64-bit samples using a 32-bit JVM is not supported.
  • If you are using the file java-run.sh (in the samples/smjavaagentapi folder) remove the comment indicator before the -d64 flag. Leave this flag commented out when on a 32-bit operating environment.

Policy Server Prerequisite

You must have the SiteMinder Policy Server to run the applications and Policy Server plug-ins that you develop with the SiteMinder SDK. However, in most cases, you do not use the Policy Server to build those applications and plug-ins. The application runtime files can either be local or remote to the Policy Server.

Java Components of the SiteMinder SDK

The Java components of the SiteMinder SDK are listed in the following table:

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.

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.

Agent Discovery

Agent discovery lets SiteMinder administrators track instances of different types of agents, including agents that have been deployed over a number of years. An agent instance can be any type of agent, for example, Web agent, custom agent, or ERP agent. To come under the purview of agent discovery, the agent must be active and in communication with the Policy Server.

Only 5.x agents and later can be tracked. For agents created before r12.5, the combination of the IP address and trusted host are used to identify the agent. Any change in this combination for the same agent results in multiple entries for the same agent.

A unique GUID identifies each r12.5 agent instance, which is stored in a configuration file. Multiple agent instances cannot share a configuration file. In addition to the location of the configuration file, AgentInstanceDef.java defines parameters that specify the following attributes of an agent instance:

• Agent product type
• Agent product version
• Agent product subtype
• Agent configuration object name
• Host configuration object name

Enable Agent Discovery

When you want a custom agent to come under the purview of agent discovery, follow this process:

1. Instantiate the AgentInstanceDef.java class.
2. Call the getAgentIdFile method.

   If this method returns a valid configuration path, the agent instance is already accounted for in the agent discovery process.

3. Call the setAgentIdFile method and provide the location of the configuration file when getAgentIdFile does not return one.
4. (Optional) Call additional methods to set or get attribute information for the agent instance.
5. Call the AgentAPI.setAgentInstanceInfo method, passing in the name of your object.

The agent instance periodically sends the Policy Server a heartbeat message informing the Policy Server that the agent instance is still active.

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

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.