Create a Client Application in Java
Complete the following procedures to create a client application with the Policy Management API or the DMS API in Java:
sm1252sp1
Complete the following procedures to create a client application with the Policy Management API or the DMS API in Java:
2
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:
- Adefaultconnection 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. - Auser-definedconnection 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
CA Single Sign-On
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, CA Single Sign-On
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
- Use the following constructor to create an API connection object:SmApiConnection (boolean bDefaultAgentConnectionboolean disableLoadBalancing)
- In the constructor, set bDefaultAgentConnection to true—for example:SmApiConnection m_defaultConnection = new SmApiConnection(true,false);
- If bDefaultAgentConnection is false, 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.
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
- Create your connection object through the following constructor:SmApiConnection (netegrity.siteminder.javaagent.AgentAPIagentApiConnection)
- 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:
- 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);The authorization, authentication, and accounting servers are combined into a single server process. Consequently,authorizationPort,authenticationPort, andaccountingPortcan all be set to the same value.CA Single Sign-Onv4.x webagent.conf files are no longer supported by the SM API.
- Connection parameters stored in an Agent configuration file.
- 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);SmApiConnection myConnection=new SmApiConnection(false,false);myConnection.setAgentApiConnection(agent);
- Call setAgentApiConnection() and pass in the agent object you just created—for example:
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.
To use the Policy Management API, you must connect as a
CA Single Sign-On
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.
If... | And... | Then... |
You have an existing session from authenticating a user. | — | Pass in the session specification for the authenticated user. |
You do not have an existing session. | You must connect asa CA Single Sign-On Administrator. | Use the method SmApiSession.login(). |
You do not have an existing session. | You want to connect as a non-Administrator. | Use the Java Agent API to obtain a session specification for the user. |
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
CA Single Sign-On
AdministratorTo authenticate a
CA Single Sign-On
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 (noreason).
- 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
CA Single Sign-On
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:
- Instantiate the AgentInstanceDef.java class.
- Call the getAgentIdFile method.If this method returns a valid configuration path, the agent instance is already accounted for in the agent discovery process.
- Call the setAgentIdFile method and provide the location of the configuration file when getAgentIdFile does not return one.
- (Optional) Call additional methods to set or get attribute information for the agent instance.
- 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);