Programming Guides › Programming Guide for Java › Policy Management API

Policy Management API

This section contains the following topics:

About Policy Management

Policy Management Setup

Required JAR File

Policy Store Objects

Write a Policy Management Application

Administrator Methods

Agent Methods

Agent Configuration Object Methods

Authentication and Authorization Map Methods

Authentication Scheme Methods

Certificate Map Methods

Domain Methods

General Object Methods

Group Methods

Host Configuration Object Methods

ODBC Query Scheme Methods

Password Policy Methods

Policy Methods

Policy Migration Methods

Realm Methods

Response Methods

Root Configuration Methods

Rule Methods

Self-Registration Methods

Trusted Host Object Methods

User Directory Methods

User Policy Methods

Utility Methods

Object Associations

Add Objects to the Policy Store

Retrieve Objects from the Policy Store

Delete Objects from the Policy Store

Authentication Scheme Configuration

Performance Consideration

About Policy Management

Policy management consists of creating, deleting, and modifying policy objects within a SiteMinder policy store. Through the Policy Management API, you can perform most of the data manipulations that you can perform through the native Policy Server User Interface. For example, you can write a client application that allows administrators to perform tasks such as:

• Creating a policy domain
• Creating an Agent object
• Creating an Agent configuration object
• Creating a host configuration object
• Registering a trusted host
• Creating a SiteMinder user directory object
• Creating an authentication scheme object
• Creating an administrator
• Creating a realm
• Adding a realm to a policy domain
• Creating a rule
• Creating a response
• Creating a policy
• Adding a user or group to a policy
• Adding a rule to a policy
• Setting responses for rules in a policy
• Migrating an entire policy store or an individual policy domain remotely

Policy Management Setup

To run applications built with the Policy Management API:

• Use the Policy Server Management Console to configure the Policy Server so that it points to the policy store you want to access.
• Run your Policy Management application on the same machine as the Policy Server or on a machine that has network access to the Policy Server.

Note: If an application built with the Policy Management API runs on the same machine as the Policy Server, the application must run as the same user who installed the Policy Server (for example, smuser on UNIX platforms).

Required JAR File

The JAR file smjavasdk2.jar is required for building and running Policy Management applications. The JAR file is stored in the following locations:

• Windows platforms:

  <install_path>\sdk\java

• UNIX platforms:

  <install_path>/sdk/java

Policy Store Objects

Interface SmPolicyApi is implemented by the class SmPolicyApiImpl. Use this class as the starting point for the Policy Management API. Each policy store object is associated with a class in the Policy Management API. You create and manage policy store objects through the methods in an object’s class.

Policy store objects can be classified according to scope:

• Domain objects are visible only within the domain. They cannot be shared between domains.
• Global objects are visible across all domains.

  Global objects are sometimes called system objects.

Global objects include:

• Administrators
• Agent types
• Agents and agent groups
• Agent Configuration objects
• Host Configuration objects
• Trusted Hosts
• Authentication schemes
• Authentication/authorization maps
• Certificate maps
• Domains
• ODBC query schemes
• Password policies
• Registration schemes
• User directories

Domain objects include:

• Policies
• Realms
• Responses and response groups
• Response attributes
• Rules and rule groups
• User policies

When you are working in the Policy Server user interface, you will see most of the above objects listed in the System and Domain tabs of the SiteMinder Administration window.

Note: Descriptions in the Javadoc reference specify whether an object has global scope or domain scope.

Write a Policy Management Application

To write a Policy Management application

1. Establish a Connection to the Policy Server
2. Obtain a Session Object
3. Pass in the Session Object
4. Make Policy Management API Requests
5. Terminate the Administrator Session

The SiteMinder SDK contains a sample of how to use the classes and methods in the Java Policy Management API.

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.

Obtain a Session Object

A session object is obtained when a user or administrator successfully logs in. In this case, an administrator login is required, since only administrators can perform policy management.

To log in a SiteMinder administrator and establish an administrator session, call the login() method in the SmApiSession class of the Utilities package.

Once login is successful, the session object will hold a valid administrator session specification.

Pass in the Session Object

After obtaining a valid session, create a Policy Management API object by passing the session to the constructor of the SmPolicyApiImpl class—for example:

SmPolicyApi policyApi = new SmPolicyApiImpl (apiSession);

In the example, policyApi is the new Policy Management API object and apiSession is the session obtained when the administrator successfully logged in.

Make Policy Management API Requests

After you obtain a session object and create a Policy Management API object, you are ready to make Policy Management requests. Most of the methods in the Policy Management API are categorized according to the SiteMinder object that a given method acts upon—for example, agents, policies, and rules.

There is also a Utilities category for methods that perform services, such as cache and encryption key management. Use these categories to help you find a particular Policy Management API method to use in your custom policy management applications.

Note: The methods in the policyapi package can only be called from a Siteminder administrator session.

Terminate the Administrator Session

When you are finished making Policy Management API requests, log out the administrator by calling the logout() method in the SmApiSession class of the Utilities package.

Important! After you have called the logout() method, the connection handle becomes invalid. Do not reference it again.

Administrator Methods

Unless otherwise specified, the following methods are in the class SmPolicyApiImpl. The following methods act on administrator objects. You create an administrator object by instantiating SmAdmin.

Agent Methods

Unless otherwise specified, the methods listed in this table are in the class SmPolicyApiImpl. The following methods act on agent objects. You create an agent object by instantiating SmAgent.

Agent Configuration Object Methods

Unless otherwise specified, the methods listed in this table are in the class SmPolicyApiImpl. The following methods act on agent configuration objects. You define an agent configuration object by instantiating SmAgentConfig.

Authentication and Authorization Map Methods

Unless otherwise specified, the methods listed in this table are in the class SmPolicyApiImpl. The following methods act on authentication and authorization directory mapping objects. You create an authentication and authorization directory mapping object by instantiating SmAuthAzMap.

Authentication Scheme Methods

Unless otherwise specified, the methods listed in this table are in the class SmPolicyApiImpl. The following methods act on authentication schemes. You create an authentication scheme by instantiating SmScheme.

Certificate Map Methods

Unless otherwise specified, the methods listed in this table are in the class SmPolicyApiImpl. The following methods act on certificate mapping objects. You create certificate mapping objects by instantiating SmCertMap.

Domain Methods

Unless otherwise specified, the methods listed in this table are in the class SmPolicyApiImpl. The following methods act on domain objects. You create domain objects by instantiating SmDomain.

General Object Methods

Unless otherwise specified, the methods listed in this table are in the class SmPolicyApiImpl. The following methods act on multiple types of objects.

Group Methods

Unless otherwise specified, the methods listed in this table are in the class SmPolicyApiImpl. The following methods act on group objects. Group objects are created with SmAgentGroup (for agent groups), SmResponseGroup (for response groups), or SmRuleGroup (for rule groups).

Host Configuration Object Methods

Unless otherwise specified, the methods listed in this table are in the class SmPolicyApiImpl. The following methods act on host configuration objects. You define a host configuration object by instantiating SmHostConfig.

ODBC Query Scheme Methods

Unless otherwise specified, the methods listed in this table are in the class SmPolicyApiImpl. The following methods act on ODBC Query schemes. You create ODBC Query schemes by instantiating SmODBCQuery.

Password Policy Methods

Unless otherwise specified, the methods listed in this table are in the class SmPolicyApiImpl. The following methods act on password policy objects. You create password policy objects by instantiating SmPasswordPolicy.

Policy Methods

The following methods act on policy and policy link objects. A policy link is an association of a policy, a rule, and optionally, a response. Unless otherwise specified, these methods are in the class SmPolicyApiImpl.

Policy objects are created with SmPolicy. Policy link objects are created with SmPolicyLink.