Programming Guides › Programming Guide for Perl › Agent Operations

Agent Operations

This section contains the following topics:

Resource Protection

When a user attempts to log into a site and access a protected resource, the agent typically needs to answer the following questions:

Is the requested resource protected?
Can the user be authenticated for login?
Is the user authorized to access the resource?

The following script illustrates how you can use the Agent API to address and respond to these basic agent questions:

use Netegrity::AgentAPI;

#Define script variables
$agent = "agent1";
$secret = "oursecret";
$ip = "127.0.0.1";
$respath = "/mysite/hr/payroll.htm";
$username = "userid";
$pwd = "userpwd";

print "\nStep 1. Connecting to Policy Server...\n";
$agentapi = Netegrity::AgentAPI‑>New($agent, $secret);
$serverconfig = $agentapi‑>AddServerConfig($ip);
$status=$agentapi‑>Connect();
die "FATAL: Connect() failed with error code " .
                         $status unless($status==SM_AGENTAPI_YES);

$resource = $agentapi‑>GetResource($respath);  
print "\nStep 2. Is the resource protected?\n";
if ($resource‑>IsProtected == SM_AGENTAPI_YES) {
   print "Resource ".$respath." is protected.\n\n";

   print "\nStep 3. User login...\n";
   $user = $agentapi‑>CreateUser($username, $pwd);
   print "Logging in user ".$user‑>Name().".\n";
   $status = $user‑>Login($resource);
   if($status==SM_AGENTAPI_YES) {
      print $user‑>Name() . " logged in successfully!\n\n";

      print "\nStep 4. User authorized for the resource?\n";
      $status = $user‑>IsAuthorized($resource);
      if($status==SM_AGENTAPI_YES) {
         print $user‑>Name()." is authorized for " .
                                                $respath . "\n\n";
      }
      else {
         print $user‑>Name()." is not authorized for " .
                                                $respath . "\n\n";
      }
   }
   else {
      print "Couldn't log in user " . $username . ".\n\n";
   }
}
else {
      print "Resource ".$respath." is not protected.\n\n";
}

Responses and Response Attributes

After an agent issues a request through a call to Login() or IsAuthorized(), a response to the request is returned. The response is returned whether or not the user is authorized.

With the returned response object, you can retrieve the following Agent API objects:

Session object. The session object lets you retrieve session information such as session ID and timeout values.
Response attribute object. The Policy Server uses response attributes to send information to agents. Agents can then pass that information on to the client application.

Retrieve Response Attributes

This sequence of calls retrieves the well-known attributes such as the user’s distinguished name, the name of the directory associated with the user, and any text associated with the user’s authentication. The online Agent API reference has a list of the well-known attributes that GetAttributes() can retrieve.

To retrieve response attributes

Call the AgentUser methods Login() and GetResponse().
With the AgentResponse object returned from GetResponse(), call GetAttributes().

Example: Retrieve the attributes for a response

The following script retrieves the attributes for a response to a user login request. The script then calls methods in the AgentResponseAttr object to display the attribute IDs, any attribute values, and other attribute information:

use Netegrity::AgentAPI;

$agentname="agent1";
$ip="127.0.0.1";
$sharedsecret="oursecret";
$username="userid";
$userpwd="userpwd";

$agentapi=Netegrity::AgentAPI‑>New($agentname,$sharedsecret);
#Add Policy Server configuration info...
$serverconfig = $agentapi‑>AddServerConfig($ip);
$agentapi‑>Connect();

$resource=$agentapi‑>GetResource("/mysite/hr/payroll.htm");
# Test whether the resource is protected. If it is,
# log in the user and get the attributes of the response.
if($resource‑>IsProtected() == SM_AGENTAPI_YES) {
   $user = $agentapi‑>CreateUser($username,$userpwd);
   print "\nLogging in user ".$user‑>Name()."...\n";
   $status=$user‑>Login($resource);
   if($status==SM_AGENTAPI_YES) {
      $response=$user‑>GetResponse();           
      @attr = $response‑>GetAttributes();
      foreach $attr(@attr) {
         print "\nAttribute ID = " . $attr‑>GetID()."\n";
         print "TTL = " . $attr‑>GetTTL()."\n";
         print "Value = " . $attr‑>GetValue()."\n";
         print "Name = " . $attr‑>GetName()."\n";
      }
   }
}
else {
   print "\nThe resource is not protected.\n\n";
}

Session Management

After you retrieve an AgentSession object, you can perform session management operations. You can retrieve information about a session, such as session timeout values, the session ID, and the session specification.

The session specification can be used to identify a session across multiple sites, such as for single sign-on operations. You can also retrieve a reason code for a failed authentication or authorization attempt by calling GetReason().

Example: Login in a user

The following example logs in a user, gets a response to the login attempt, retrieves a session object for the user’s session, and prints out various details about the session:

use Netegrity::AgentAPI;

#Define script variables
$agent = "agent1";
$secret = "oursecret";
$ip = "127.0.0.1";
$respath = "/mysite/hr/payroll.htm";
$username = "userid";
$pwd = "userpwd";

#Establish the connection and create needed objects
$agentapi = Netegrity::AgentAPI‑>New($agent, $secret);
$serverconfig = $agentapi‑>AddServerConfig($ip);
$agentapi‑>Connect();
$user = $agentapi‑>CreateUser($username, $pwd);
print "Logging in user ".$user‑>Name().".\n";
$resource = $agentapi‑>GetResource($respath);  
#Log in the user
$status = $user‑>Login($resource);
if($status==SM_AGENTAPI_YES) {
   print $user‑>Name() . " logged in successfully!\n\n";
   #Get the login response
   $response=$user‑>GetResponse();
   #Get the session object
   $session=$response‑>GetSession();
   if ($session != undef) {
      print "Printing session details:\n";
      print "Session reason=".$session‑>GetReason()."\n";
      print "Session IdleTimeout=".$session‑>IdleTimeout()."\n";
      print "Session Maxtimeout=".$session‑>MaxTimeout()."\n";
      print "Session ID=".$session‑>GetID()."\n";
      print "Session specification=".$session‑>GetSpec()."\n\n";
   }
}
else {
      print "Couldn't log in user " . $username . "\n\n";
}

Policy Server Commands

A management protocol exists between agents and the Policy Server. An agent uses this protocol to manage its caches and encryption keys in a manner consistent with policies and administrative changes on the Policy Server.

When Policy Server changes occur that require corresponding agent changes, the Policy Server issues commands for the agent to make the changes. You can retrieve these commands by calling DoManagement(). DoManagement() returns an array of AgentResponseAttr objects. Call GetID() in this object to retrieve any management commands that might be pending from the Policy Server.

The following script checks for pending management commands. If any commands are found, the script prints out each command ID and, if appropriate, the value associated with a command:

use Netegrity::AgentAPI;

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

$agentapi = Netegrity::AgentAPI‑>New($agentname,$secret);
$serverconfig = $agentapi‑>AddServerConfig($ip);
$agentapi‑>Connect();

@attr = $agentapi‑>DoManagement();

if (@attr == undef) {
   print "No commands are pending from the Policy Server.";
}
else {
   print "IDs of commands pending from the Policy Server:";
   foreach $attr(@attr) {
      if ($attr‑>GetID()==SM_AGENTAPI_AFFILIATE_KEY_UPDATE ||
         $attr‑>GetID()==SM_AGENTAPI_CACHE_FLUSH_THIS_USER ||
         $attr‑>GetID()==SM_AGENTAPI_CACHE_FLUSH_THIS_REALM) {
         print "\n Command ID: " . $attr‑>GetID();
         print "\n \tValue: " . $attr‑>GetValue();
      }
      else {
         #No need to print values for the IDs below. Value
         #will contain either binary data or no data.
         print "\nCommand ID: " . $attr‑>GetID();
      }
   }
}