Programming Guides › Programming Guide for Perl › Policy Management Operations › Policy Store Object Migration › Import Realm Objects

Import Realm Objects

Some points to note about importing realm objects:

• At the South site, the exported files Data.smdif (containing the object information) and NorthEnv.cfg (containing North site configuration information) have been placed in the same directory as the import script.
• A $datamgr object is created for the import operation. The object references the two files generated during the export.
• A single Import() call imports all the exported realms and their dependencies from the Data.smdif file.

  Note that the Import() call references the target-site-specific configuration file. This file is used in place of the source-site configuration file referenced in the $datamgr object.

• Neither of the default import flags has been changed:
  • An existing realm with the same name as an imported realm will be overwritten. Call OverwriteObjects(0) to protect realms from being overwritten.
  • The realms and their dependencies are imported. You can import just the realms with IncludeDependencies(0).

Example:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminsouth", "adminpwd");
$datamgr = $session‑>CreateDataManager("Data.smdif",NorthEnv.cfg);
die "FATAL: Data manager creation failed.\n" unless($datamgr!=undef);

print "\nData manager creation was successful.";
$domain = $session‑>GetDomain("Acme North Domain");
$result=$datamgr‑>Import("SouthEnv.cfg",$domain);
print "\nResult of import: " . $result . "\n";

When importing objects from multiple data files, you need a PolicyMgtDataMgr object for each file.

Example:

The following script imports realm objects to the policy store at a company’s South site from two other sites—a North site and a West site. At the South site, the data and configuration files generated from each export are placed in the same directory as the import script. The South-site configuration file is also located there:

use Netegrity::PolicyMgtAPI;

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

$domain = $session‑>GetDomain("Acme South Domain");

#create data manager for North site file
$mNorth=$session‑>CreateDataManager("DataNorth.smdif","NorthEnv.cfg");
if ($mNorth == undef) {
   print "\nData manager creation for North site file failed.\n";
}
else {
   print "\nData manager creation for North site file successful.\n";
   #Import realms from North site file
   $result=$mNorth‑>Import("SouthEnv.cfg",$domain);
   print "\nResult of import of North site realms: ".$result."\n";
}

#create data manager for West site file
$mWest=$session‑>CreateDataManager("DataWest.smdif","WestEnv.cfg");
if ($mWest == undef) {
   print "\nData manager creation for West site file failed.\n";
}
else {
   print "\nData manager creation for West site file successful.\n";
   #Import realms from West site file
   $result=$mWest‑>Import("SouthEnv.cfg",$domain);
   print "\nResult of import of West site realms: ".$result."\n";
}

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();