Programming Guides › Programming Guide for Perl › CLI Policy Management Methods › CLI Realm Methods

CLI Realm Methods

Agent Method—Sets or Retrieves the Agent for the Realm

The Agent method sets or retrieves the agent for the realm.

Syntax

The Agent method has the following format:

Netegrity::PolicyMgtRealm‑>Agent([agent])

Parameters

The Agent method accepts the following parameters:

agent (PolicyMgtAgent)

(Optional) Specifies the agent to set for the realm.

Return Value

The Agent method returns a new or existing PolicyMgtAgent object or PolicyMgtGroup object when the call is successful.

This method returns undef when the call is unsuccessful

AuthScheme Method—Sets or Retrieves the Authentication Scheme for the Realm

The AuthScheme method sets or retrieves the authentication scheme for the realm.

Syntax

The AuthScheme method has the following format:

Netegrity::PolicyMgtRealm‑>AuthScheme([authScheme])

Parameters

The AuthScheme method accepts the following parameter:

authScheme (PolicyMgtAuthScheme)

(Optional) Specifies the authentication scheme to set for the realm.

Return Value

The AuthScheme method returns one of the following values:

• A New or existing PolicyMgtAuthScheme object for the realm
• undef if the call is unsuccessful

AzUserDir Method—Sets or Retrieves the Authorization User Directory for the Realm

The AzUserDir method sets or retrieves the authorization user directory for the realm.

Syntax

The AzUserDir method has the following format:

Netegrity::PolicyMgtRealm‑>AzUserDir([dir])

Parameters

The AzUserDir method accepts the following parameter:

dir (PolicyMgtUserDirectory)

(Optional) Specifies the authorization user directory to set for the realm.

Return Value

The AzUserDir method returns one of the following values:

• A new or existing PolicyMgtUserDir object for the realm
• undef if none exists, or if the call is unsuccessful

CreateChildRealm Method—Creates and Configures a Child Realm

The CreateChildRealm method creates and configures a realm directly under the realm on which this method was called.

Syntax

The CreateChildRealm method has the following format:

Netegrity::PolicyMgtRealm‑>CreateChildRealm(realmName, agent, authScheme [, realmDesc] [, resFilter] [, procAuthEvents] [, procAzEvents] [, protectAll] [, maxTimeout] [, idleTimeout] [, syncAudit] [, azUserDir] [, regScheme])

Parameters

The CreateChildRealm method accepts the following parameters:

realmName (string)

Specifies the name of the realm.

agent (PolicyMgtAgent)

Specifies the agent or agent group for the realm.

authScheme (PolicyMgtAuthScheme)

Specifies the authentication scheme to associate with the realm.

realmDesc (string)

(Optional) Specifies the realm description.

resFilter (string)

(Optional) Specifies the resource filter for the realm.

procAuthEvents (int)

(Optional) Specifies a flag for processing authentication events: 1 to enable, or 0 to disable. The default is enabled.

procAzEvents (int)

(Optional) Specifies a flag for processing authorization events: 1 to enable, or 0 to disable. The default is enabled.

protectAll (int)

(Optional) Specifies a flag for activating default resource protection:1 to enable, or 0 to disable. The default is enabled.

maxTimeout (int)

(Optional) Specifies the maximum time, in seconds, a user can access the realm before re-authentication is required. The default is 7200 (2 hours).

idleTimeout (int)

(Optional) Specifies the maximum time a user can remain inactive in the realm before re-authentication is required. The default is 3600 (1 hour).

syncAudit (int)

(Optional) Specifies a flag for enabling synchronous auditing: 1 to enable, or 0 to disable. When this flag is enabled, SiteMinder logs Policy Server and agent actions before it allows access to resources. The default is enabled.

azUserDir (PolicyMgtUserDir)

(Optional) Specifies the directory where users in the realm will be authorized. The default is the default directory.

regScheme (PolicyMgtRegScheme)

(Optional) Specifies the registration scheme used to register new users accessing resources in the realm.

Return Value

The CreateChildRealm method returns one of the following values:

• A PolicyMgtRealm object
• undef if the call is unsuccessful

Remarks

This method creates a realm that is configured for non-persistent sessions. To configure the realm for SiteMinder 5.0 persistent sessions, edit the realm in the Administrative UI.

Note: The Policy Management API only manipulates realms that are direct descendants of the object whose method has been called, as follows:

• For a realm under a domain. You can only manipulate the top-level realms in a domain object.
• For a realm under a realm. You can only manipulate realms that are directly under the parent realm.

CreateRule Method—Creates and Configures a Rule under the Realm

The CreateRule method creates and configures a rule under the realm.

Syntax

The CreateRule method has the following format:

Netegrity::PolicyMgtRealm‑>CreateRule( ruleName [, ruleDesc] [, action] [, resource] [, allowAccess] [, regexMatch] [, activeExpr] [, isEnabled] )

Parameters

The CreateRule method accepts the following parameters:

ruleName (string)

Specifies the name of the rule.

ruleDesc (string)

(Optional) Specifies the description of the rule.

action (string)

(Optional) Specifies the type of action that the rule will execute. One of the following actions:

For action type Web Agent actions, use one or more of the following HTTP actions. Use commas to separate multiple actions:

• GET. Retrieves a resource for viewing through HTTP.
• POST. Posts user-supplied information through HTTP.
• PUT. Supports legacy HTTP actions.

For action type Authentication events:

• OnAuthAccept. Occurs when a user successfully authenticates.
• OnAuthAttempt. Occurs when a user fails to authenticate because no user name was supplied.
• OnAuthChallenge. May be used in custom authentication schemes to trigger a response.
• OnAuthReject. Occurs when a user fails to authenticate.
• OnAuthUserNotFound. Used to trigger Active Responses.

For action type Authorization events:

• OnAccessAccept. Occurs when SiteMinder successfully authorizes a user to access the resource.
• OnAccessReject. Occurs when SiteMinder rejects a user because the user is not authorized to access the resource.

  resource (string)

(Optional) Specifies the resource protected by the rule. This value doesn't apply to action type Authentication events.

allowAccess (int)

(Optional) Specifies a flag to allow or deny access to the resource protected by the rule: 1 allows access, or 0 denies access. This flag applies only to action values of type GET, PUT, and/or POST. The default is 1.

regexMatch (int)

(Optional) Specifies a flag to allow regular expression pattern matching in the resource field : 1 allows regular expression matching, and 0 denies regular expression matching. This flag doesn't apply to action type Authentication events. The default is 0.

activeExpr (string)

(Optional) Specifies the active expression associated with the rule.

isEnabled (int)

(Optional) Specifies a flag to enable or disable the rule:1 to enable, or 0 to disable. The default is enabled.

Return Value

The CreateRule method returns one of the following values:

• A PolicyMgtRule object
• undef if the call is unsuccessful

DeleteChildRealm Method—Deletes a Top-level Realm within the Realm

The DeleteChildRealm method deletes a top-level realm within the realm.

Syntax

The DeleteChildRealm method has the following format:

Netegrity::PolicyMgtRealm‑>DeleteChildRealm(realm)

Parameters

The DeleteChildRealm method accepts the following parameter:

realm (PolicyMgtRealm)

Specifies the child realm to delete.

Return Value

The DeleteChildRealm method returns one of the following values:

• 0 on success, or is the realm was not found
• -1 if the call is unsuccessful

DeleteRule Method—Deletes an Existing Rule within the Realm

The DeleteRule method deletes an existing rule within the realm.

Syntax

The DeleteRule method has the following format:

Netegrity::PolicyMgtRealm‑>DeleteRule(rule)

Parameters

The DeleteRule method accepts the following parameter:

rule (PolicyMgtRule)

Specifies the rule to delete.

Return Value

The DeleteRule method returns one of the following values:

• 0 on success
• -1 if the call is unsuccessful, or if the rule is not part of the realm being used to delete the rule

Description Method—Sets or Retrieves the Description of the Realm

The Description method sets or retrieves the description of the realm.

Syntax

The Description method has the following format:

Netegrity::PolicyMgtRealm‑>Description([realmDesc])

Parameters

The Description method accepts the following parameter:

realmDesc (string)

(Optional) Specifies the description to assign to the realm.

Return Value

The Description method returns one of the following values:

• A new or existing realm description.
• An empty string if the call is unsuccessful

Flush Method—Flushes the Realm from the Resource Cache

The Flush method flushes the realm from the resource cache.

Syntax

The Flush method has the following format:

Netegrity::PolicyMgtRealm‑>Flush()

Parameters

The Flush method accepts no parameters.

Return Value

The Flush method returns one of the following values:

• 0 on success
• -1 if the call is unsuccessful

GetAllChildRealms Method—Retrieves All Top-level Realms within the Realm

The GetAllChildRealms method retrieves all top-level realms within the realm. Returns only the children.

Syntax

The GetAllChildRealms method has the following format:

Netegrity::PolicyMgtRealm‑>GetAllChildRealms()

Parameters

The GetAllChildRealms method accepts no parameters.

Return Value

The GetAllChildRealms method returns one of the following values:

• An array of PolicyMgtRealm objects
• undef if the call is unsuccessful

GetAllRules Method—Retrieves the Rules Associated with the Realm

The GetAllRules method retrieves the rules associated with the realm.

Syntax

The GetAllRules method has the following format:

Netegrity::PolicyMgtRealm‑>GetAllRules()

Parameters

The GetAllRules method accepts no parameters.

Return Value

The GetAllRules method returns one of the following values:

• An array of PolicyMgtRule objects
• undef if the call is unsuccessful

GetChildRealm Method—Retrieves a Top-level Child Realm under the Realm

The GetChildRealm method retrieves a top-level child realm under the realm. This method only searches child realms.

Syntax

The GetChildRealm method has the following format:

Netegrity::PolicyMgtRealm‑>GetChildRealm(realmName)

Parameters

The GetChildRealm method accepts the following parameter:

realmName (string)

Specifies the realm to check for child realms.

Return Value

The GetChildRealm method returns one of the following values:

• A PolicyMgtRealm object
• undef if the call is unsuccessful, or if the realm does not exist

GetDomain Method—Retrieves the Domain Associated with the Realm

The GetDomain method retrieves the domain associated with the realm.

Syntax

The GetDomain method has the following format:

Netegrity::PolicyMgtRealm‑>GetDomain()

Parameters

The GetDomain method accepts parameters.

Return Value

The GetDomain method returns one of the following values:

• Existing PolicyMgtDomain object for the realm
• undef if the call is unsuccessful

GetRule Method—Retrieves an Existing Rule in the Realm

The GetRule method retrieves an existing rule in the realm.

Syntax

The GetRule method has the following format:

Netegrity::PolicyMgtRealm‑>GetRule(ruleName)

Parameters

The GetRule method accepts the following parameter:

ruleName (string)

Specifies the name of the rule to retrieve.

Return Value

The GetRule method returns one of the following values:

• A PolicyMgtRule object
• undef if the call is unsuccessful, or if he specified rule does not exist

IdleTimeout Method—Sets or Retrieves the Maximum Time a User Can Remain Inactive in the Realm

The IdleTimeout method sets or retrieves the maximum time a user can remain inactive in the realm before re-authentication is required.

Syntax

The IdleTimeout method has the following format:

Netegrity::PolicyMgtRealm‑>IdleTimeout([idleTimeout])

Parameters

The IdleTimeout method accepts the following parameter:

idleTimeout (type)

(Optional) Specifies the idle timeout value, in seconds.

Return Value

The IdleTimeout method returns one of the following values:

• The existing timeout value if no argument is specified
• The new timeout value if idleTimeout is specified
• -1 if the call is unsuccessful

MaxTimeout Method—Sets or Retrieves the Maximum Time a User Can Access the Realm

The MaxTimeout method sets or retrieves the maximum time a user can access the realm before re-authentication is required.

Syntax

The MaxTimeout method has the following format:

Netegrity::PolicyMgtRealm‑>MaxTimeout([maxTimeout])

Parameters

The MaxTimeout method accepts the following parameter:

maxTimeout (int)

(Optional) Specifies the maximum timeout value, in seconds.

Return Value

The MaxTimeout method returns one of the following values:

• The existing maximum timeout value if no argument is specified.
• The new maximum timeout value if maxTimeout is specified.
• -1 if the call is unsuccessful

Name Method—Sets or Retrieves the Realm Name

The Name method sets or retrieves the realm name.

Syntax

The Name method has the following format:

Netegrity::PolicyMgtRealm‑>Name([realmName])

Parameters

The Name method accepts the following parameter:

realmName (string)

(Optional) Specifies the name to assign to the realm.

Return Value

The Name method returns one of the following values:

• The new or existing realm name
• undef if the call is unsuccessful

ProcessAuEvents Method—Sets or Retrieves the Authentication Event Flag in the Realm

The ProcessAuEvents method sets or retrieves the authentication event flag in the realm.

Authentication event processing affects performance. If no rules in the realm are triggered by authentication events, set this flag to 0.

Syntax

The ProcessAuEvents method has the following format:

Netegrity::PolicyMgtRealm‑>ProcessAuEvents([authFlag])

Parameters

The ProcessAuEvents method accepts the following parameter:

authFlag (int)

(Optional) Specifies whether authentication events are processed:

• 1 to enable even processing
• 0 to disable event processing

Return Value

The ProcessAuEvents method returns one of the following values:

• 1 if authentication events are to be processed
• 0 if authentication events are not to be processed
• -1 if the call is unsuccessful

ProcessAzEvents Method—Sets or Retrieves the Authorization Event Flag in the Realm

The ProcessAzEvents method sets or retrieves the authorization event flag in the realm.

Syntax

The ProcessAzEvents method has the following format:

Netegrity::PolicyMgtRealm‑>ProcessAzEvents([azFlag])

Parameters

The ProcessAzEvents method accepts the following parameter:

azFlag (int)

(Optional) Specifies whether to enable authorization event processing:

• 1 enables event processing
• 0 disables event processing

Return Value

The ProcessAzEvents method returns one of the following values:

• 1 if authorization events are to be processed
• 0 if authorization events are not to be processed
• -1 if the call is unsuccessful

Remarks

Authorization event processing affects performance. If no rules in the realm are triggered by authorization events, set this flag to 0.

ProtectResource Method—Sets or Retrieves the Current Resource Protection Flag Example

The ProtectResource method sets or retrieves the current resource protection flag.

Syntax

The ProtectResource method has the following format:

Netegrity::PolicyMgtRealm‑>ProtectResource([protectFlag])

Parameters

The ProtectResource method accepts the following parameter:

protectFlag (int)

(Optional) Specifies whether enable resource protection:

• 1 protects the resource
• 0 makes the resource unprotected

Return Value

The ProtectResource method returns one of the following values:

• The existing resource protection state (0 or 1) if no argument is specified
• The new resource protection state if a flag value is passed to the method
• undef if the call is unsuccessful

RegScheme Method—Sets or Retrieves the Registration Scheme for the Realm

The RegScheme method sets or retrieves the registration scheme for the realm.

Syntax

The RegScheme method has the following format:

Netegrity::PolicyMgtRealm‑>RegScheme([regScheme])

Parameters

The RegScheme method accepts the following parameter:

regScheme (PolicyMgtRegScheme)

(Optional) Specifies the registration scheme to set.

Return Value

The RegScheme method returns one of the following values:

• A PolicyMgtRegScheme object
• undef if the call is unsuccessful, or if no registration scheme exists

SessionDrift Method--Sets or Retrieves the Session Drift

The SessionDrift method sets or retrieves the session drift of the realm, that is, the validation period (in seconds) if enabled on a persistent realm.

Syntax

The SessionDrift method has the following format:

Netegrity::PolicyMgtRealm‑>SessionDrift([SessionDrift])

Parameters

The SessionDrift method accepts the following parameter:

SessionDrift (int)

(Optional) Specifies the new value, or returns the current value when not specified.

Return Value

The SessionDrift method returns one of the following values:

• The new or existing session drift value
• An Sm_PolicyApi_Status_t error code if unsuccessful

  Note: -1 (Sm_PolicyApi_Failure) is a valid return value, indicating that the session drift is not enabled

ResourceFilter Method—Sets or Retrieves the Realm Resource Filter

The ResourceFilter method sets or retrieves the realm resource filter.

Syntax

The ResourceFilter method has the following format:

Netegrity::PolicyMgtRealm‑>ResourceFilter([rFilter])

Parameters

The ResourceFilter method accepts the following parameter:

rFilter (string)

(Optional) Specifies the realm resource filter to set.

Return Value

The ResourceFilter method returns one of the following values:

• The new or existing realm filter
• undef if the call is unsuccessful

SyncAudit Method—Sets or Retrieves the Synchronous Auditing Flag

The SyncAudit method sets or retrieves the synchronous auditing flag. When this flag is enabled, SiteMinder logs Policy Server and agent actions before it allows access to resources.

Syntax

The SyncAudit method has the following format:

Netegrity::PolicyMgtRealm‑>SyncAudit([syncFlag])

Parameters

The SyncAudit method accepts the following parameter:

syncFlag (int)

(Optional) Specifies whether synchronous auditing is enabled:

• 1 enables synchronous auditing
• 0 disables synchronous auditing

Return Value

The SyncAudit method returns one of the following values:

• Existing synchronous auditing value (0 or 1) if no argument is specified
• New synchronous auditing value if a flag argument is passed to the method
• -1 if the call is unsuccessful