Programming Guides › Programming Guide for Perl › Policy Management Operations

Policy Management Operations

This section contains the following topics:

Initialize a Session

Create and Manage System Objects

Objects with Domain Scope

Objects with Domain Scope or Global Scope

Authorization Variables

Save Changes to Objects

Modify a Password Policy

Manage Password State

Create Responses and Response Attributes

Update Realms with a New Authentication Scheme

View Default Values for an Authentication Scheme Template

Create an Authentication Scheme

Modify the Shared Secret Rollover Policy

Write a Domain and Realm Report to a File

Disable Authentication and Authorization Event Processing

Manage Policy Server Load Distribution

Initialize a Session

When you create a session, a number of session initialization flags are set to their default values. The following table lists the initialization methods in the PolicyMgtAPI object and their default values:

Note: These methods have no effect if called after CreateSession().

Example: Initialize session operations

The following example enables all the session initialization operations that are not enabled by default. If the session is successfully initialized, the script displays the initialization flags:

use Netegrity::PolicyMgtAPI;

$username = "adminid";
$password = "adminpwd";

print "\nInitializing and connecting to PolicyMgtAPI...\n";
$policyapi = Netegrity::PolicyMgtAPI‑>New();
$policyapi‑>PreLoadCache(1);
$policyapi‑>LoadAgentTypeDictionary(1);

die "ERROR: Couldn't create session\n" unless ($session != undef);

print "Initialization settings:\n";
print "  Preload cache flag: ".$policyapi‑>PreLoadCache()."\n";
print "  Disable validation flag: " . 
                     $policyapi‑>DisableValidation()."\n";
print "  Load agent type dictionary flag: " . 
                     $policyapi‑>LoadAgentTypeDictionary()."\n";
print "  Disable audit flag: ".$policyapi‑>DisableAudit()."\n";
print "  Disable watchdog flag: " . 
                     $policyapi‑>DisableManagementWatchDog()."\n";

Create and Manage System Objects

When you initialize a connection to the Policy Server, you create a session object (PolicyMgtSession). You use the session object to create, retrieve, and delete the system-level objects that are listed in the System tab of the SiteMinder Administration window.

System objects (also called global objects) have global scope—that is, they are visible across all domains in the policy store. The system objects you can create from session objects include:

• Administrators
• Agents and agent types
• Authentication schemes
• Authentication and authorization maps
• Domains
• ODBC query schemes
• Password policies
• Registration schemes
• User directories

Create Agent Objects

Agent objects are system objects with global scope. The following example uses a session object to create and configure an agent, then prints out all the agent names that are configured in the policy store:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");

$ip="127.0.0.1";
$secret="oursecret";

$agentType=$session‑>GetAgentType("Web Agent");
$session‑>CreateAgent("agent1",$agentType,"",$ip,$secret);

@agents=$session‑>GetAllAgents();
foreach $agent(@agents) {
   print $agent‑>Name()."\n";
}

Note: This example creates a v4.x agent. To create a v5.x or v6.x agent, do not specify a shared secret.

View and Modify Object Properties

After you create an object (or after an object is created in the Administrative UI), you can view and modify the individual properties of the created object by calling the object’s get and set methods.

Typically, an object’s get and set method names represent the name of the property being retrieved or modified, and the methods take a single optional argument. If you supply the argument, you set the property for the object. If you omit the argument, you retrieve the property value without altering it. The method returns the new or existing property value.

In the following example, each user directory is checked for its Maximum Results property—that is, the value that specifies the maximum number of search results to return after a directory search. If the retrieved number is not 25, the script sets the property to 25:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");

$max="25";

@userdirs=$session‑>GetAllUserDirs();
foreach $userdir(@userdirs) {
   print "\nMax results for directory " . $userdir‑>Name()."\n";
   if ($userdir‑>MaxResults() != $max) {
      print "  Updating from " . $userdir‑>MaxResults()." to " .
                                                      $max . "\n";
      $userdir‑>MaxResults($max);
   }
   else {
      print "  Max results are correct.\n";
   }
}

Objects with Domain Scope

One of the system objects you can create is a domain object (PolicyMgtDomain). Although a domain object itself has global scope, the objects you create and retrieve through a domain object have domain scope—that is, they are visible only within the domain and cannot be shared between domains.

Domain objects are listed in the Domains tab of the SiteMinder Administration window.

Objects with domain scope include:

• Policies
• Realms
• Responses and response attributes
• Rules
• User Policies

Retrieve One Object to Create Another

Sometimes, before you can manipulate an object, you must retrieve a higher-level object. That is the case with objects having domain scope.

Here is an example of creating a policy with domain scope. Note that before the policy object can be created, you retrieve the domain object where the policy will reside:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");
$domain=$session‑>GetDomain("engineering");
$policy=$domain‑>CreatePolicy("Payroll Policy");
if($policy == undef) {
   print "Couldn't create the policy.\n";
}
else {
   print "Successfully created policy " . $policy‑>Name() . ".\n";
}

Manage an Object’s Properties

You view and set properties for an object with domain scope by using the object’s get and set methods, just as you do for objects with global scope.

Sometimes, the value of an object’s property is not a string or numeric value, but another object. For example, with policies, you add rules and users to the policy, and you set responses for the rules in the policy. All of these values are provided as objects.

Example: Add objects to a policy

In the following example, the policy is configured with a user, rule and response:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");
$domain=$session‑>GetDomain("engineering");
$policy=$domain‑>GetPolicy("Payroll Policy");

# Add a user to the policy
$userdir=$session‑>GetUserDir("Acme North Directory");

@users=$userdir‑>LookupEntry("uid=ppaycheck");
foreach $user(@users) {
   if ($user‑>GetPath()=="uid=ppaycheck,ou=HR,o=security.com") {
      $userResult=$policy‑>AddUser($user);
      $thisUser=$user;
   }
}
if ($userResult != 0) {
   print "Error adding user to policy.\n";
}

# Add a rule to the policy
$realm=$domain‑>GetRealm("HR");
$rule=$realm‑>GetRule("Payroll Rule");
$ruleResult=$policy‑>AddRule($rule);
if ($ruleResult != 0) {
   print "Error adding rule to policy.\n";
}
else
{
   # Set a response for the rule
   $response=$domain‑>GetResponse("Welcome to Payroll");
   $respResult=$policy‑>SetResponse($rule,$response);
   if ($respResult != 0) {
      print "Error adding response to policy.\n"
   }
}

print "\nAdded these objects to the policy:\n";
print "  User DN: ".$thisUser‑>GetPath()."\n" unless $userResult!=0;
print "  Rule: ".$rule‑>Name()."\n" unless $ruleResult!=0;
print "  Response: ".$response‑>Name()."\n" unless $respResult!=0;

Objects with Domain Scope or Global Scope

Some objects can be created with either domain scope or global scope. Those objects are:

• PolicyMgtPolicy
  • Domain: PolicyMgtDomain‑>CreatePolicy()
  • Global: PolicyMgtSession‑>CreateGlobalPolicy()
• PolicyMgtResponse
  • Domain: PolicyMgtDomain‑>CreateResponse()
  • Global: PolicyMgtSession‑>CreateGlobalResponse()
• PolicyMgtRule
  • Domain: PolicyMgtRealm‑>CreateRule()
  • Global: PolicyMgtSession‑>CreateGlobalRule()
• PolicyMgtGroup
  • Domain: PolicyMgtDomain‑>CreateResponseGroup()
  • Domain: PolicyMgtDomain‑>CreateRuleGroup()
  • Global: PolicyMgtSession‑>CreateAgentGroup()

The following table compares policy, response, and rule objects when they have domain scope and global scope:

Authorization Variables

An authorization variable is a dynamic object that is resolved to a value during an authorization request. The variables appear within an active expression defined for a policy or a response.

Authorization variables are used as follows:

• With policies, variables are used as authorization constraints. When a user requests access to a resource, and the resource contains an active expression that includes one or more variables, the variables are resolved to values that pertain to the user. The values are then evaluated and used in the decision about whether to authorize the user.

  For example, suppose a policy that protects a bank’s credit card application form contains an active expression with a Credit Rating variable and a Salary variable. When a user attempts to access the form, the user is authorized only if his credit rating and salary meet or exceed the minimum values for these variables.

• With responses, variables are used as return values. For example, a response attribute might be configured to return a transaction’s tracking number obtained from a remote Web Service.

To use authorization variables, you must have the SiteMinder Option Pack installed.

Configure a Variable for a Particular Variable Type

You create and configure a variable by calling CreateVariable() for a PolicyMgtDomain object.

One of this method’s arguments is definition. The value of this argument can be a simple string or a set of XML elements, depending on the variable type. Here are the SiteMinder variable types and a description of the definition argument for each type:

• Post

  The definition argument contains the name of a field on an HTML form. In a POST action, the variable value is derived from the value assigned to the field.

• RequestContext

  The definition argument contains the following XML code:

  <RequestContextVariableDef>
     <ItemName></ItemName>
  </RequestContextVariableDef>
  

  The variable value depends upon which of the following attribute names appears within the ItemName element:

  • Action. The variable value is the type of action specified in the request (for example, GET or POST).
  • Resource. The variable value is the target resource (for example, /directory_name/).
  • Server. The variable value is the full server name specified in the request (for example, server.company.com).
• Static

  The definition argument contains the actual value that will be compared against the user-supplied data at runtime. For example, a Static variable of return type VAR_RETTYPE_DATE might be assigned the string value 2004-01-01. During authorization, this assigned date is compared to a user-supplied date.

• UserContext

  The definition argument contains some or all of the following XML code:

  <UserContextVariableDef>
     <ItemName></ItemName>
     <PropertyName></PropertyName>
     <DN></DN>
     <BufferSize></BufferSize>
  </UserContextVariableDef>
  

  The variable value is based on an attribute of a user directory connection (such as session ID) or on the contents of the user directory (such as user name). The name of the attribute upon which the variable value is based appears in the XML element ItemName.

  The elements PropertyName, DN, and BufferSize are only used as follows:

  • When ItemName contains DirectoryEntryProperty, elements PropertyName, DN, and BufferSize are used.
  • When ItemName contains UserProperty, elements PropertyName and BufferSize are used.

  For a complete list of the valid ItemName values, see the description of CreateVariable() in the Policy Management API Reference (PolicyMgtAPI.htm).

• WebService

  The definition argument contains the following basic XML structure:

  <WebServiceVariableDefn xmlns:NeteWS=
                         "http://www.netegrity.com/2003/SM6.0";>
     <NeteWS:RemoteURL></NeteWS:RemoteURL>
     <NeteWS:SSL/>
        <NeteWS:RemoteMethod></NeteWS:RemoteMethod>
        <NeteWS:ResultQuery></NeteWS:ResultQuery>
        <NeteWS:AuthCredentials>
           <NeteWS:Username></NeteWS:Username>
           <NeteWS:Password></NeteWS:Password>
           <NeteWS:Hash></NeteWS:Hash>
        </NeteWS:AuthCredentials>
        <NeteWS:Document>
           <SOAP:Envelope xmlns:SOAP=
                   "http://schemas.xmlsoap.org/soap/envelope/";>
              <SOAP:Header></SOAP:Header>
              <SOAP:Body></SOAP:Body>
           </SOAP:Envelope>
        </NeteWS:Document>
  </WebServiceVariableDefn>
  

  To retrieve a variable value from a Web Service, the Policy Server sends the Web Service a SOAP request document as specified in the definition argument, and then extracts the variable value from the SOAP response.

The following table describes the XML elements used to configure a WebService variable:

Note: The XML element structures shown above are formatted for legibility. The XML string supplied through the definition argument should not be formatted with spaces, tabs, and return characters. For example, a RequestContext variable for a Resource attribute would be passed in definition as follows:

<RequestContextVariableDef><ItemName>Resource</ItemName></RequestContextVariableDef>

The following information is required in a call to CreateVariable():

• The user-defined variable name.
• The variable type—for example, Static or ResourceContext.
• The variable definition.
• The data type of the variable value. Valid data type values are:
  • VAR_RETTYPE_BOOLEAN
  • VAR_RETTYPE_NUMBER
  • VAR_RETTYPE_STRING
  • VAR_RETTYPE_DATE

If you have both the optional TransactionMinder product and the Option Pack installed, you can use the following types of variables:

• SAMLAssertion
• Transport
• XMLAgent
• XMLBody
• XMLEnvironment

You cannot create variables of these types with the Command Line Interface. You can only do so using the Administrative UI.

Example: Create a ResourceContext Variable

The following example creates the variable MyVar as a ResourceContext variable. The variable value is the resource that is being protected (for example, /directory_name/):

use Netegrity::PolicyMgtAPI;

$pmgtapi=Netegrity::PolicyMgtAPI‑>New();
$session=$pmgtapi‑>CreateSession("adminid", "adminpwd");

$dom=$session‑>GetDomain("MyDomain");
$varName="MyVar";
$varType=$session‑>GetVariableType("RequestContext");
$varDef="<RequestContextVariableDef><ItemName>Resource</ItemName>

</RequestContextVariableDef>";

$vr=$dom‑>CreateVariable($varName,$varType,$varDef,

VAR_RETTYPE_STRING);

if ($vr==undef) {
	print "Create operation failed.";
	}
else {
	print "Created variable " . $varName;
	}

Save Changes to Objects

When you make changes to an instance of the following objects, you must call the object’s Save() method to save the changes. Call Save() once after making any changes to these objects:

• PolicyMgtAffiliate
• PolicyMgtAuthScheme
• PolicyMgtPwdPolicy
• PolicyMgtSAMLAffiliation
• PolicyMgtSAMLServiceProvider
• PolicyMgtSharedSecretPolicy

The following example changes properties for an authentication scheme object:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");
$authscheme=$session‑>GetAuthScheme("HTML Authentication");

#Specify the attribute list
$attrList="AL=PASSWORD,SSN,age,zipcode;";
#Specify the new credentials collector
$target="http://my.server.com/siteminderagent/forms/customlogin.fcc";

#Make the changes and save them
$authscheme‑>ProtectionLevel(10);
$authscheme‑>CustomParam($attrList.$target);
$authscheme‑>Save();

Modify a Password Policy

Suppose a company has different password policies defined at different sites, and it decides to standardize certain password policy requirements. The following script can be executed for each site to set the new password policy definitions:

use Netegrity::PolicyMgtAPI;

$policymgtapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policymgtapi‑>CreateSession("adminid", "adminpwd");

@pwdpols=$session‑>GetAllPwdPolicies();
foreach $pwdpol(@pwdpols) {
   $pwdpol‑>Description("Standardized settings 4/15/02");
   print "\n\nPwd Policy: " . $pwdpol‑>Name();
   print "\nUpdated the following settings:";
   print "\n  Minimum length:\t".$pwdpol‑>PwdMinLength(6);
   print "\n  Maximum length:\t".$pwdpol‑>PwdMaxLength(18);
   print "\n  Minimum digits:\t".$pwdpol‑>PwdMinNumbers(3);
   print "\n  Allowable failures:\t".$pwdpol‑>MaxLoginFailures(3);
   print "\n  Days before reuse:\t".$pwdpol‑>PwdReuseDelay(360);
   print "\n  Changes before reuse:\t".$pwdpol‑>PwdReuseCount(6);
   $pwdpol‑>Save();
}

Manage Password State

Password state refers to activities relating to a given user’s password—for example, the last time the password was changed, and the last time the password was used to log in the user.

To retrieve an existing PolicyMgtUserPasswordState object for a user, or to set a new password state object with any attribute changes, call PolicyMgtUser‑>UserPasswordState().

The table that follows lists the password state attributes you can access for a given user, and the method used to set or retrieve an attribute value. All methods are in the object PolicyMgtUserPasswordState, unless otherwise noted.

If you change a password state attribute, the change applies to the current password state object only. To apply the change to a password state object that may be subsequently retrieved, pass the current password state object in a call to PolicyMgtUser‑>UserPasswordState(). This method sets a new password state object containing the attribute values passed into the method.

For example, the code fragment below performs the following operations:

1. Retrieves the password state object, $passwordstate, for the current user, $user[0].
2. Sets the login failures attribute to 3 in this instance of the password state object.
3. Calls UserPasswordState() to clear the user’s password history and set a new password state object for the user with the new history and login failures attributes.

   $passwordstate = $user[0]‑>UserPasswordState();
   $passwordstate‑>LoginFailures(3);
   $user[0]‑>UserPasswordState($passwordstate, 1);
   

Create Responses and Response Attributes

The following script creates a response and response attribute. Note that GetAgentType() needs to be called to retrieve an agent type object for the call to CreateResponse():

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");

$domain = $session‑>GetDomain("Acme North Domain");
$agenttype=$session‑>GetAgentType("Web Agent");
$response=$domain‑>CreateResponse("Welcome to Payroll",$agenttype);
if ($response==undef) {
   print "\nCouldn't create the response.";
}
else {
   $attr=$response‑>CreateAttribute("WebAgent-HTTP-Cookie-Variable",
                                    "cookiename=mycookie");
   if ($attr==undef) {
      print "\nCouldn't create attribute for ".$response‑>Name();
   }
   else {
      print "\nCreated response " . $response‑>Name();
      print "\nCreated attribute " . $attr‑>GetValue();
   }
}

Update Realms with a New Authentication Scheme

The following example assigns the authentication scheme HTML Authentication to all the realms in the domain Acme North Domain:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");

$domain = $session‑>GetDomain("Acme North Domain");
$authscheme=$session‑>GetAuthScheme("HTML Authentication");

@realms=$domain‑>GetAllRealms();
print "Updating these realms to auth scheme ".$authscheme‑>Name();
foreach $realm(@realms) {
   $name=$realm‑>Name();
   if ($realm‑>AuthScheme($authscheme)==undef) {
      print "\n  Couldn't update realm " . $name;
   }
   else {
      print "\n  Realm ". $name;
   }
}

View Default Values for an Authentication Scheme Template

The following script displays the default values for the authentication scheme template HTML Form Template.

Creating an authentication scheme is not necessary. The script uses GetAuthScheme() to retrieve an authentication scheme object for the template, then prints the objects’s default properties:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");

#Retrieve the object for the authentication scheme template
$template=$session‑>GetAuthScheme("HTML Form Template");

print "\nDefault values for template " . $template‑>Name();
print "\n  Type:\t" . $template‑>Type()‑>Name();
print "\n  Description:\t" . $template‑>Description();
print "\n  Protection level:\t" . $template‑>ProtectionLevel();
print "\n  Library:\t" . $template‑>CustomLib();
print "\n  Parameter:\t" . $template‑>CustomParam();
print "\n  Shared secret:\t" . $template‑>CustomSecret();
print "\n  Is template?:\t" . $template‑>IsTemplate();
print "\n  Is used by admin?:\t" . $template‑>IsUsedByAdmin();
print "\n  Save credentials?:\t" . $template‑>SaveCredentials();
print "\n  Is Radius:\t" . $template‑>IsRadius();
print "\n  Ignore pwd ck?:\t" . $template‑>IgnorePwd();

Create an Authentication Scheme

When you create an authentication scheme, you base the scheme on an authentication scheme template. To do so, you first retrieve an existing template and then specify the template object in the call to CreateAuthScheme().

The following example creates an authentication scheme based on the template HTML Form Template and accepts all defaults:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");

#Retrieve the object for the authentication scheme template
$template=$session‑>GetAuthScheme("HTML Form Template");

#Create the authentication scheme
$scheme=$session‑>CreateAuthScheme("HTML Authentication",$template);
if ($scheme == undef) {
   print "\nCouldn't create the authentication scheme.";
}
else {
   print "\nCreated authentication scheme ".$scheme‑>Name();
}

Modify the Shared Secret Rollover Policy

A shared secret is a text string known only to a trusted host and the policy store domain where the host is registered. The shared secret is used to authenticate the identity of the trusted host when it makes a secure connection to the Policy Server.

The shared secret rollover feature provides a mechanism to periodically change the shared secret automatically.

Using the Scripting Interface for Perl, you can:

• Call GetSharedSecretPolicy() to retrieve an existing shared secret rollover policy object.
• Modify the retrieved PolicyMgtSharedSecretPolicy object as follows:
  • Modify the rollover frequency. This setting specifies how often rollover should occur over a given rollover period (see the next item).
  • Modify the rollover period (hourly, daily, weekly, monthly). For example, with a rollover frequency of 3 and a daily rollover period, the shared secret is automatically changed every three days.
  • Enable or disable the rollover feature. If the shared secret rollover policy is enabled, rollover must also be enabled for any trusted host whose shared secret needs to be synchronized with the rollover policy’s shared secret. You can enable rollover for a trusted host object by calling RolloverEnabled().

Write a Domain and Realm Report to a File

The following script writes the names of all policy store domains and top-level realms to a text file:

use Netegrity::PolicyMgtAPI;

$destFile="DomainsRealms.txt";
open(DEST,">".$destFile) || die "Open file error: $!";
print DEST "Domains and Domain Realms for Acme North Site\n";
print DEST "Printed " . scalar(localtime)."";

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");

@domains=$session‑>GetAllDomains();
foreach $domain(@domains) {
   print DEST "\n\nDomain " . $domain‑>Name() . ":";
   @realms=$domain‑>GetAllRealms();
   foreach $realm(@realms) {
      print DEST "\n  Realm " . $realm‑>Name();
   }
}

print "\nDomain and realm report written to " . $destFile."\n";

Disable Authentication and Authorization Event Processing

The following script checks all the rules for each realm in the policy store. If no rules in a realm are triggered by authentication events, the script then checks whether authentication event processing is enabled for the realm. If it is, the script disables authentication event processing for the realm. The script performs the same checks for authorization events.

To simplify the example, realms in the domains are known not to have child realms.

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");

$auAction=0; # Initialize flag for authentication actions
$azAction=0; # Initialize flag for authorization actions
$auChange="";# Realms with a changed auth event processing property
$azChange="";# Realms with a changed az event processing property

@domains=$session‑>GetAllDomains();
foreach $domain(@domains) {
   @realms=$domain‑>GetAllRealms();
   foreach $realm(@realms) {
      @rules=$realm‑>GetAllRules();
      foreach $rule(@rules) {
         if ($rule‑>Action()=~/OnAuth./ ) {
            $auAction=1;
         }
         if ($rule‑>Action()=~/OnAccess./ ) {
            $azAction=1;
         }
      }
      if($auAction==0) {
         if($realm‑>ProcessAuEvents()==1) {
            $realm‑>ProcessAuEvents(0);
            $auChange=$auChange.$domain‑>Name().": ";
            $auChange=$auChange.$realm‑>Name()."\n";
         }
      }
      else { $auAction=0; }
      if($azAction==0) {
         if($realm‑>ProcessAzEvents()==1) {
            $realm‑>ProcessAzEvents(0);
            $azChange=$azChange.$domain‑>Name().": ";
            $azChange=$azChange.$realm‑>Name()."\n";
         }
      }
      else { $azAction=0; }
   }
}

if ($auChange ne "") {
   print "Stopped auth event processing for these realms:\n";
   print $auChange . "\n\n";
}
if ($auChange ne "") {
   print "Stopped az event processing for these realms:\n";
   print $azChange . "\n";
}

Manage Policy Server Load Distribution

To help prevent service interruptions, SiteMinder includes a failover feature. If the primary Policy Server fails and failover is enabled, a backup Policy Server takes over policy operations. Beginning with SiteMinder v6.0, failover can occur not only between Policy Servers, but between groups, or clusters, of Policy Servers.

The cluster functionality also improves server performance by providing dynamic load balancing between the servers in a cluster. With dynamic load balancing, policy operations are automatically distributed between the available servers in a cluster according to the performance capabilities of each server.

A host configuration can be associated with one or more Policy Servers, or with one or more clusters of Policy Servers, depending on how you define your host configuration object:

• Clustered servers
  • Call AddCluster() for each cluster to create in the host configuration.
  • In the PolicyMgtCluster object returned from AddCluster(), call AddServer() to populate the cluster with servers.

  Behavior: Failover occurs between clusters of servers if multiple clusters are defined. Also, requests to servers within a cluster are sent according to the improved performance-based load-balancing techniques introduced with Agent API v6.0.

• Non-clustered servers
  • Call AddServer() for each non-clustered server to create in the host configuration.

  Behavior: Behavior is the same as in v5.x installations—that is, you can enable failover among the servers associated with a host configuration (set EnableFailover() to 1), or you can enable round-robin behavior among the servers (set EnableFailover() to 0).

  When round-robin behavior is enabled, the improved performance-based load-balancing techniques introduced with Agent API are used.

Note: You cannot mix clustered and non-clustered servers in a host configuration.

Cluster Configuration

A cluster is stored in a host configuration object. Cluster failover occurs according to the following configuration values set in PolicyMgtHostConfig:

• Failover threshold. The minimum percentage of servers within a cluster that must be available for Policy Server requests. If the number of available servers falls below the threshold, failover to the next cluster occurs.

  The failover threshold percentage applies to all clusters associated with the host configuration object.

  To determine the number of servers that the percentage represents in any given cluster, multiply the threshold percentage by the number of servers in the cluster, rounding up to the next highest integer. For example:

  • With a 60-percent failover threshold for a cluster of five servers, failover to the next cluster occurs when the number of available servers in the cluster falls below 3.
  • With a 61-percent failover threshold for the same cluster, failover occurs when the number of available servers falls below 4.

  Set through: FailoverThreshold().

• Server timeout. The maximum time an agent will wait for a response from a server. If the wait time exceeds the server timeout value, the server is considered inactive, and failover to the next server occurs.

  If a server timeout occurs within a cluster, and the timeout causes the cluster’s failover threshold to be exceeded, failover to the next cluster occurs.

  Set through: RequestTimeout().

• Sequence of cluster failover. When cluster failover occurs, SiteMinder sends subsequent Policy Server requests to the next cluster in the cluster sequence. Cluster sequence is determined by the order of cluster objects in the cluster array.

  Add clusters through: AddCluster(). The newly added cluster is added to the end of the cluster array.

  Retrieve the cluster array through: GetAllClusters().

  The order in which you add clusters to a host configuration object determines the failover sequence. The first cluster you add (that is, the first cluster in the cluster array) is the primary cluster. This is the cluster that is used as long as the number of available servers in the cluster does not fall below the failover threshold. If there are not enough available servers in the primary cluster, failover to the next cluster occurs—that is, to the second cluster that was added to the host configuration object. If that cluster also fails, failover to the third cluster added to the host configuration object occurs, and so on.

When All Clusters Fail

If the number of available servers falls below the failover threshold in all clusters within a host configuration, policy operations do not stop. Requests are sent to the first cluster in the cluster sequence that has at least one available server.

For example, suppose a host configuration has two clusters—C1 containing three servers, and C2 containing five servers. The failover threshold for the host configuration is set at 60 percent. The following table shows the minimum number of servers that must be available within each cluster:

If the number of available servers falls below the threshold in each cluster, so that C1 has no available servers and C2 has just two, the next incoming request will be dispatched to a C2 server with the best response time. After at least two of the three C1 servers are repaired, subsequent requests are load-balanced among the available C1 servers.

Agent API v6 is backwards-compatible with Agent API v5, allowing complete interoperability between v5/v6 agents and the v5/v6 Agent APIs.

Example: Create a host configuration

The following code creates a host configuration object and adds a number of clusters and servers:

use Netegrity::PolicyMgtAPI;

# Initialize the Policy Management API and create a Host Config object.
$pmgtapi = Netegrity::PolicyMgtAPI‑>New();
$session = $pmgtapi‑>CreateSession("SiteMinder", "password");
$hostconf = $session‑>CreateHostConfig("host", "description",
                                              false, 2, 2, 1, 30);
# Add two non-cluster servers. The Az, Auth and Acct ports are
# specified.
$hostconf‑>AddServer("1.1.1.1", 44443, 44442, 44441);
$hostconf‑>AddServer("2.2.2.2", 44443, 44442, 44441);

# Add two clusters with two servers in each cluster. One Policy
# Server port number is specified.
$clusterconf1 = $hostconf‑>AddCluster();
$clusterconf1‑>AddServer("1.1.1.1", 44443);
$clusterconf1‑>AddServer("2.2.2.2", 44443);

$clusterconf2 = $hostconf‑>AddCluster();
$clusterconf2‑>AddServer("3.3.3.3", 44443);
$clusterconf2‑>AddServer("4.4.4.4", 44443);

# Print configuration of all non-cluster servers in the Host
# Config object
@servers = $hostconf‑>GetAllServers();
foreach $server (@servers) {
	$address = $server‑>GetServerAddress();
	@ports = $server‑>GetServerPort();
	print("Server: $address,@ports[0],@ports[1],@ports[2]\n");
}

# Print all cluster servers
@clusters = $hostconf‑>GetAllClusters();
foreach $cluster (@clusters) {
	$num++;
	foreach $server ($cluster‑>GetAllServers()) {
	$address = $server‑>GetServerAddress();
	$port = $server‑>GetServerPort();
	print("Cluster $num Server: $address,$port\n");
}
}

# Remove all clusters and non-cluster servers from host configuration
$hostconf‑>RemoveAllClusters();
$hostconf‑>RemoveAllServers();