Siteminder Perl Scripting Enu

CA SiteMinder

Programming Guide for Perlr12.0 SP2

This documentation and any related computer software help programs (hereinafter referred to as the "Documentation") are for your informational purposes only and are subject to change or withdrawal by CA at any time. This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and p roprietary information of CA and may not be used or disclosed by you except as may be permitted in a separate confidentiality agreement between you and CA. Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may print a reasonable number of copies of the Documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy. The right to print copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed. TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION "AS IS" WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. The use of any software product referenced in the Documentation is governed by the applicable license agreement and is not modified in any way by the terms of this notice. The manufacturer of this Documentation is CA. Provided with "Restricted Rights." Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their successors. Copyright 2009 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

CA Product ReferencesThis document references the following CA products: CA SiteMinder

Contact CAContact Technical Support For your convenience, CA provides one site where you can access the information you need for your Home Office, Small Business, and Enterprise CA products. At http://ca.com/support, you can access the following: Online and telephone contact information for technical assistance and customer services Information about user communities and forums Product and documentation downloads CA Support policies and guidelines Other helpful resources appropriate for your product

Provide Feedback If you have comments or questions about CA product documentation, you can send a message to [email protected]. If you would like to provide feedback about CA product documentation, complete our short customer survey, which is also available on the CA Support website, found at http://ca.com/docs.

ContentsChapter 1: Perl Scripting Overview 25About the SiteMinder Command Line Interface ................................................... 25 Installation Path ................................................................................ 26 Perl Location ................................................................................ 26 Where to Run Your Scripts ...................................................................... 26 CLI Example: Create a Policy Store Object ....................................................... 27 CLI Example: View and Set Individual Properties ................................................. 28 Location of Sample Scripts ...................................................................... 29 Related Documentation ......................................................................... 29 Object Dependencies Poster ................................................................. 29

Chapter 2: Agent API

31

About Agents and the Agent API................................................................. 31 Write a Script against the Agent API ............................................................. 32 Single Sign-on and the Agent API ............................................................... 33 Single Sign-on Support for Custom Agents ................................................... 34 Single Sign-on Support for Standard Agents ................................................. 34 Session Information ............................................................................ 35 Advantages of Session Variables ............................................................. 35 SiteMinder Support ......................................................................... 35 Requirements for Using Session Variables .................................................... 36 End of Session Cleanup ..................................................................... 36 Objects and the Object Hierarchy ................................................................ 37

Chapter 3: CLI Agent API Methods

39

Agent Administration Methods ................................................................... 39 AddServerConfig MethodAdds Policy Server Configurations to Agent API Object.............. 40 Connect MethodEstablishes Connection between Agent API and Policy Server ................ 41 CreateBootstrapFile MethodGenerates Bootstrap File for Connecting to Agent ................ 42 CreateUser MethodCreates a User Object .................................................. 43 Disconnect MethodCloses Connection between Agent and Policy Server ..................... 44 DoManagement MethodRequests Agent Commands from Policy Server ...................... 45 GetResource MethodRetrieves the Specified Resource ...................................... 45 IncrementRefCount MethodIncrement the Reference Count ................................. 46 New MethodConstructs the Agent API ...................................................... 47 PrintDebugTrace MethodOutputs Trace Information to Console .............................. 48

Contents 5

SetErrorCallback MethodRegisters Subroutine that Processes Error Messages ................ 48 SetTraceCallback MethodRegisters Subroutine that Processes Trace Messages ............... 49 Resource Methods .............................................................................. 51 GetAuthType MethodRetrieves the Type of Credentials Required ............................ 51 IsProtected MethodChecks whether SiteMinder Is Protecting Resource....................... 53 Response Methods .............................................................................. 53 GetAttributes MethodRetrieves List of Available Response Attributes ........................ 54 GetSession MethodRetrieves the Session from the Response ................................ 54 Response Attribute Methods ..................................................................... 55 GetFlags MethodRetrieves Response Attribute's Flags ....................................... 55 GetID MethodRetrieves Response Attribute's ID or Agent Command's ID .................... 55 GetName MethodRetrieves Response Attribute's Name ..................................... 58 GetTTL MethodRetrieves Response Attribute's TTL Value .................................... 58 GetValue MethodRetrieves Response Attribute's Value ...................................... 59 Server Configuration Method .................................................................... 59 IPAddress MethodSets or Retrieves Policy Server's IP Address .............................. 59 Session Methods ................................................................................ 60 AddParameter MethodAdds Session Variable Name-Value Pair to Parameters List ............ 60 DelVariables MethodDeletes Session Variables from Session Store .......................... 62 GetID MethodRetrieves the Session ID ..................................................... 63 GetReason MethodRetrieves the Session's Reason ID ....................................... 63 GetSpec MethodRetrieves the Encrypted Session Specification .............................. 65 GetVariables MethodRetrieves Session Variables from Session Store ........................ 66 IdleTimeout MethodRetrieves Session's Idle Timeout Value ................................. 66 MaxTimeout MethodRetrieves Session's Maximum Timeout Value ........................... 67 SetVariables MethodWrites Session Variables to Session Store .............................. 67 Single Sign-on Token Methods .................................................................. 68 Decode MethodDecodes a Single Sign-on Token ............................................ 68 GetString MethodRetrieves String Representation of SSO Token Object ..................... 70 GetVersion MethodRetrieves SiteMinder Version of SSO Token .............................. 70 IsThirdParty MethodDetermines Whether the Token Is Custom .............................. 71 User Methods ................................................................................... 72 Audit MethodAudits Authorizations Performed out of Agent Cache ........................... 72 Certificate MethodSets or Retrieves User's X.509 Cerficate .................................. 73 CertificateFile MethodSets or Retrieves User's X.509 Certificate Using File ................... 74 CreateSSOToken MethodCreates Single Sign-on Token Object .............................. 75 CustomData MethodSets or Retrieves Custom Authentication Data .......................... 76 FormData MethodSets or Retrieves HTML Forms-based Authentication Data ................. 76 GetResponse MethodReturns Response After IsAuthorized or Login.......................... 77 Impersonate MethodAllows One User to Impersonate Another .............................. 78 IsAuthorized MethodDetermines Whether User Is Authorized................................ 79 Login MethodPerforms Session Login and Validation ........................................ 80

6 Programming Guide for Perl

Logout MethodLogs the User out of the Session ............................................ 81 Name MethodSets or Retrieves the User's Username ....................................... 82 Password MethodSets or Retrieves the User's Password..................................... 82 Validate MethodValidates a Session Specification ........................................... 83

Chapter 4: Agent Operations

85

Resource Protection ............................................................................. 85 Responses and Response Attributes ............................................................. 86 Retrieve Response Attributes ................................................................ 87 Session Management ........................................................................... 88 Policy Server Commands ........................................................................ 90

Chapter 5: Policy Management API

91

About the Policy Server and the Policy Management API .......................................... 91 Location of the Policy Management API ...................................................... 92 Write a Script against the Policy Management API ................................................ 92 Script Execution Performance Enhancement.................................................. 93 Federation Security Services .................................................................... 93 SAML Assertions ............................................................................ 93 SAML 1.x ................................................................................... 94 SAML 2.0 ................................................................................... 96 WS-Federation ............................................................................. 100 Sample Scripts ............................................................................ 102 Affiliate Domains .............................................................................. 102 Authentication Scheme Configuration ........................................................... 102 Configuration Information .................................................................. 103 Configuration Tables ....................................................................... 104

Chapter 6: CLI Policy Management Methods

149

Administrator Methods ......................................................................... 152 AuthScheme MethodSets or Retrieves an Authentication Scheme .......................... 152 Description MethodSets or Retrieves the Description of an Administrator ................... 153 ManageAllDomains MethodGrants or Revokes Privileges to Manage Policy Server Objects ... 153 ManageDomainObjects MethodGrants or Revokes Privileges to Manage Domain Objects..... 154 ManageKeysAndPwdPolicy MethodGrants or Revokes Privileges to Manage Keys and Password Policies .......................................................................... 155 ManageUsers MethodGrants or Revokes Privileges to Manage Users ........................ 156 Name MethodSets or Retrieves the Name of an Administrator .............................. 157 Password MethodSets or Retrieves the Administrator Password ............................ 157 UserDirectory MethodSets or Retrieves an External User Directory ......................... 158 Affiliate Attribute Methods...................................................................... 158

Contents 7

GetAttrType MethodRetrieves the Affiliate Attribute Type .................................. 159 GetValue MethodRetrieves the Value of the Affiliate Attribute .............................. 159 Affiliate Domain Methods ....................................................................... 160 AddAdmin MethodAssociates an Administrator with an Affiliate Domain ..................... 161 AddUserDir MethodAssociates a User Directory with an Affiliate Domain .................... 161 CreateAffiliate MethodCreates an Affiliate Object .......................................... 162 CreateSAMLServiceProvider MethodCreates a SAML Service Provider ....................... 165 CreateWSFEDResourcePartner MethodCreates a WS-Federation Resource Partner .......... 168 DeleteAffiliate MethodDeletes an Affiliate from a Domain .................................. 170 DeleteSAMLServiceProvider MethodDeletes a SAML Service Provider ....................... 170 DeleteWSFEDResourcePartner MethodDeletes a Resource Partner .......................... 171 Description MethodRetrieves or Sets a Description ......................................... 171 GetAffiliate MethodRetrieves an Affiliate Object ............................................ 172 GetAllAdmins MethodRetrieves all Administrators .......................................... 172 GetAllAffiliates MethodRetrieves All Affiliates in a Domain .................................. 173 GetAllSAMLServiceProviders MethodRetrieves all Service Providers associated with the Affiliate Domaine .......................................................................... 173 GetAllWSFEDResourcePartners MethodRetrieves all WSFED Resource Partners .............. 174 GetSAMLServiceProvider MethodRetrieves a Specified Service Provider ..................... 174 GetSAMLServiceProviderByID MethodRetrieves a Specified Service Provider ................ 175 GetUserDirSearchOrder MethodRetrieves Search Order of a User Directory ................. 175 GetWSFEDResourcePartner MethodRetrieves Resource Partner ............................. 176 GetWSFEDResourcePartnerById MethodRetrieves Resource Partner by ID .................. 176 Name MethodSets or Retrieves Affiliate Domain Name ..................................... 177 RemoveAdmin MethodDissasocciates an Administrator from an Affiliate Domain ............ 178 RemoveUserDir MethodDisassociates a User Directory from an Affiliate Domain ............. 178 SetUserDirSearchOrder MethodSets the Order for Searching Directory Objects ............. 179 Affiliate Object Methods ........................................................................ 179 AddAttribute MethodAdds a New Affiliate Attribute......................................... 181 AddUser MethodAdds a New User to the Affiliate Object ................................... 183 AllowNotification MethodSets or Retrieves the Event Notification Property .................. 184 AssertionPluginClass MethodSets or Retrieves the Name of an Assertion Generator Plug-in........................................................................................... 184

AssertionPluginParameters MethodSets or Retrieves a Parameter String .................... 185 Audience MethodSets or Retrieves a URI .................................................. 186 AuthURL MethodSets or Retrieves a URL .................................................. 187 ConsumerURL MethodSets or Retrieves a URL ............................................. 187 CreateIPHostConfigName MethodCreates an IP Configuration Object from the Specified Host Name ................................................................................ 188 CreateIPConfigRange MethodCreates an IP Configuration Object ........................... 189 CreateIPConfigSingleHost MethodCreates an IP Configuration Object from the Specified IP Address ................................................................................... 189 CreateIPConfigSubnetMask MethodCreates an IP Configuration Object ..................... 190


DeleteIPConfig MethodDeletes an IP Configuration Object ................................. 191 Description MethodSets or Retrieves the Description of an Affiliate Object .................. 191 GetAllAttributes MethodRetrieves Attributes for an Affiliate Object.......................... 192 GetAllIPConfigs MethodRetrieves All IP Configuration Objects for an Affiliate ................ 192 GetAllUsers MethodRetrieves All Users Associated with an Affiliate ......................... 193 IsEnabled MethodSets or Retrieves the Enabled Flag for the Affiliate ....................... 193 Name MethodSets or Retrieves the Affiliate Name ......................................... 194 Password MethodSets or Retrieves a Password for an Affiliate .............................. 195 RemoveAttribute MethodRemoves an Attribute from an Affiliate ............................ 195 RemoveUser MethodRemoves a User from an Affiliate ..................................... 196 SAMLProfile MethodSets or Retrieves the Type of SAML Profile ............................. 196 SAMLVersion MethodSets or Retrieves the SAML Version for the Affiliate ................... 197 Save MethodSaves the Affiliate to the Policy Store......................................... 198 SessionSyncInterval MethodSets or Retrieves the Session Synchronization Property ........ 199 SharedSessioning MethodSets or Retrieves the Shared Session Property ................... 199 SkewTime MethodSets or Retrieves the Skew Time Property ............................... 200 ValidityDuration MethodSets or Retrieves the Duration a SAML Assertion Is Valid ........... 201 Agent Methods ................................................................................ 201 ConvertFromLegacy MethodConverts a v4.x Agent to a v5.x Agent ......................... 202 ConvertToLegacy MethodConverts a v5.x Agent to a v4.x Agent ........................... 202 Description MethodSets or Retrieves the Agent Description ................................ 203 IPAddress MethodSets or Retrieves the Agent's IP Address ................................ 203 Name MethodSets or Retrieves the Name of the Agent .................................... 204 RealmHintAttrID MethodSets or Retrieves the Hint Attribute ............................... 204 SharedSecret MethodSets or Retrieves the Shared Secret for a v4.x Agent ................. 205 Agent Configuration Methods ................................................................... 205 AddAssociation MethodAdds a Name and Value for this Configuration ...................... 206 AddAssociationMultiValue MethodAdds a Multi-valued Configuration Parameter ............. 206 Description MethodSets or Retrieves the Description of the Agent Configuration Object ..... 207 GetAssociations MethodRetrieves a List of All the Configuration Parameters ................ 208 Name MethodSets or Retrieves the Agent Configuration Object Name ...................... 208 RemoveAssociation MethodRemoves a Configuration Parameter ............................ 209 Agent Configuration Parameters Methods ....................................................... 209 Name MethodSets or Retrieves the Name Portion of the Agent Configuration Parameter ..... 209 Flags MethodSets or Retrieves the Encryption Flag Attribute ............................... 210 Value MethodSets or Retrieves the Value of the Agent Configuration Parameter ............. 211 Agent Type Methods ........................................................................... 211 GetDescription MethodRetrieves the Description of the Agent Type ......................... 211 GetName MethodRetrieves the Name of the Agent Type ................................... 212 Authentication and Authorization Map Methods .................................................. 212 AuthDir MethodSets or Retrieves the Authentication Directory ............................. 213 AzDir MethodSets or Retrieves the Authorization Directory ................................. 213

Contents 9

MapType MethodSets or Retrieves the Type of Authentication and Authorization Map ....... 214 Authentication Scheme Methods ................................................................ 215 CustomLib MethodSets or Retrieves the Name of the Shared Library ....................... 216 CustomParam MethodSets or Retrieves Information that Is Passed to the Authentication Scheme ................................................................................... 217 CustomSecret MethodSets or Retrieves the Shared Secret for the Custom Authentication Scheme ................................................................................... 217 Description MethodSets or Retrieves the Description of the Authentication Scheme ......... 218 IgnorePwd MethodSpecifies whether Password Policies Should Be Checked ................. 218 IsRadius MethodDetermines whether the Authentication Scheme Supports RADIUS Agents........................................................................................... 219

IsTemplate MethodDetermines whether the Authentication Scheme Is a Template .......... 220 IsUsedByAdmin MethodDetermines whether the Scheme Authenticates Administrators ...... 220 Name MethodSets or Retrieves the Name of the Authentication Scheme .................... 221 ProtectionLevel MethodSets or Retrieves the Protection Level of the Authentication Scheme........................................................................................... 222

Save MethodSaves the Authentication Scheme to the Policy Store ......................... 222 SaveCredentials MethodDetermines whether User Credentials Can Be Saved ............... 223 Type MethodSets or Retrieves the Authentication Scheme Type ............................ 224 Certificate Mapping Methods ................................................................... 224 AttrMap MethodSets or Retrieves the Attribute Map for Certificate Mapping ................. 225 CacheCRL MethodDetermines whether To Cache Certificate Revocation List (CRL) entries ... 225 CertRequired MethodDetermines whether Certificate Validation is Required ................. 226 CRLUserDirectory MethodSets or Retrieves the LDAP Directory where the Certificate Revocation List (CRL) Is Located ............................................................ 227 Description MethodSets or Retrieves the Description of the Certificate Map ................. 227 DirectoryType MethodSets or Retrieves the Type of User Directory ......................... 228 EnableCRL MethodDetermines whether To Check the Certificate Revocation List (CRL) for Revoked Certificates ....................................................................... 229 IssuerDN MethodSets or Retrieves the DN of the Certificate Issuer ......................... 230 UseDistributionPoints MethodDetermines whether Certificate Revocation List (CRL) Searches Use a Distribution Point ........................................................... 230 VerifySignature MethodDetermines whether SiteMinder Verifies the Certificate Authority's Signature .................................................................................. 231 Cluster Methods ............................................................................... 232 AddServer MethodAdds a Server to the Cluster ............................................ 232 GetAllServers MethodRetrieves an Array of All the Servers in a Cluster ..................... 233 Data Management Methods .................................................................... 233 ClearText MethodSets or Retrieves the Clear Text Flag .................................... 234 Export MethodExports the Specified SiteMinder Object from the Source Data Store ......... 235 Import MethodImports an Object from the Temporary Files ................................ 236 IncludeDependencies MethodSets or Retrieves the Object Dependencies Flag ............... 238 OverwriteObjects MethodSets or Retrieves the Overwrite Objects Flag ..................... 239 Domain Methods ............................................................................... 240


AddAdmin MethodAdds an Administrator to the Domain ................................... 241 AddUserDir MethodAssociates a User Directory with the Domain ........................... 242 CreatePolicy MethodCreates and Configures a Policy in the Domain ........................ 243 CreateRealm MethodCreates and Configures a Top-level Realm in the Domain .............. 244 CreateResponse MethodCreates a Response............................................... 246 CreateResponseGroup MethodCreates a Response Group for the Domain ................... 247 CreateRuleGroup MethodCreates a Rule Group for the Domain ............................. 247 DeleteGroup MethodDeletes a Group from the Domain .................................... 248 DeletePolicy MethodDeletes a Policy ...................................................... 249 DeleteRealm MethodDeletes a Realm in the Domain ....................................... 249 DeleteResponse MethodDeletes a Response ............................................... 250 DeleteVariable MethodDeletes a Specified Variable ........................................ 250 Description MethodSets or Retrieves the Description of the Domain ........................ 251 GetAllPolicies MethodRetrieves All Policies Associated with the Domain ..................... 251 GetAllRealms MethodRetrieves All Top-level Realms in the Domain ......................... 252 GetAllResponseGroups MethodRetrieves All the Response Groups Associated with the Domain .................................................................................... 252 GetAllResponses MethodRetrieves All Responses Associated with the Domain ............... 253 GetAllRuleGroups MethodRetrieves All Rule Groups Associated with the Domain ............ 253 GetAllVariables MethodRetrieves All Variable Objects of the Domain ........................ 254 GetPolicy MethodRetrieves a Policy in the Domain ......................................... 254 GetRealm MethodRetrieves a Top-level Realm in the Domain .............................. 255 GetResponse MethodRetrieves a Response Associated with the Domain .................... 255 GetResponseGroup MethodRetrieves the Specified Response Group ........................ 256 GetRuleGroup MethodRetrieves the Specified Rule Group .................................. 256 GetUserDirSearchOrder MethodRetrieves User Directory Objects Associated with the Domain .................................................................................... 257 GetVariable MethodRetrieves the Specified Variable Object ................................ 257 GlobalPoliciesApply MethodDetermines whether the Domain Is Enabled for Global Policies ... 258 Name MethodSets or Retrieves the Domain Name ......................................... 258 RemoveAdmin MethodDisassociates an Administrator from the Domain .................... 259 RemoveUserDir MethodDisassociates the User Directory from the Domain .................. 260 SetUserDirSearchOrder MethodRearranges the Search Order of the User Directory Objects........................................................................................... 260

Group Methods ................................................................................ 261 Add MethodAdds an Agent, Response, Rule, or Nested Group Object to the Group .......... 262 Contains MethodDetermines whether the Group Contains the Specified Agent, Response, Rule, or Nested Group Object............................................................... 263 Description MethodSets or Retrieves the Description of the Group Object ................... 263 GetAgent MethodRetrieves the Specified Agent Object from the Group ..................... 264 GetAgentGroup MethodRetrieves an Agent Group Object Nested within the Group .......... 265 GetAgentType MethodRetrieves the Type of the Agent Objects Contained in the Group ...... 265

Contents 11

GetAllAgentGroups MethodRetrieves All the Agent Group Objects Nested within the Group........................................................................................... 266

GetAllAgents MethodRetrieves All the Agent Objects in the Group .......................... 266 GetAllResponseGroups MethodRetrieves All the Response Group Objects Nested within the Group ..................................................................................... 267 GetAllResponses MethodRetrieves All the Response Objects in the Group ................... 267 GetAllRuleGroups MethodRetrieves All the Rule Group Objects Nested within the Group ..... 268 GetAllRules MethodRetrieves All the Rule Objects in the Group ............................. 268 GetResponse MethodRetrieves the Specified Response Object from the Group .............. 269 GetResponseGroup MethodRetrieves a Response Group Object Nested within the Group .... 269 GetRule MethodRetrieves the Specified Rule Object from the Group ........................ 270 GetRuleGroup MethodRetrieves a Rule Group Object Nested within the Group .............. 271 Name MethodSets or Retrieves the Name of the Group Object ............................. 271 Remove MethodRemoves the Specified Group Member from the Group ..................... 272 Host Configuration Methods .................................................................... 272 AddCluster MethodAdds an Empty Cluster to the Host Configuration........................ 273 AddServer MethodAdds a Non-clustered Server to the Host Configuration .................. 274 Description MethodSets or Retrieves the Description of the Host Configuration Object....... 275 EnableFailover MethodSets or Retrieves the Enable Failover Flag ........................... 275 FailoverThreshold MethodSets or Retrieves the Failover Threshold Percentage .............. 276 GetAllClusters MethodRetrieves an Array of Policy Management Cluster Objects ............ 277 GetAllServers MethodRetrieves an Array of Non-clustered Server Objects .................. 278 MaxSocketsPerPort MethodSets or Retrieves the Maximum Number of TCP/IP Sockets ...... 278 MinSocketsPerPort MethodSets or Retrieves the Minimum Number of TCP/IP Sockets ....... 279 Name MethodSets or Retrieves the Name of the Host Configuration Object ................. 279 NewSocketStep MethodSets or Retrieves the New Socket Step Value for the Host Configuration .............................................................................. 280 RemoveAllClusters MethodRemoves All Cluster Objects Associated with This Host Configuration .............................................................................. 281 RemoveAllServers MethodRemoves All Non-clustered Policy Server Objects from the Host Configuration .............................................................................. 281 RequestTimeout MethodSets or Retrieves the Request Timeout Value ...................... 282 Initialization Methods .......................................................................... 282 CreateSession MethodCreates a Policy Server Session ..................................... 283 DisableAudit MethodSets the Flag to Enable or Disable Auditing ............................ 283 DisableCacheUpdates MethodDeprecated ................................................. 284 DisableManagementWatchDog MethodReads or sets the Enabled State of the SiteMinder Management Watchdog .................................................................... 285 DisableValidation MethodReads or Sets the Enabled State for Validation of Policy Server Objects .................................................................................... 286 EnableCache MethodDeprecated .......................................................... 286 LoadAgentTypeDictionary MethodReads or Sets the Enabled State for the Agent Type Dictionary ................................................................................. 287 New MethodConstructor for the Policy Management API ................................... 287


PreLoadCache MethodReads or Sets the Enabled State for Preloading of Caches ............ 288 PrintDebugTrace MethodEnables or Disables Printing Debug (Trace) Information Example ... 289 IP Configuration Methods ...................................................................... 290 GetEndIPAddress MethodRetrieves the Ending IP Address.................................. 290 GetHostName MethodRetrieves the Host Name Associated with a Host Name IP Address Restriction ................................................................................. 291 GetIPAddress Method Retrieves an IP address for an IP address restriction ................. 292 GetSubnetMask MethodRetrieves the Subnet Mask for a Subnet Address ................... 292 GetType MethodRetrieves the Type of the IP Address Restriction ........................... 293 ODBC Query Scheme Methods.................................................................. 294 Description MethodSets or Retrieves the Description of the ODBC Query Scheme ........... 295 Name MethodSets or Retrieves the ODBC Query Scheme Name ............................ 295 QueryAuthenticateUser MethodSets or Retrieves a Query that Fetches a User's Password ... 296 QueryEnumerate MethodSets or Retrieves a Query that Lists the Names of User Objects .... 297 QueryGetGroupProp MethodSets or Retrieves a Query that Fetches the Value of a Group Property ................................................................................... 297 QueryGetGroupProps MethodSets or Retrieves a List of Group Properties ................... 298 QueryGetGroups MethodSets or Retrieves a Query that Fetches the Names of the Groups that the User Is a Member of ............................................................... 299 QueryGetObjInfo MethodSets or Retrieves a Query that Fetches the Class of the Object..... 300 QueryGetUserProp MethodSets or Retrieves a Query that Fetches the Value of a User Property ................................................................................... 300 QueryGetUserProps MethodSets or Retrieves a List of User Properties ...................... 301 QueryInitUser MethodSets or Retrieves a Query that Determines whether a User Exists in the Database .............................................................................. 302 QueryIsGroupMember MethodSets or Retrieves a Query that Lists the Group Membership for a Particular User ........................................................................ 303 QueryLookup MethodSets or Retrieves a Query that Fetches Objects ....................... 303 QueryLookupGroup MethodSets or Retrieves a Query that Fetches a Group Name .......... 304 QueryLookupUser MethodSets or Retrieves a Query that Fetches a User Name ............. 305 QuerySetGroupProp MethodSets or Retrieves a Query that Sets the Value of a Group Property ................................................................................... 306 QuerySetPassword MethodSets or Retrieves a Query that Changes a User Password ........ 306 QuerySetUserProp MethodSets or Retrieves a Query that Sets the Value of a User Property........................................................................................... 307

Password Policy Methods ....................................................................... 308 AllowNestedGroups MethodAllows the Password Policy To Be Configured for Nested Groups........................................................................................... 311

AllowLowerPriorityPolicies MethodSets Flag To Determine whether Password Policies with Lower Priority Should Be Evaluated ......................................................... 312 AuthLoginTrackFailure MethodAllows a User To Login if Login Tracking Data Fails ........... 312 BadLoginDisablementPeriod MethodSets or Retrieves the Number of Minutes Before a User Account Is Disabled ................................................................... 313 Description MethodSets or Retrieves the Description of the Password Policy ................ 314

Contents 13

DictionaryMatch MethodSets the Minimum Number of Letters Required To Qualify a Password for Dictionary Checking ........................................................... 314 DictionaryPath MethodSets or Retrieves the Location of a Dictionary File ................... 315 DisableAfterInactivityExpiration MethodDisables an Inactive User's Account ................ 316 DisableAfterPwdExpiration MethodDisables a User's Aaccount after the User's Password Expires .................................................................................... 316 EntireDir MethodDetermines Whether the Password Policy Applies to the Entire Directory ... 317 ExpirationDelay MethodSpecifies the Number of Days a Password Can Be Used ............. 318 IsEnabled MethodEnables or Disables a Password Policy ................................... 318 MaxLoginFailures MethodSets or Retrieves the Maximum Number of Failed Login Attempts........................................................................................... 319

MaxLoginInactive MethodSets or Retrieves the Number of Days of Inactivity Are Allowed ... 320 Name MethodSets or Retrieves the Password Policy Name ................................. 320 PwdAddRegExpMatch MethodAdds a Regular Expression to the List of Expressions that New Passwords Must Match ................................................................ 321 PwdAddRegExpNoMatch MethodAdds a Regular Expression to the List of Expressions that New Passwords Must NOT Match............................................................ 321 PwdAllowDigits MethodSpecifies whether Passwords Are Allowed To Have Numeric Characters................................................................................. 322 PwdAllowLowercase MethodSpecifies whether Passwords Are Allowed To Have Lower Case Letters .................................................................................... 323 PwdAllowNonAlphNum MethodSpecifies whether Passwords Are Allowed To Have Non-Alphanumeric Characters .............................................................. 323 PwdAllowNonPrintable MethodSpecifies whether Passwords Are Allowed To Have Non-Printable Characters ................................................................... 324 PwdAllowPunctuation MethodSpecifies whether Passwords Are Allowed To Have Punctuation Mark Characters ............................................................... 325 PwdAllowUpperCase MethodSpecifies whether Passwords Are Allowed To Have Upper Case Letters .................................................................................... 325 PwdExpiryWarning MethodSets or Retrieves the Number of Days in Advance To Notify the User that the Password Will Expire .......................................................... 326 PwdForceLowerCase MethodDetermines whether To Convert Upper Case Letters in a New Password to Lower Case.................................................................... 327 PwdForceUpperCase MethodDetermines whether To Convert Lower Case Letters in a New Password to Upper Case.................................................................... 327 PwdGetAllRegExpMatch MethodRetrieves the Name Tags of the Regular Expressions that New Passwords Must Match ................................................................ 328 PwdGetAllRegExpNoMatch MethodRetrieves the Name Tags of the Regular Expressions that New Passwords Must NOT Match ....................................................... 329 PwdGetRegExp MethodRetrieves the Regular Expression for the Specified Name Tag ........ 329 PwdIgnoreSequence MethodDetermines whether To Ignore Sequence when Calculating the New Password ......................................................................... 330 PwdMaxLength MethodSets or Retrieves the Maximum Length for User Passwords .......... 331 PwdMaxRepeatingChar MethodSets or Retrieves the Maximum Number of Identical Characters................................................................................. 331


PwdMinAlpha MethodSets or Retrieves the Minimum Number of Alphabetic Characters a Password Must Contain ..................................................................... 332 PwdMinAlphaNum MethodSets or Retrieves the Minimum Number of Alphanumeric Characters a Password Must Contain ........................................................ 333 PwdMinLength MethodSets or Retrieves the Minimum Length for User Passwords ........... 333 PwdMinLowercase MethodSets or Retrieves the Minimum Number of Lower Case Letters a Password Must Contain ..................................................................... 334 PwdMinNonAlpha MethodSets or Retrieves the Minimum Number of Non-Alphanumeric Characters A Password Must Contain........................................................ 334 PwdMinNonPrintable MethodSets or Retrieves the Minimum Number of Non-Printable Characters a Password Must Contain ........................................................ 335 PwdMinNumbers MethodSets or Retrieves the Minimum Number of Numeric Characters a Password Must Contain ..................................................................... 335 PwdMinProfileMatch MethodSpecifies the Minimum Character Sequence To Check against the User's Personal Information ............................................................ 336 PwdMinPunctuation MethodSets or Retrieves the Minimum Number of Punctuation Marks a Password Must Contain ..................................................................... 337 PwdMinUppercase MethodSets or Retrieves the Minimum Number of Upper Case Letters a Password Must Contain ..................................................................... 337 PwdPercentDiff MethodSets or Retrieves the Percentage of Different Characters a New Password Must Contain ..................................................................... 338 PwdPolicyPriority MethodSets or Retrieves the Password's Evaluation Priority Setting ....... 338 PwdRedirectionURL MethodSets or Retrieves the URL where the User is Redirected Example ................................................................................... 339 PwdRemoveRegExp MethodRemoves the Regular Expression Associated with the Specified Name Tag ................................................................................. 340 PwdReuseCount MethodSpecifies the Number of New Passwords that Must Be Used ......... 340 PwdReuseDelay MethodSpecifies the Number of Days a User Must Wait Before Reusing a Password .................................................................................. 341 ReEnableAfterIncorrectPwd MethodDetermines whether To Re-enable a User Account after the Entry of an Incorrect Password ......................................................... 341 Save MethodSaves the Password Policy to the Policy Store ................................. 342 StripEmbeddedWhitespace MethodDetermines whether To Strip New Passwords of Embedded White Space .................................................................... 343 StripLeadingWhitespace MethodDetermines whether To Strip New Passwords of Leading White Space ............................................................................... 343 StripTrailingWhitespace MethodDetermines whether To Strip New Passwords of Trailing White Space ............................................................................... 344 TrackLoginDetails MethodDetermines whether To Track Authentication Attempts and Successful Logins .......................................................................... 345 UserDirClass MethodSets or Retrieves the Directory Class if the Password Policy Applies to a Part of the Directory ..................................................................... 345 UserDirectory MethodSets or Retrieves the User Directory for the Password Policy .......... 346 UserDirPath MethodSets or Retrieves the Directory Path if the Password Policy Applies to a Part of the Directory ....................................................................... 346

Contents 15

Policy Methods................................................................................. 347 ActiveExpr MethodSets or Retrieves the Active Expression Associated with the Policy ....... 348 AddRule MethodAdds a Rule to the Policy ................................................. 348 AddUser MethodAdds a User to the Policy ................................................. 349 AllowNested MethodSets or Retrieves the AllowNested Flag ................................ 350 CreateIPHostConfigName MethodCreates an IP Address Configuration ...................... 351 CreateIPConfigRange MethodCreates an IP Address Configuration .......................... 351 CreateIPConfigSingleHost MethodCreates an IP Address Configuration ..................... 352 CreateIPConfigSubnetMask MethodCreates an IP Address Configuration Based on the IP Address and Subnet Mask .................................................................. 352 DeleteIPConfig MethodDeletes the Specified IP Configuration Object ....................... 353 Description MethodSets or Retrieves the Description of the Policy .......................... 354 EnforceANDEvaluation MethodSets or Retrieves the ANDUser/Group Flag ................... 354 ExcludeUser MethodExcludes or Includes a User from the Policy ........................... 355 GetAllIPConfigs MethodRetrieves All IP Address Restriction Objects in the Policy ............ 356 GetAllRules MethodRetrieves All Rules Associated with the Policy ........................... 357 GetAllUsers MethodRetrieves All Users Associated with the Policy .......................... 357 IsEnabled MethodEnables or Disables the Policy ........................................... 358 Name MethodSets or Retrieves the Policy Name ........................................... 358 RemoveResponse MethodRemoves the Response for a Configured Rule in the Policy ........ 359 RemoveRule MethodRemoves the Specified Rule from the Policy ........................... 360 RemoveUser MethodRemoves a User from the Policy ...................................... 360 SetResponse MethodSets the Response for a Configured Rule in the Policy ................. 361 VariableExpr MethodSets, Retrieves, or Removes the Active Expression Associated with the Policy .................................................................................. 361 Policy Server Connectivity Methods ............................................................. 362 GetPorts MethodDeprecated .............................................................. 362 GetServerAddress MethodRetrieves the Host Name or IP Address of the Policy Server ...... 363 GetServerPort MethodRetrieves TCP Port for Policy Server or Server Cluster ................ 363 Realm Methods ................................................................................ 364 Agent MethodSets or Retrieves the Agent for the Realm ................................... 365 AuthScheme MethodSets or Retrieves the Authentication Scheme for the Realm ............ 365 AzUserDir MethodSets or Retrieves the Authorization User Directory for the Realm ......... 366 CreateChildRealm MethodCreates and Configures a Child Realm ........................... 367 CreateRule MethodCreates and Configures a Rule under the Realm ......................... 369 DeleteChildRealm MethodDeletes a Top-level Realm within the Realm ...................... 370 DeleteRule MethodDeletes an Existing Rule within the Realm .............................. 371 Description MethodSets or Retrieves the Description of the Realm.......................... 372 Flush MethodFlushes the Realm from the Resource Cache ................................. 372 GetAllChildRealms MethodRetrieves All Top-level Realms within the Realm ................. 373 GetAllRules MethodRetrieves the Rules Associated with the Realm ......................... 373 GetChildRealm MethodRetrieves a Top-level Child Realm under the Realm .................. 374 GetDomain MethodRetrieves the Domain Associated with the Realm ....................... 374


GetRule MethodRetrieves an Existing Rule in the Realm .................................... 375 IdleTimeout MethodSets or Retrieves the Maximum Time a User Can Remain Inactive in the Realm ................................................................................. 375 MaxTimeout MethodSets or Retrieves the Maximum Time a User Can Access the Realm ..... 376 Name MethodSets or Retrieves the Realm Name .......................................... 376 ProcessAuEvents MethodSets or Retrieves the Authentication Event Flag in the Realm ...... 377 ProcessAzEvents MethodSets or Retrieves the Authorization Event Flag in the Realm ........ 378 ProtectResource MethodSets or Retrieves the Current Resource Protection Flag Example .... 378 RegScheme MethodSets or Retrieves the Registration Scheme for the Realm ............... 379 ResourceFilter MethodSets or Retrieves the Realm Resource Filter ......................... 380 SyncAudit MethodSets or Retrieves the Synchronous Auditing Flag ......................... 380 Registration Scheme Methods .................................................................. 381 Description MethodSets or Retrieves the Registration Scheme Description .................. 381 EnableLogging MethodEnables or Disables Registration Scheme Logging .................... 382 Name MethodSets or Retrieves the Registration Scheme Name ............................ 382 TemplatePath MethodSets or Retrieves the Path of the Registration Scheme ................ 383 UserDirectory MethodSets or Retrieves the User Directory for the Registration Scheme ..... 384 WelcomePageURL MethodSets or Retrieves the Welcome Page URL for the Registration Scheme ................................................................................... 384 Response Methods ............................................................................. 385 CreateActiveAttribute MethodCreates an Active Response Attribute for the Response........ 385 CreateAttribute MethodCreates a Static Response Attribute for the Response ............... 386 CreateVariableAttribute MethodCreates a Variable Definition Response Attribute for the Response .................................................................................. 388 DeleteAttribute MethodDeletes a Response Attribute in the Response ...................... 389 Description MethodSets or Retrieves the Response Description ............................. 389 GetAllAttributes MethodRetrieves a List of Configured Response Attributes ................. 390 Name MethodSets or Retrieves the Response Name ....................................... 390 Response Attribute Methods .................................................................... 391 GetActiveExpr MethodRetrieves Any Active Expression Defined for the Response Attribute........................................................................................... 391

GetAgentTypeAttrName MethodRetrieves the Name of the Agent Type Attribute ............ 392 GetTTL MethodRetrieves the Time To Live (TTL) Setting ................................... 392 GetValue MethodRetrieves the Response Attribute Value ................................... 393 GetVariable MethodRetrieves the Variable Object in the Response Attribute's Active Expression................................................................................. 393 Rule Methods .................................................................................. 394 AccessType MethodSets or Retrieves the Flag that Allows or Denies Access to the Resource Protected by the Rule ...................................................................... 394 Action MethodSets or Retrieves the Action for the Rule .................................... 395 ActiveExpr MethodSets or Retrieves the Active Expression for the Rule ..................... 396 Agent MethodSets or Retrieves an Agent Object or an Agent Group Object Associated with the Global Rule ............................................................................ 397

Contents 17

Description MethodSets or Retrieves the Description of the Rule ........................... 398 IsEnabled MethodEnables or Disables the Rule ............................................ 398 Name MethodSets or Retrieves the Rule Name ............................................ 399 RegexMatch MethodDetermines whether Regular Expression Pattern Matching Is Enabled ... 399 Resource MethodSets or Retrieves the Resource Protected by the Rule ..................... 400 SAML 2.0 Affiliation Methods ................................................................... 401 GetAffiliatedSAMLAuthSchemes MethodRetrieves the SAML 2.0 Authentication Schemes Associated with This SAML Affiliation ........................................................ 401 GetAffiliatedSAMLServiceProviders MethodRetrieves the SAML 2.0 Service Providers Associated with this SAML Affiliation ........................................................ 402 Property MethodSets or Retrieves the Specified SAML 2.0 Metadata Property ............... 402 Save MethodSaves the Changes to the SAML 2.0 Metadata Properties of this SAML 2.0 Affiliation .................................................................................. 403 SAML 2.0 Indexed Endpoint Methods ........................................................... 404 GetACSIndex MethodRetrieves Index Value of Assertion Consumer Service Object .......... 404 GetACSBinding MethodRetrieves Protocol Binding of Assertion Consumer Service Object .... 405 GetACSURL MethodRetrieves URL Value of Assertion Consumer Service Object ............. 405 GetIsDefault MethodRetrieves IsDefault Value for Assertion Consumer Service Object ...... 406 SAML 2.0 Requester Attribute Methods ......................................................... 406 GetAttrNameFormat MethodRetrieves SAML Requester Attribute's Name Format ............ 406 GetLocalName MethodRetrieves SAML Requester Attribute's Local Name ................... 407 GetName MethodRetrieves SAML Requester Attribute's Name .............................. 407 SAML 2.0 Service Provider Methods ............................................................ 408 AddAssertionConsumerService MethodAdds an Assertion Consumer Service to a SAML Service Provider Object .................................................................... 409 AddAttribute MethodAdds an Attribute to the SAML 2.0 Service Provider.................... 409 AddUser MethodAdds a User to the SAML 2.0 Service Provider ............................. 411 CreateIPConfigHostName MethodCreates an IP Configuration Object for the Service Provider ................................................................................... 411 CreateIPConfigRange MethodCreates an IP Configuration Object for the Service Provider.... 412 CreateIPConfigSingleHost MethodCreates an IP Configuration Object for the Service Provider ................................................................................... 413 CreateIPConfigSubnetMask MethodCreates an IP Configuration Object for the Service Provider ................................................................................... 414 DeleteIPConfig MethodDeletes Specified IP Configuration Object ........................... 414 GetAllAttributes MethodRetrieves All Attributes for SAML 2.0 Service Provider .............. 415 GetAllIPConfigs MethodRetrieves All IP Configuration Objects .............................. 416 GetAllAssertionConsumerServices MethodRetrieves All Assertion Consumer Services ........ 416 GetAllUsers MethodRetrieves All Users .................................................... 417 Property MethodSets or Retrieves Metadata Property ...................................... 417 RemoveAssertionConsumer MethodRemoves Assertion Consumer Service .................. 418 RemoveAttribute MethodRemoves Specified Attribute ...................................... 419 RemoveUser MethodRemoves Specified User .............................................. 420


Save MethodSaves Changes Made to Metadata Properties ................................. 420 SAML 2.0 Service Provider Attribute Methods ................................................... 421 GetAttrNameFormat MethodRetrieves Format of Attribute Names .......................... 421 GetValue MethodRetrieves Service Provider Attribute Value ................................ 422 Session Methods ............................................................................... 422 AddAttributeToSAMLScheme MethodAdds New Attribute to Authentication Scheme ......... 426 AddTrustedHost MethodCreates or Modifies Trusted Host Object ........................... 427 CreateAdmin MethodCreates System-Level Administrator .................................. 428 CreateAffDomain MethodCreates Affiliate Domain ......................................... 429 CreateAgent MethodCreates SiteMinder Agent ............................................. 430 CreateAgentConfig MethodCreates Agent Configuration Object ............................. 431 CreateAgentGroup MethodCreates Agent Group ........................................... 431 CreateAuthAzMap MethodCreates Directory Mapping Object ............................... 432 CreateAuthScheme MethodCreates Authentication Scheme ................................ 433 CreateCustomCertMap MethodCreates Custom Certificate Map ............................. 435 CreateDataManager MethodCreates Data Manager Object.................................. 436 CreateDomain MethodCreates Policy Domain Object ....................................... 438 CreateExactCertMap MethodCreates Certificate Map Matching User Directory Attributes ..... 439 CreateGlobalPolicy MethodCreates Global Policy ........................................... 440 CreateGlobalResponse MethodCreates Global Response .................................... 441 CreateGlobalRule MethodCreates Global Rule .............................................. 441 CreateHostConfig MethodCreates Host Configuration Object ............................... 443 CreateODBCQueryScheme MethodCreates ODBC Query Scheme ........................... 444 CreatePwdPolicy MethodCreates Password Policy .......................................... 447 CreateRegScheme MethodCreates Registration Scheme.................................... 451 CreateSAMLAffiliation MethodCreates SAML 2.0 Affiliation Object ........................... 453 CreateSAMLAuthScheme MethodCreates SAML Authentication Scheme Object .............. 454 CreateSingleCertMap MethodCreates Single-Attribute Certificate Map ...................... 458 CreateTrustedHost MethodCreates Trusted Host Object .................................... 459 CreateUserDir MethodCreates User Directory Object ....................................... 460 CreateWSFEDAuthScheme MethodCreates WS-Federation Authentication Scheme .......... 465 DeleteAdmin MethodDeletes Administrator ................................................ 467 DeleteAffDomain MethodDeletes Affiliate Domain .......................................... 467 DeleteAgent MethodDeletes Agent ........................................................ 468 DeleteAgentConfig MethodDeletes Agent Configuration Object ............................. 468 DeleteAuthAzMap MethodDeletes Authentication and Authorization Map .................... 469 DeleteAuthScheme MethodDeletes Authentication Scheme ................................. 470 DeleteCertMap MethodDeletes Certificate Map ............................................. 470 DeleteDomain MethodDeletes Policy Domain .............................................. 471 DeleteGlobalPolicy MethodDeletes Global Policy ........................................... 471 DeleteGlobalResponse MethodDeletes Global Response .................................... 472 DeleteGlobalRule MethodDeletes Global Rule .............................................. 473

Contents 19

DeleteGroup MethodDeletes Agent Group ................................................. 473 DeleteHostConfig MethodDeletes Host Configuration Object ................................ 474 DeleteODBCQueryScheme MethodDeletes ODBC Query Scheme ........................... 474 DeletePwdPolicy MethodDeletes Password Policy .......................................... 475 DeleteRegScheme MethodDeletes Registration Scheme .................................... 476 DeleteSAMLAffiliation MethodDeletes SAML Affiliation ...................................... 476 DeleteTrustedHost MethodDeletes Trusted Host ........................................... 477 DeleteUserDir MethodDeletes User Directory .............................................. 477 GetAdmin MethodRetrieves Administrator ................................................. 478 GetAffDomain MethodRetrieves Affiliate Domain ........................................... 479 GetAgent MethodRetrieves Agent ......................................................... 479 GetAgentConfig MethodRetrieves Agent Configuration Object .............................. 480 GetAgentGroup MethodRetrieves Agent Group ............................................ 480 GetAgentType MethodRetrieves Agent Type ............................................... 481 GetAllAdmins MethodRetrieves List of All Administrators ................................... 482 GetAllAffDomains MethodRetrieves List of All Affiliate Domains ............................. 482 GetAllAgentConfigs MethodRetrieves List of All Agent Configuration Objects ................ 483 GetAllAgentGroups MethodRetrieves List of All Agent Group Objects........................ 483 GetAllAgents MethodRetrieves List of All Agents ........................................... 484 GetAllAuthAzMaps MethodRetrieves List of All AuthAz Maps ................................ 484 GetAllAuthSchemes MethodRetrieves List of Authentication Schemes ....................... 485 GetAllCertMaps MethodRetrieves List of Certificate Mapping Objects ........................ 485 GetAllDomains MethodRetrieves List of All Domains ....................................... 486 GetAllGlobalPolicies MethodRetrieves List of Global Policy Objects .......................... 486 GetAllGlobalResponses MethodRetrieves List of All Global Response Objects ................ 487 GetAllGlobalRules MethodRetrieves List of All Global Rule Objects .......................... 487 GetAllHostConfigs MethodRetrieves List of All Host Configuration Objects ................... 488 GetAllODBCQuerySchemes MethodRetrieves List of All ODBC Query Schemes............... 488 GetAllPwdPolicies MethodRetrieves List of All Password Policies ............................ 489 GetAllRegSchemes MethodRetrieves List of All Registration Schemes ....................... 489 GetAllSAMLAffiliations MethodRetrieves List of All SAML 2.0 Affiliations ..................... 490 GetAllSAMLSchemeAttributes MethodRetrieves List of All Requester Attributes .............. 490 GetAllTrustedHosts MethodRetrieves List of All Trusted Host Objects ....................... 491 GetAllUserDirs MethodRetrieves List of All User Directories ................................. 491 GetAllVariableTypes MethodRetrieves List of All Variable Type Objects ...................... 492 GetAuthScheme MethodRetrieves Authentication Scheme Object ........................... 492 GetCertMap MethodRetrieves Certificate Mapping Object................................... 494 GetDomain MethodRetrieves Domain Object .............................................. 494 GetGlobalPolicy MethodRetrieves Global Policy Object ..................................... 495 GetGlobalResponse MethodRetrieves Global Response Object .............................. 495 GetGlobalRule MethodRetrieves Global Rule Object ........................................ 496 GetHostConfig MethodRetrieves Host Configuration Object ................................. 497


GetODBCQueryScheme MethodRetrieves ODBC Query Scheme Object...................... 497 GetPwdPolicy MethodRetrieves Password Policy Object..................................... 498 GetRegScheme MethodRetrieves Registration Scheme Object .............................. 498 GetSAMLAffiliation MethodRetrieves SAML 2.0 Affiliation Object ............................ 499 GetSAMLAffiliationById MethodRetrieves SAML 2.0 Affiliation Object by ID.................. 500 GetSharedSecretPolicy MethodRetrieves Shared Secret Policy Object ....................... 500 GetTrustedHost MethodRetrieves Trusted Host Object ..................................... 501 GetUserDir MethodRetrieves User Directory Object ........................................ 501 GetVariableType MethodRetrieves Variable Type Object.................................... 502 RemoveAttributeFromSAMLScheme MethodRemoves Attribute from SAML Scheme ......... 503 SAMLAuthSchemeProperties MethodSets or Retrieves SAML Metadata Properties ........... 504 WSFEDAuthSchemeProperties MethodSets or Retrieves WS-Federation Properties .......... 505 Shared Secret Rollover Methods ................................................................ 506 Enabled MethodSets or Retrieves Rollover Enabled Flag for Policy .......................... 506 RolloverFrequency MethodSets or Retrieves Rollover Frequency for Policy .................. 507 RolloverPeriod MethodSets or Retrieves Rollover Period for Policy .......................... 508 Save MethodSaves Shared Secret Policy Object ........................................... 509 Trusted Host Methods .......................................................................... 509 GetDescription MethodRetrieves Description of Trusted Host ............................... 510 GetIPAddress MethodRetrieves IP Address of Trusted Host ................................. 510 GetName MethodRetrieves Name of Trusted Host ......................................... 511 GetSecret MethodRetrieves Shared Secret of Trusted Host ................................. 511 RolloverEnabled MethodSets or Retrieves Shared Secret Rollover Flag ...................... 512 SetSecret MethodSets Shared Secret of Trusted Host ...................................... 513 User Methods .................................................................................. 514 DisableByAdmin MethodSets or Retrieves Disabled-by-Administrator Flag .................. 514 DisableInactive MethodSets or Retrieves Disabled-by-Inactivity Flag ....................... 515 DisableMaxLoginFail MethodSets or Retrieves Disabled-by-Max-Login-Failure Flag .......... 517 DisablePwdExpired MethodSets or Retrieves Disabled-by-Password-Expired Flag ............ 518 ForcePwdChange MethodSets or Retrieves Force-Password-Change Flag .................... 519 GetClass MethodRetrieves User Class ..................................................... 520 GetPath MethodRetrieves User Path....................................................... 521 SetPassword MethodSets a New Password ................................................ 521 UserPasswordState MethodSets or Retrieves Password State Object ........................ 522 ValidatePassword MethodValidates Password .............................................. 523 User Directory Methods ........................................................................ 524 AnonymousIDAttr MethodSets or Retrieves Anonymous DN Name .......................... 525 ChalRespAttr MethodSets or Retrieves Challenge/Response Name .......................... 525 Description MethodSets or Retrieves Description of User Directory ......................... 526 DisabledAttr MethodSets or Retrieves Name of Disabled Attribute .......................... 527 EmailAttr MethodSets or Retrieves Email Attribute Name .................................. 527 EnableSecurityContext MethodSets or Retrieves Security Context Flag ..................... 528

Contents 21

GetContents MethodRetrieves All Users in User Directory .................................. 529 GetNamespace MethodRetrieves User Directory Namespace ............................... 529 IsSecure MethodSets or Retrieves Secure Authentication Flag .............................. 530 LookupEntry MethodRetrieves Users that Match Specified Pattern .......................... 531 MaxResults MethodSets or Retrieves Maximum Search Results ............................. 531 Name MethodSets or Retrieves User Directory Name ...................................... 532 ODBCQueryScheme MethodSets or Retrieves ODBC Query Scheme ........................ 533 Password MethodSets or Retrieves User Password ......................................... 533 PwdAttr MethodSets or Retrieves Password Attribute Name ................................ 534 PwdDataAttr MethodSets or Retrieves Password Data Attribute Name ...................... 535 RequireCredentials MethodSets or Retrieves Whether Credentials Are Required ............. 535 SearchRoot MethodSets or Retrieves Directory Search Root ................................ 536 SearchScope MethodSets or Retrieves LDAP Directory Search Scope ....................... 537 SearchTimeout MethodSets or Retrieves Maximum Directory Search Time .................. 538 Server MethodSets or Retrieves a Directory-Dependent Value ............................. 539 UIDAttr MethodSets or Retrieves Universal ID Attribute Name ............................. 540 UserLookupEnd MethodSets or Retrieves User DN Lookup Endpoint ........................ 541 UserLookupStart MethodSets or Retrieves User DN Lookup Starting Point .................. 542 Username MethodSets or Retrieves Username............................................. 543 ValidateEntry MethodValidates User Directory Entry ....................................... 543 User Password State Methods .................................................................. 544 DisabledTime MethodSets or Retrieves Time Object Was Disabled .......................... 544 LastPWChangeTime MethodSets or Retrieves Time Password Last Changed ................. 545 LastLoginTime MethodSets or Retrieves Last Login Time ................................... 546 LoginFailures MethodSets or Retrieves Number of Login Failures ........................... 546 Variables Methods ............................................................................. 547 Definition MethodSets or Retrieves Variable Object's Definition ............................. 547 Description MethodSets or Retrieves Variable Object's Description ......................... 548 GetName MethodRetrieves Variable Name ................................................ 548 GetReturnType MethodRetrieves Data Type of Variable Value .............................. 549 GetVariableType MethodRetrieves Variable Type Object.................................... 550 MetaData MethodSets or Retrieves MetaData for TransactionMinder ........................ 550 NestedVariables MethodSets or Retrieves Nested Variables ................................ 551 Variable Type Methods ......................................................................... 552 GetDescription MethodRetrieves Description of Variable Type Object ....................... 552 GetName MethodRetrieves Name of Variable Type Object .................................. 552 WS-Federation Resource Partner Methods ...................................................... 553 AddAttribute MethodAdds Attribute to Resource Partner ................................... 553 AddUser MethodAdds User to Resource Partner............................................ 554 CreateIPConfigHostName MethodCreates Object Based on Specified Host................... 555 CreateIPConfigSingleHost MethodCreates Object Based on Single Address .................. 556 CreateIPConfigSubnetMask MethodCreates Object Based on Subnet Address ............... 556


DeleteIPConfig MethodDeletes Specified IP Configuration Object ........................... 557 GetAllAttributes MethodRetrieves All Attributes for Resource Partner ....................... 558 GetAllIPConfigs MethodRetrieves All IP Configuration Objects for Service Provider .......... 558 GetAllUsers MethodRetrieves All Users Associated with Resource Partner ................... 559 Property MethodSets or Retrieves Resource Partner Property .............................. 559 RemoveUser MethodRemoves Specified User from Resource Partner ....................... 560 Save MethodSaves Resource Partner's Metadata .......................................... 561 WS-Federation Resource Partner Attribute Methods ............................................. 561 GetAttrNameFormat MethodRetrieves Format of Attribute Names .......................... 562 GetValue MethodRetrieves Attribute Value ................................................ 562

Chapter 7: Policy Management Operations

563

Initialize a Session ............................................................................. 563 Create and Manage System Objects ............................................................ 565 Create Agent Objects ...................................................................... 566 View and Modify Object Properties .......................................................... 566 Objects with Domain Scope .................................................................... 567 Retrieve One Object to Create Another...................................................... 568 Manage an Objects Properties.............................................................. 568 Objects with Domain Scope or Global Scope .................................................... 570 Authorization Variables ........................................................................ 572 Configure a Variable for a Particular Variable Type .......................................... 572 Save Changes to Objects....................................................................... 577 Policy Store Object Migration ................................................................... 578 Sequence of Calls .......................................................................... 578 Export Realm Objects ...................................................................... 581 Import Realm Objects ...................................................................... 582 Modify a Password Policy ....................................................................... 584 Manage Password State ........................................................................ 584 Create Responses and Response Attributes ..................................................... 586 Update Realms with a New Authentication Scheme .............................................. 587 View Default Values for an Authentication Scheme Template ..................................... 588 Create an Authentication Scheme .............................................................. 589 Modify the Shared Secret Rollover Policy ........................................................ 590 Write a Domain and Realm Report to a File ..................................................... 591 Disable Authentication and Authorization Event Processing ...................................... 592 Manage Policy Server Load Distribution ......................................................... 593 Cluster Configuration ....................................................................... 594 When All Clusters Fail ...................................................................... 595

Contents 23

Appendix A: Command Line Interface Restrictions Appendix B: Property References

599 601

SAML 2.0 Properties ........................................................................... 601 WSFED Properties ............................................................................. 640

Index

659


Chapter 1: Perl Scripting OverviewThis section contains the following topics: About the SiteMinder Command Line Interface (see page 25) Installation Path (see page 26) Where to Run Your Scripts (see page 26) CLI Example: Create a Policy Store Object (see page 27) CLI Example: View and Set Individual Properties (see page 28) Location of Sample Scripts (see page 29) Related Documentation (see page 29)

About the SiteMinder Command Line InterfaceThe SiteMinder Command Line Interface (CLI) lets you perform SiteMinder tasks by running custom Perl scripts from the command line. The scripting interface contains the following APIs: Agent APILets you test whether access control of protected resources is behaving according to policy definitions. Policy Management APILets you design and administer policy stores.

The Command Line Interface provides: A quick and light-weight alternative to the Administrative UI. An efficient way to perform Policy Server design and administrative tasks over multiple policy stores. The ability to migrate individual objects between policy stores.

The Command Line Interface lets you perform most, but not all, of the policy store operations you can perform through the Administrative UI.

More Information: Command Line Interface Restrictions (see page 599)

Chapter 1: Perl Scripting Overview 25

Installation Path

Installation PathBy default, the SiteMinder Command Line Interface is installed in the following location: /CLI is the root directory where you installed your Policy Server software.

Perl LocationA complete version of Perl is installed along with the Policy Server. When you run scripts against the Command Line Interface, you should use the Perl interpreter that is installed with the Policy Server rather than any other Perl interpreter that might be on your system. The installation program installs Perl in the following default location: /CLI/bin If you have another version of Perl installed on your system, make sure that the Perl location shown above comes before any other Perl location in your systems PATH environment variable.

Where to Run Your ScriptsThe Perl Agent and Policy Management APIs can be used on the following machines: Agent APIOn the machine where a Policy Server is installed. The Agent API can access the local Policy Server or a remote Policy Server. Policy Management APIOn the machine where a Policy Server is installed.

To run a script against these APIs, use the following command line syntax:perl scriptname

Note: A script built with the Policy Management API must run as the same user who installed the Policy Server (for example, smuser on UNIX platforms).


CLI Example: Create a Policy Store Object

CLI Example: Create a Policy Store ObjectSuppose you are an administrator for the domain engineering. You want to create the realm documentation in that domain. Using the Administrative UI, you might take the following steps: 1. Log into the SiteMinder Administration software. 2. Right-click the domain engineering where you are adding the realm. 3. Click Create Realm and provide the following configuration information for the fields on the Resource tab: Name: documentation Description: Source files for manuals Agent: agent1 Resource Filter: /mysite/docs/* Authentication Scheme: Basic

You are accepting all other defaults for the realm (including resource protection, which is enabled by default). 4. Click OK to confirm the creation of the new realm. If you write a script to perform the same operation, it might look like this:#Initialize the Policy Management API use Netegrity::PolicyMgtAPI; $policyapi = Netegrity::PolicyMgtAPI->New(); print "Step 1. Log in the admin and create an API session.\n"; $session = $policyapi->CreateSession("adminid", "adminpwd"); print "Step 2. Select the domain for the new realm.\n"; $domain=$session->GetDomain("engineering"); #Get the realms agent and authorization scheme info.\n"; $agent=$session->GetAgent("agent1"); $authscheme=$session->GetAuthScheme("Basic");


CLI Example: View and Set Individual Properties

print "Step 3. Create and configure the realm.\n"; $realm=$domain->CreateRealm("documentation", $agent, $authscheme, "Source files for manuals", "/mysite/docs/*" ); print "Step 4. Confirm the creation of the realm.\n"; if ($realm == undef) { print "Realm creation failed.\n"; } else { print "Realm creation succeeded.\n"; }

Note: Generally, policy store object names are case-sensitive. In the above example, the Basic authentication scheme and the engineering domain are case-sensitive. Further, agent names are always written to the policy store in lowercase. Existing agents must be referenced in lowercase in your scripts.

CLI Example: View and Set Individual PropertiesPolicy Management API objects (such as PolicyMgtRealm) provide a number of get/set methods that let you view and modify individual properties of objects in the policy store. You use these get/set methods to view and edit an objects properties just as you would use the property fields in the Administrative UI. The following script modifies the resource filter property:use Netegrity::PolicyMgtAPI; $policyapi = Netegrity::PolicyMgtAPI->New(); $session = $policyapi->CreateSession("adminid", "adminpwd"); $domain=$session->GetDomain("engineering"); $realm=$domain->GetRealm("documentation"); if($realm->ResourceFilter() eq "/mysite/docs/*") { $filter=$realm->ResourceFilter("/mysite/docs/*.doc"); }


Location of Sample Scripts

if ($filter eq undef) { print "Error changing resource filter.\n"; } else { print "Resource filter changed to: " . $filter . "\n"; }

Note the following general rules: When you pass an argument into a method, the method behaves as a setter methodfor example:$realm->ResourceFilter("/mysite/docs/*.doc");

When no argument is given, the method behaves as a getter methodfor example:$filter=$realm->ResourceFilter();

With get and set methods, the existing or new property value is returned.

Location of Sample ScriptsSample scripts are installed in the following default location: /CA/siteminder/CLI/examples Before using a sample script, be sure to change the values of the site-specific variables (such as administrators credentials and user-store location) that are defined at the beginning of the script.

Related DocumentationYou can find additional information about Policy Server and agent operations in the following SiteMinder documents: CA SiteMinder Policy Server Configuration Guide CA SiteMinder Policy Server Administration Guide CA SiteMinder Web Agent Configuration Guide

Object Dependencies PosterThe poster Scripting Interface for Perl: Object Dependencies is included with SiteMinder. The poster illustrates the Perl objects that you need to create or retrieve before you can manipulate dependent objects. Each object is shown with all of its methods.


Chapter 2: Agent APIThis section contains the following topics: About Agents and the Agent API (see page 31) Write a Script against the Agent API (see page 32) Single Sign-on and the Agent API (see page 33) Session Information (see page 35) Objects and the Object Hierarchy (see page 37)

About Agents and the Agent APIA SiteMinder agent enforces access control policies provided by the Policy Server. Agents act as gate keepers that protect resources from unauthorized users. When a user issues a request for a resource, the request is routed through the agent. The agent determines whether to accept or reject the request based on the information it receives from the Policy Server. The Agent API (module Netegrity::AgentAPI) lets you write scripts that test the operation of your agents. The tasks you can perform with the Agent API include many of the tasks you can perform with the SiteMinder Test Tool. The Agent API also lets you view information about the users session. The following illustration shows some of the operations you can perform with the Agent API:

Web Server Web Agent

Protected Resources

Command Line Interface

User Session Management Resource Protection Authentication and Authorization Response and Response Attributes

Test Agent Operations

Chapter 2: Agent API 31

Write a Script against the Agent API

Write a Script against the Agent APIAll scripts require certain common basic steps. To write a script against the Agent API 1. Reference the Agent API at the beginning of your script: 2. Use the New() method to create an Agent API object:$agentapi=Netegrity::AgentAPI->New("agtName","shrdScrt");

Note: Specifying the shared secret in the second argument creates a v4.x agent. Omitting the shared secret creates a v5.x or 6.x agent. 3. Provide configuration information about the Policy Server. The IP address is required, but you can accept the defaults for other arguments:$serverconfig = $agentapi->AddServerConfig($ipAddr);

4. Connect to the Policy Server: With v4.x agents:

$agentapi->Connect();

With v5.x and later agents:

$agentapi->Connect("../../../../Program Files/Netegrity/webagent/config/smhost.conf");

Example: Verify the protection on a resource After you have completed these basic steps, you can perform various agent operations. For example, you can see whether a specified resource is protected by the agent, and if so, you can find out the credentials that are required to access the resource:$resource = $agentapi->GetResource("/companyXYZ/private/"); if($resource->IsProtected() == SM_AGENTAPI_YES) { print "\nAuthentication Type: ".$resource->GetAuthType(); } else { print "The resource is not protected."; }


Single Sign-on and the Agent API

Single Sign-on and the Agent APIIn a single sign-on environment, a user who successfully authenticates through a given agent does not need to re-authenticate when accessing a realm protected by a different agent. When a custom agent is involved in a single sign-on environment, the two agents must be in the same cookie domainfor example, xxx.domainname.com. Single sign-on is made possible through a single sign-on cookie named SMSESSION. This cookie is created and written to the users browser either by SiteMinder or by the custom agent. The cookies contents are retrieved from and written to the cookie in encrypted string form. The encrypted string is called a token. The Agent API contains the following methods that allow custom agent scripts to share token information with standard SiteMinder Web Agents: CreateSSOToken(). After the user successfully logs in, the custom agent script passes information about the user to this method. The method creates a single sign-on token object from this user information and from session information returned from the login call. GetString(). After creating a token object, the custom agent script calls GetString() to retrieve the token as an encrypted string. The script then writes the token string to the SMSESS

Date post:	27-Oct-2014
Category:	Documents
Upload:	jose-rosario
View:	143 times
Download:	4 times

Siteminder Perl Scripting Enu

Documents