Programming Guides › Programming Guide for C › Policy Management API Guidance

Policy Management API Guidance

This section contains the following topics:

Policy Management API Overview

Federation API

Policy Management API Data Structures

Exported Types

Structure of a Policy Application

Functions by Category in the Policy Management API

Function Declarations for the Policy Management API

Authentication Scheme Configuration

Policy Management API Overview

The Policy Management API lets you manipulate policy objects within a SiteMinder installation. Using the Policy Management API, you can perform most of the data manipulations that are provided by the Administrative UI. You can also develop your own custom interface to SiteMinder.

Note: Before you work with the Policy Management API, be sure that you are familiar with SiteMinder concepts.

Policy Management Setup

To use the Policy Management API

1. Install the Policy Server and the SiteMinder Software Development Kit on the same machine. In the Windows environment, the Policy Server is required for running Policy Management applications. In the UNIX environment, the Policy Server is required for both building and running Policy Management applications.

   Note: You can build your Policy Management application without running the Policy Server services.

2. Use the Policy Server Management Console to configure the Policy Server so that it points to the policy store you want to access.
3. Run your Policy Management application on the machine where the Policy Server is installed and that has been configured to point to the policy store. The policy store can be on a different machine than the Policy Server.

To run your Policy Management application, you need the following files:

Windows platforms: SmPolicyApi45.dll

UNIX platforms: libsmpolicyapi45.so and libsmutilities.so, in the following location:

<siteminder_install_location>\Netegrity\SiteMinder\lib

Refer to the sample makefile before executing a UNIX build.

To build your policy application, include SmPolicyAPI45.h and link to the required shared libraries.

• Windows platforms: Link to SmPolicyAPI45.lib, located in
  <install_path>\sdk\lib\win32\
• UNIX platforms: Link to the libraries libsmpolicyapi45.so and libsmutilities.so, located as described in the previous section.

Note: Before you build policy management applications for UNIX, you must install the SiteMinder SDK on the same machine as the Policy Server.

Object Retrieval Functions

These functions retrieve information about an object from the SiteMinder policy store.

If the return code indicates success, a linked list of objects that match the request is returned. In most cases, the API returns a single item that matches the unique object identifier. If a matching object is not found, the return code indicates failure and the returned linked list pointer points to NULL.

Object retrieval functions are prefixed with Sm_PolicyApi_Get. To find the function that retrieves information for a particular object, look in the table of functions for that object.

More Information:

Functions by Category in the Policy Management API

Object Creation Functions

To create a SiteMinder object, you must fill in the appropriate data structure and call the appropriate function with a properly initialized handle. If the call is successful:

• The function returns Sm_PolicyApi_Success.
• The object is added to the SiteMinder policy store.
• The pszOid field in the corresponding object structure is set to the object identifier of the object.

Object creation functions are prefixed with either Sm_PolicyApi_Add or Sm_PolicyApi_Create.

More Information:

Functions by Category in the Policy Management API

Object Deletion Functions

These functions delete objects from the SiteMinder policy store. Only one object at a time can be deleted.

Object deletion functions are prefixed with Sm_PolicyApi_Delete or Sm_PolicyApi_Remove.

More Information:

Functions by Category in the Policy Management API

Object Associations

Some objects can be associated with or disassociated from one another-for example, Sm_PolicyApi_AddAdminToDomain() adds an administrator object to a domain, and Sm_PolicyApi_RemoveAdminFromDomain() removes an administrator object from a domain.

An "add-to" operation requires that both objects exist prior to the call and have an established association. After a "remove-from" operation, both objects still exist, but they are no longer associated with one other.

When you're looking for a function that associates or disassociates two objects, look in the category of the method that you are adding or removing. For example, the functions Sm_PolicyApi_AddAdminToDomain() and Sm_PolicyApi_RemoveAdminFromDomain() are both found in Administrator Functions.

Object Identifiers

With the introduction of nested realms, the unique identification of an object can no longer rely on a realm name. When a SiteMinder object is created, a unique object identifier (OID) is written in the pszOid field of the object's defining structure.

These functions do not return SiteMinder objects. Instead, they return an array of string pointers that contain the OIDs of SiteMinder objects. You pass in OIDs to SiteMinder Object Retrieval Functions (Sm_PolicyApi_Get...) to specify objects to retrieve.

The functions that return arrays of OIDs are:

• Sm_PolicyApi_GetDomainObjects()
• Sm_PolicyApi_GetGlobalObjects()
• Sm_PolicyApi_GetUserDirSearchOrder()

Free the memory allocated by this group of functions by calling Sm_PolicyApi_FreeMemoryEx().

Directory Search Order Functions

The following functions help you retrieve and set the search order of user directories:

• Sm_PolicyApi_GetUserDirSearchOrder() retrieves the object identifiers (OIDs) of user directory objects associated with the specified domain.
• Sm_PolicyApi_SetUserDirSearchOrder() sets the search order of the user directories in a domain. The ordered list of OIDs is specified in the pszArray string array. The user directories in this array must match in OID and number (but not order) the list of user directory OIDs that were retrieved by a call to Sm_PolicyApi_GetUserDirSearchOrder().

Performance Enhancement

By performing either of the following actions, a custom Policy Management application can reduce the time it takes to update policy store objects:

• Omit the Sm_PolicyApi_InitFlags_PreLoadCache flag in the call to Sm_PolicyApi_Init().
• Introduce a very small time delay in the custom application to ensure adequate time for cache processing before exiting.

Memory, Cache, and Agent Key Management

The following functions free memory allocated by the Policy Management API:

• Sm_PolicyApi_FreeMemory() and Sm_PolicyApi_FreeMemoryEx() free any of the linked list pointers that are returned by the API.
• Sm_AgentApi_FreeServers() frees an array of server structures allocated by Sm_AgentApi_GetConfig().
• Sm_PolicyApi_FreeString() frees memory allocated for a single string (for example, pszUseMsg and pszErrMsg strings).
• Sm_PolicyApi_FreeStringArray() frees arrays of returned strings.

Another management command, Sm_PolicyApi_ManagementCommand(), performs cache and agent encryption key management, such as:

• Flushing all caches
• Flushing users cache
• Flushing realms from the resource cache
• Changing dynamic keys
• Changing persistent keys

The type of management operation you want to perform is determined by the management command you pass to Sm_PolicyApi_ManagementCommand().

Object Scope

SiteMinder 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.

The scope of SiteMinder objects is as follows:

• Global objects include:
  • Administrators
  • Agent types
  • Agents and agent groups
  • Authentication schemes
  • Authentication/authorization maps
  • Certificate maps
  • Domains
  • ODBC query schemes
  • Password policies
  • Policies
  • Registration schemes
  • Responses
  • Rules
  • User directories
• Domain objects include:
  • Policies
  • Realms
  • Responses and response groups
  • Response attributes
  • Rules and rule groups
  • User policies