CA eTrust SiteMinder Developer's Guide for Java

This documentation and any related computer software help programs (hereinafter referred to as the“Documentation”) is for the end user’s informational purposes only and is subject to change or withdrawal by CA atany time.This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or inpart, without the prior written consent of CA. This Documentation is confidential and proprietary information of CAand protected by the copyright laws of the United States and international treaties.Notwithstanding the foregoing, licensed users may print a reasonable number of copies of the Documentation fortheir own internal use, and may make one copy of the related software as reasonably required for back-up anddisaster recovery purposes, provided that all CA copyright notices and legends are affixed to each reproduced copy.Only authorized employees, consultants, or agents of the user who are bound by the provisions of the license forthe Product are permitted to have access to such copies.The right to print copies of the Documentation and to make a copy of the related software is limited to the periodduring which the applicable license for the Product remains in full force and effect. Should the license terminate forany reason, it shall be the user’s responsibility to certify in writing to CA that all copies and partial copies of theDocumentation have been returned to CA or destroyed.EXCEPT AS OTHERWISE STATED IN THE APPLICABLE LICENSE AGREEMENT, TO THE EXTENT PERMITTED BYAPPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION “AS IS” WITHOUT WARRANTY OF ANY KIND, INCLUDINGWITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSEOR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER OR ANY THIRD PARTY FOR ANYLOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUTLIMITATION, LOST PROFITS, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLYADVISED OF SUCH LOSS OR DAMAGE.The use of any product referenced in the Documentation is governed by the end user’s applicable licenseagreement.The manufacturer of this Documentation is CA.Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to therestrictions 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.All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.Copyright © 2008 CA. All rights reserved.

CA Product ReferencesThis document references the following CA products:CA eTrust ® SiteMinder ®Contact Technical SupportFor online technical assistance and a complete list of locations, primary servicehours, and telephone numbers, contact Technical Support athttp://ca.com/support.

ContentsChapter 1: Java API Overview 11Purpose of the Java APIs ...................................................................... 11Installation Path .............................................................................. 11Code Samples ................................................................................ 12Policy Server Prerequisite ..................................................................... 12Java Components of the SiteMinder SDK ....................................................... 13Java Agent API ............................................................................... 13Policy Management API ....................................................................... 14Authentication API ............................................................................ 14Authorization API ............................................................................. 15Delegated Management Services API........................................................... 15Utilities Package .............................................................................. 15How Java Components Fit Together ............................................................ 16Network Architecture ......................................................................... 16Java API Flow ................................................................................ 17Establish a Connection to the Policy Server ................................................. 17Obtain a Session.......................................................................... 21Make API Requests and Handle Results..................................................... 23Log Trace Information ........................................................................ 23Javadoc Reference ............................................................................ 24Support for Custom Code ..................................................................... 24Chapter 2: Utilities Package 25Purpose of the Utilities Package................................................................ 25Classes for Internal Use ....................................................................... 25Connection Class ............................................................................. 26Session Class................................................................................. 26Result Class .................................................................................. 27Interpret a Result Object .................................................................. 28Core Methods in the Result Class .......................................................... 29Exception Class............................................................................... 29Property Class................................................................................ 30Chapter 3: Agent API 31SiteMinder Agents ............................................................................ 31Agent API Class Hierarchy..................................................................... 32Contents 5

Implement the JNI Java Agent API............................................................. 33Implement the Pure Java Agent API............................................................ 34Connection to a Policy Server.................................................................. 36User Access to Resources ..................................................................... 37How Web Agents Use the Agent API ........................................................... 39Java Agent API Services ...................................................................... 40Session Services.............................................................................. 40Session Creation and the Session Specification ............................................. 40Session Validation ........................................................................ 41Session Delegation........................................................................ 41Session Termination ...................................................................... 42Authorization Services ........................................................................ 42Auditing Services and Transaction Tracking..................................................... 42Management Services......................................................................... 43Cache Commands......................................................................... 43Encryption Commands .................................................................... 43Tunnel Services .............................................................................. 44Response Attributes .......................................................................... 44Single Sign-on ............................................................................... 45Log on through a Custom Agent ........................................................... 45Log on through a Standard Agent .......................................................... 46Standard Agent Support................................................................... 47How Information Is Bound to a Session .................................................... 47Advantages of Session Variables ........................................................... 48Requirements for Using Session Variables .................................................. 48End of Session Cleanup ................................................................... 48Server Clusters ............................................................................... 48Clustered and Non-Clustered Servers ...................................................... 49Cluster Configuration...................................................................... 49Cluster Failover ........................................................................... 50Timeouts..................................................................................... 51Agent Type................................................................................... 52Chapter 4: Policy Management API 53About Policy Management ..................................................................... 54Policy Management Setup ..................................................................... 55Required JAR File ............................................................................. 55Policy Store Objects .......................................................................... 55Write a Policy Management Application......................................................... 57Establish a Connection to the Policy Server ................................................. 57Obtain a Session Object ................................................................... 58Pass in the Session Object................................................................. 586 Developer's Guide for Java

Make Policy Management API Requests..................................................... 58Terminate the Administrator Session ....................................................... 58Administrator Methods ........................................................................ 59Agent Methods ............................................................................... 59Agent Configuration Object Methods ........................................................... 60Authentication and Authorization Map Methods ................................................. 60Authentication Scheme Methods ............................................................... 61Certificate Map Methods....................................................................... 61Domain Methods ............................................................................. 61General Object Methods....................................................................... 62Group Methods ............................................................................... 63Host Configuration Object Methods ............................................................ 63ODBC Query Scheme Methods................................................................. 64Password Policy Methods ...................................................................... 64Policy Methods ............................................................................... 65Policy Migration Methods ...................................................................... 65Realm Methods ............................................................................... 66Response Methods ............................................................................ 66Root Configuration Methods ................................................................... 67Rule Methods................................................................................. 67Self-Registration Methods ..................................................................... 68Trusted Host Object Methods .................................................................. 68User Directory Methods ....................................................................... 68User Policy Methods .......................................................................... 69Utility Methods ............................................................................... 70Object Associations ........................................................................... 70Add Objects to the Policy Store ................................................................ 71Retrieve Objects from the Policy Store ......................................................... 72Delete Objects from the Policy Store ........................................................... 72Authentication Scheme Configuration .......................................................... 72Configuration Information ................................................................. 75Performance Consideration ................................................................... 111Chapter 5: Authentication and Authorization APIs 113Configuration of All Custom Classes........................................................... 113Custom Classes for Authentication and Authorization........................................... 114Required Library File ......................................................................... 114Shared Information .......................................................................... 115Common Classes ............................................................................ 115Create a Custom Authentication Scheme ...................................................... 116Classes and Interfaces in the Authentication API ........................................... 116How SiteMinder Loads a Custom Authentication Scheme.................................... 118Contents 7

How SiteMinder Initializes Authentication Processing ....................................... 119Supported Credentials.................................................................... 121User Disambiguation and Authentication................................................... 121Redirection .............................................................................. 124Authentication Events .................................................................... 124Extend the SAML and WS-Federation Authentication Schemes .............................. 125Use the Authorization API .................................................................... 127Active Expressions ....................................................................... 128Classes and Interfaces in the Authorization API ............................................ 130Custom Authentication Scheme Configuration.............................................. 131Active Policy Configuration ............................................................... 132Active Rule Configuration................................................................. 133Active Response Configuration ............................................................ 134Modify a SAML Assertion or Response ..................................................... 134Chapter 6: Delegated Management Services API 139About the DMS API .......................................................................... 139The Required JAR File ........................................................................ 140SiteMinder User Directories................................................................... 140SiteMinder User Directory Containers...................................................... 141Attribute-based Delegation ................................................................... 142Configure Attribute-based Delegation ..................................................... 143DMS Users .................................................................................. 143Implementation Class........................................................................ 144Context Class ............................................................................... 144Object Class................................................................................. 145Object Model ............................................................................ 145Search Class ................................................................................ 146Cursor Class ................................................................................ 146Searches that Support Cursor Operations.................................................. 147Searches of Microsoft LDAP Directories .................................................... 147Write a Directory Management Application .................................................... 148DMS Context ............................................................................ 150Directory Context ........................................................................ 152Change the User Type in DMS Context .................................................... 152Create an Object......................................................................... 154Get Directory Entry Attributes ............................................................ 154Add an Object to a Directory.............................................................. 155Add a User to a Group ................................................................... 156Add a User to a Role ..................................................................... 156Get, Modify, or Delete an Object .......................................................... 156Searches.................................................................................... 1578 Developer's Guide for Java

Set Search Parameters When You Create the Search Object ................................ 158Set Search Parameters After Creating the Search Object ................................... 158Set the Search Filter ..................................................................... 160Search an Organization .................................................................. 162Examples of a Search .................................................................... 163User Password State ......................................................................... 164ODBC Support............................................................................... 165Restricted Methods .......................................................................... 166Index 169Contents 9

Chapter 1: Java API OverviewThis section contains the following topics:Purpose of the Java APIs (see page 11)Installation Path (see page 11)Code Samples (see page 12)Policy Server Prerequisite (see page 12)Java Components of the SiteMinder SDK (see page 13)Java Agent API (see page 13)Policy Management API (see page 14)Authentication API (see page 14)Authorization API (see page 15)Delegated Management Services API (see page 15)Utilities Package (see page 15)How Java Components Fit Together (see page 16)Network Architecture (see page 16)Java API Flow (see page 17)Log Trace Information (see page 23)Javadoc Reference (see page 24)Support for Custom Code (see page 24)Purpose of the Java APIsThe SiteMinder SDK provides Java APIs for performing the following tasks:■■■Creating SiteMinder AgentsCreating Policy Management applicationsCreating Delegated Management Services (DMS) applicationsInstallation PathThe Java APIs, documentation, and samples are installed to the followinglocation:■■UNIX platforms: /sdkWindows platforms: \sdk refers to the installation path where you installed the SDKsoftware.Chapter 1: Java API Overview 11

Code SamplesCode SamplesThe SiteMinder SDK includes tested samples of SiteMinder client applications.The source files for these samples are located as follows:■UNIX platforms:/sdk/samples/■Windows platforms:\sdk\samples\Notes on the Java samples:■■■■■The samples use properties defined in smjsdksample.properties, located in/sdk/properties. Before running the Java samples, modify this file withsettings for your environment.The smjsdksample.properties file also externalizes literal strings used forlogging.The samples smjavaagentapi and javadmsapi use the policy store createdby the sample javapolicyapi. Run smjavapolicyapi before runningsmjavaagentapi or javadmsapi.All the samples use the same logging options and output format.When executing the Java samples on a 64-bit UNIX platform, note thefollowing:■■Use a 64-bit JVM. Running the 64-bit samples using a 32-bit JVM is notsupported.If you are using the file java-run.sh (in the samples/smjavaagentapifolder) remove the comment indicator before the -d64 flag. Leave thisflag commented out when on a 32-bit platform.Policy Server PrerequisiteNo SiteMinder processes need to be running on the machine where you buildcustom applications using the Java APIs. Further, no SiteMinder software otherthan the SDK needs to be installed on the machine where you run customapplications built with the Java APIs.However, the Policy Server is required for running the applications. Theapplication runtime files can either be local or remote to the Policy Server.12 Developer's Guide for Java

Java Components of the SiteMinder SDKJava Components of the SiteMinder SDKThe Java components of the SiteMinder SDK are listed in the following table:API Name:Package NameJava Agent API:Primary Interfacesand ClassesAgentAPInetegrity.siteminder.javaagentPolicy Management API:com.netegrity.sdk.policyapiAuthentication and Authorization APIscom.netegrity.policyserver.smapiDelegated Management Services API:com.netegrity.sdk.dmsapiUtilities package:com.netegrity.sdk.apiutilSmPolicyApi, implemented bySmPolicyApiImplSmAuthScheme(Authentication API)ActiveExpression(Authorization API)SmDmsApi, implemented bySmDmsApiImplSmApiConnectionSmApiSessionJava Agent APIUse the Java Agent API to build a custom agent for enforcing access controland for managing user sessions. Enforcing access control consists of thefollowing checks on the user:■■■AuthenticationAuthorizationAuditingWhen using the Java Agent API, you code your agent in Java and let the AgentAPI perform the connection to the Policy Server.Chapter 1: Java API Overview 13

Policy Management APIThe SiteMinder Java Agent API has two implementations:■■The JNI Java Agent API, which relies on the native C/C++ Agent APIlibraries. It uses the interface presented in the SiteMinder SDK, versions5.x and later.The pure Java Agent API, which replaces the native code used in the JNIJava Agent API with pure Java components. The present version of thisAPI uses the same interface as the JNI Java Agent API.You can choose to use either implementation. Because there are no nativemodecomponents, the pure Java Agent API is highly portable to newplatforms. It requires certification only against the Java Virtual Machinehosting the implementation, rather than against individual operating systemsand hardware platforms.Important! To use the pure Java API, your Java JCE must be unlimitedstrength jurisdiction. You can download the files from Sun at the followingURL:http://java.sun.com/products/jce/javase.html#UnlimitedDownload.Policy Management APIUse the Policy Management API to manage:■■■■ResourcesPoliciesCachesSecurity rolesYou can manage policies by creating, deleting, associating, and modifyingpolicy objects such as policy domains, realms, and policies.Authentication APIUse the Authentication API to create a custom authentication scheme.The Authentication API allows you to create custom authentication schemes toprovide authentication services not offered by any of the standard SiteMinderauthentication schemes.14 Developer's Guide for Java

Authorization APIAuthorization APIUse the Authorization API to implement custom functionality for controllingaccess to protected resources. The functionality is provided through customJava classes that are referenced in Policy Server active expressions. An activeexpression is a string of variable definitions that appears in the following PolicyServer objects:■■■Active policyActive responseActive ruleDelegated Management Services APIUse the Delegated Management Services (DMS) API to perform tasks such as:■■■Manage directory entriesGrant privileges to users and to groupsGrant DMS roles to users and to groupsUtilities PackageUse the methods in the Utilities package to implement the APIs in the PolicyManagement API and the DMS API.Chapter 1: Java API Overview 15

How Java Components Fit TogetherHow Java Components Fit TogetherThe following figure shows how the Java components of the SiteMinder SDK fittogether:Client ApplicationClient requestsand responsesPolicyManagement APIDelegated ManagementServices APIAgent APISecure connection withload balancing and failoverAuthenticationAPIAuthorizationAPIPolicy ServerPolicy StoreUser NamespacesNetwork ArchitectureYou can use the Java APIs to write client applications that connect to a remoteSiteMinder Policy Server. These applications have access to the following builtinfunctionality of the Java Agent API:■■■SecurityLoad balancingFailover16 Developer's Guide for Java

Java API FlowThe network architecture of the Java APIs is shown in the following figure:The Policy Management API and the DMS API use the Java Agent API to accessthe Policy Server. A single API client instance makes a single, secure, AgentAPI connection to the SiteMinder Policy Server. As long as they share the sameprocess space, multiple API clients can re-use a single Agent API connection.For example, you can use the Java Agent API to establish a connection, thenuse that connection to make DMS API calls.Java API FlowWhen you are creating a client application with the Policy Management API orthe DMS API, take the following steps:1. Establish a Connection to the Policy Server2. Obtain a Session3. Make API Requests4. Handle Results and Exceptions.Establish a Connection to the Policy ServerTo establish a connection to the Policy Server, use the SmApiConnection classof the Utilities package. This class holds the Agent API handle through whichJava API requests are sent.Chapter 1: Java API Overview 17

Java API FlowThere are two types of connection handles in this class:■A default connection handle. A default connection handle:■■■Represents a single instance of an Agent API object.Is static across the process.Allows connections to the Agent API object from both PolicyManagement and DMS clients.You can establish multiple connections to the Policy Server through thesingle Agent API object instance.■A user-defined connection handle. You can create multiple user-definedconnection objects; each one can support multiple connections to thePolicy Server.Establish a Default ConnectionIf you have not already established a connection to the Policy Server, you canrequest an automatic connection. If SiteMinder establishes a connection foryou automatically, it creates a default Java Agent API object and handle.However, if a valid user-defined handle already exists, SiteMinder does notcreate a default object and handle. A user-defined handle takes precedenceover a default handle.To establish a default connection to the Policy Server automatically1. Use the following constructor to create an API connection object:SmApiConnection (boolean bDefaultAgentConnectionboolean disableLoadBalancing)2. In the constructor, set bDefaultAgentConnection to true—for example:SmApiConnection m_defaultConnection =new SmApiConnection(true,false);3. If bDefaultAgentConnection is false, you must explicitly establish theconnection in your client code.18 Developer's Guide for Java

Java API FlowAn automatic connection has the following requirements:■■■Your Web Agent be installed on the same machine where you are runningthe Agent API.The property DefaultAgentName in the Web Agent configuration objectcontains an agent name. You define the Web Agent configuration object inthe Policy Server.With Netscape and Apache Web Agents, the path to the Agentconfiguration file is in the CLASSPATH. With Microsoft IIS Web Agents, thisconfiguration information is in the Registry, so a CLASSPATH reference isnot necessary.Establish a User-Defined ConnectionYou establish a user-defined connection in one of two ways:■■By referencing an existing Java Agent API connection handle in theconstructor of the SmApiConnection object.By establishing a new connection manually through thesetAgentApiConnection() method.You may already have a connection to the Policy Server. For example, youmay have written a custom agent and established a connection using the JavaAgent API. To make subsequent Policy Management API or DMS API calls, youcan use the existing connection.To create a connection using an existing Agent API connection1. Create your connection object through the following constructor:SmApiConnection (netegrity.siteminder.javaagent.AgentAPIagentApiConnection)2. In the constructor, use agentApiConnection to pass in the handle of theexisting Agent API connection—for example:SmApiConnection myConnection =new SmApiConnection (myAgentApiConnection);The new Java Agent API handle is a user-defined handle.Chapter 1: Java API Overview 19

Java API FlowIf you do not already have a default connection but you want a user-definedconnection object, you can use the Agent API to create the agent object andthen create the new connection, as follows:1. Create the agent object.You can create an agent object based on connection parameters fromeither of the following sources:■User-defined connection parameters defined in your code—forexample:AgentAPI agent = new AgentAPI();ServerDef sd = new ServerDef();sd.serverIpAddress = POLICY_IP;sd.connectionMin = CX_MIN;sd.connectionMax = CX_MAX;sd.connectionStep = CX_STEP;sd.timeout = CX_TIMEOUT;sd.authorizationPort = AZ_PORT;sd.authenticationPort = AUTH_PORT;sd.accountingPort = ACC_PORT;InitDef init=new InitDef(AGENT_LOGIN,SHARED_SECRET,false, sd);agent.init(init);Note: With SiteMinder v6.0 and later, the authorization, authentication,and accounting servers are combined into a single server process.Consequently, authorizationPort, authenticationPort, and accountingPortcan all be set to the same value.■Connection parameters stored in an Agent configuration file(WebAgent.conf or LocalConfig.conf). For example, the following codeestablishes a connection on a Netscape server:AgentAPI agent = new AgentAPI();InitDef init = new InitDef();agent.getConfig(init, "myagent","/opt/netscape/server4/https-smdev/config/WebAgent.conf");agent.init(init);Note: An Agent configuration file for a v5QMRx or v6.x agent containsdifferent information than an Agent configuration file for a v4QMRx agent.20 Developer's Guide for Java

Java API Flow2. Create the new connection.After creating the agent object, you create the new connection in either ofthese ways:■Pass the agent object you just created into the constructor of the newSmApiConnection object—for example:SmApiConnection myConnection = new SmApiConnection(agent);■Call setAgentApiConnection() and pass in the agent object you justcreated—for example:SmApiConnection myConnection=new SmApiConnection(false,false);myConnection.setAgentApiConnection(agent);If you establish the connection in this way, the Java Agent API handle willbe a user-defined handle.If you call setAgentApiConnection() but you do not have a connection, youcan establish an automatic, static connection by passing in null.Obtain a SessionAfter obtaining a connection to the Policy Server, you need to obtain a user oradministrator session. (To use the Policy Management API, you must connectas a SiteMinder Administrator. The SiteMinder Policy Server validates a user’srights to perform an operation.)When you obtain a session object, you pass it to the Policy Management API orthe DMS API through the constructor for the SmPolicyApiImpl class or theSmDmsApiImpl class.To obtain a session, perform one of these actions:If... And... Then...You have an existingsession fromauthenticating a user.— Pass in the sessionspecification for theauthenticated user.You don’t have anexisting session.You don’t have anexisting session.You must connect as aSiteMinderAdministrator.You want to connect asa non-Administrator.Use the methodSmApiSession.login().Use the Java Agent API toobtain a sessionspecification for the user.Note: To use the Policy Management API, you must connect as a SiteMinderAdministrator.Chapter 1: Java API Overview 21

Java API FlowYou might already have a session specification for a user that has beenauthenticated. For example, you have written a custom agent and obtained asession specification using the Java Agent API. To make DMS API calls as auser, you can use that session specification. You need not obtain a newsession specification.To use an existing session, create an SmApiSession object and associate thesession specification with that object.Log in as a SiteMinder AdministratorTo authenticate a SiteMinder administrator, use the login() method in theSmApiSession class of the Utilities package. This method uses theadministrator’s login credentials (username and password) to authenticate theadministrator. Calling this login() method obtains a session specification andreturns an SmApiResult object.The syntax of the login() method is as follows:result=mySession.login (username,password,IPaddress,challengeReason);Provide a value for the challengeReason parameter as follows:■■On the administrator’s initial login, set challengeReason to 0 (no reason).If the initial login fails, use challengeReason in the next login() call tospecify the results of the previous authentication attempt.To retrieve the reason value to assign to challengeReason, callgetReason() in the SmApiResult object.To obtain a new session specification for a user, use the Java Agent API toobtain a session specification. Then, create an SmApiSession object andassociate the session specification with that object.22 Developer's Guide for Java

Log Trace InformationMake API Requests and Handle ResultsAfter establishing a session, you can call the methods in your clientapplication.A result is a response from the Policy Server to a Java API request. Results arereturned in an SmApiResult object.Exceptions are thrown from an unexpected client-side error. An exceptioncontains a result with additional information, such as the origin and severity ofthe result. To create a result object to store the results of API requests, usethe constructor of the SmApiResult class in the Utilities package—for example:SmApiResult result = new SmApiResult();You can check whether a request was successful by calling the methodisSuccess() on the result object. The method returns true if the request wassuccessful, or false if it was not successful.You can compare the current result object to a specified result object bycalling the equals() method.You can use the equals() method to compare the current result object withSmApiResult constants that represent different kinds of results. For example,in the following code, the result represented by the unique constantSERVER_INVALID_PASSWORD is compared against the current result object:InetAddress address = InetAddress.getLocalHost();SmApiResult result = apiSession.login(usr,pwd,address,0);boolean resultStatus =result.equals(SmApiResult.SERVER_INVALID_PASSWORD);Log Trace InformationTo log tracing information on the client side, use the -D option of the java tooland set the system property SMJAVASDK_LOG_INFO to true. SiteMinder logsthe information to the standard output.For example, if your Java Development Kit is on Windows and you want totrace the Policy Management API sample application, the command line wouldbe:java -DSMJAVASDK_LOG_INFO=true -classpath .;..\..\java\smjavasdk2.jar;..\..\java\smjavaagentapi.jar PolicyApiSampleChapter 1: Java API Overview 23

Javadoc ReferenceJavadoc ReferenceThroughout this Guide you can follow the links to the appropriate sections ofthe Javadoc reference to see details about a particular class or method. Thesedetails include syntax, parameters, return values, and exception information.Use the back arrow in the menu bar of the browser to return to topic whereyou left the Guide.The description of each package, class, and interface in the Javadoc referenceincludes a Since heading that indicates the SiteMinder or SDK version whenthe component was introduced. Individual methods and fields will only includea Since heading if they were added in a later version of the class or interface.Support for Custom CodeCA supports the Software Development Kit (SDK) as part of the standardofferings. Code written by customers or partners, however, is not supported.You are responsible for the code you write. If you require assistance designingor implementing SDK-based code, contact your CA customer account team.24 Developer's Guide for Java

Chapter 2: Utilities PackageThis section contains the following topics:Purpose of the Utilities Package (see page 25)Classes for Internal Use (see page 25)Connection Class (see page 26)Session Class (see page 26)Result Class (see page 27)Exception Class (see page 29)Property Class (see page 30)Purpose of the Utilities PackageIf you plan to call functions in the Policy Management API or the DMS API, youmust use the functions in the Utilities package to build your Java application.The SmApiConnection, SmApiResult, SmApiSession, SmApiException, andSmProperty classes in the Utilities package provide services such as:■■■■■Establishing a connection to the Policy ServerObtaining a sessionProviding a result object that stores results of API requestsHandling exceptions and resultsEncapsulating property dataClasses for Internal UseThe Utilities package provides these classes for SiteMinder internal use only:■■■■■■SmApiConstantsSmApiObjectSmApiPropertySetsSmApiExportFileHandlerSmApiImportFileHandlerSmFlagThese classes are used internally to define methods in the Policy ManagementAPI and the DMS API.Chapter 2: Utilities Package 25

Connection ClassConnection ClassYou use the SmApiConnection class to create an API connection object andestablish a connection between the Agent API and Policy Server. Dependingupon the constructor you use, you can establish either a default connection ora user-defined connection.The core methods of the SmApiConnection class are as follows:MethodgetAgentApiConnection()isValidApiConnection()setAgentApiConnection()DescriptionRetrieves the Agent API handle for thecurrent connection. Use this handle whenissuing subsequent Java API requests tothe Policy Server.Verifies whether a valid Agent APIconnection is available.Establishes a user-defined connectionthrough the handle passed into themethod. If null is passed, a staticconnection is established.Note: Do not call the execute() method from your client application. Thismethod is for internal use only.Session ClassThe Session class, SmApiSession, lets you create a session object by passingin a valid API connection and, depending upon the constructor you use, asession specification. (A session specification is also known as a sessionticket).The core methods of the SmApiSession class are as follows:MethodgetApiConnection()getSessionSpec()login()DescriptionRetrieves the SmApiConnection object forthe current connection.Retrieves the specification for the currentsession.Logs in a SiteMinder administrator. ThePolicy Server issues a session specificationfor the session.26 Developer's Guide for Java

Result ClassMethodlogout()setApiConnection()setSessionSpec()DescriptionLogs out a SiteMinder administrator.Sets a valid API connection.Sets an existing session specification.Note: For login and logout of end users, DMS organization administrators,and DMS super administrators, use the AgentAPI.login() and AgentAPI.logout()methods in the Agent API package.Result ClassThe Result class, SmApiResult, stores the result of a SiteMinder Java APIrequest. A SiteMinder result contains the following elements:■■■■Facility. Origin of the result. For example, the result might originate on theclient or server.Severity. Significance of the result, such as informational or warning.Status. Status code of the result. Status codes are unique within eachfacility. You can use a facility’s unique status code to distinguish aparticular result from other results that might have originated from thefacility.Message. Additional information about the result, such as descriptive textor numeric details.A result might also include a reason code. For example, a password policyresult might include a reason code of 1001, meaning that the password doesnot contain the required minimum number of characters. To find a reason codefor a result, call getReason().All server-side errors are returned as results, not as exceptions. However,when a client-side exception is thrown, an SmApiResult object is embedded inthe exception.Chapter 2: Utilities Package 27

Result ClassInterpret a Result ObjectEach result object and its Facility/Severity/Status combination are representedby a unique value. These unique values are associated with predefinedconstants defined in the SmApiResult class—for example,SERVER_CONFIGURATION_FAILURE.To determine the Facility/Severity/Status information for a result, you cancall the equals() method to compare the returned SmApiResult object with theresult constants.■■Facility: FACILITY_CONNECTIONSeverity: SEVERITY_ERROR■ Status: 4■Message: Unable to get server configurationYou can output a result object as a string—for example, you can generate aresult string by calling toString() on the SmApiResult object.A result string has five space-separated name/value pairs in the followingformat:[facility=facility severity=severity reason=reasonstatus=statusCode message=message]For example, suppose you call toString() for an SmApiResult object that occursbecause a user attempted to create a password with fewer than the minimumnumber of alphabetic characters. The method might return a result string thatlooks like this:[facility=4 severity=3 reason=1008 status=13 message=nArg=1,Arg1=3]The fields in the result have the following meanings:■■■facility=4. The result originated on the server.severity=3. The result is an error.reason=1008. The error occurred because the requested password hasfewer than the minimum number of alphabetic characters required forpasswords.28 Developer's Guide for Java

Exception Class■■status=13. The unique result status code for this facility.message=nArg=1,Arg1=3. An additional description of the result. The twoparts to this field have the following meanings:■■nArg1=1. The error contains just one error description.Arg1=3. The error description is 3. In the context of reason code1008, the Arg1 value means that a password is required to have aminimum of 3 alphabetic characters.Core Methods in the Result ClassThe core methods of the SmApiResult class include:Methodequals()getError()getFacility()getMessage()getReason()getSeverity()getStatus()isSuccess()toString()DescriptionIndicates whether the current object is equal to theobject passed to the method.Retrieves a unique error code.Retrieves the facility code associated with the error.Retrieves the message associated with the error.Retrieves the reason code of the error.Retrieves the severity code associated with the error.Retrieves the status code in the current facility. Thismethod can take as a parameter the result code fromthe server.Reports whether the request was successful.Returns a string representation of the SmApiResultobject.Exception ClassThe Exception class, SmApiException, contains the result class SmApiResult.The following packages use SmApiException:■■■com.netegrity.sdk.policyapicom.netegrity.sdk.dmsapicom.netegrity.sdk.apiutilChapter 2: Utilities Package 29

Property ClassThe core methods of the SmApiException class include:MethodgetFacility()getReason()getSeverity()getStatus()toString()DescriptionRetrieves the facility code of the exception.Retrieves the reason code of the exception.Retrieves the severity code of the exception.Retrieves the status code of the exception.Returns a string representation of the SmApiResultobject.The Exception class extends java.lang.Exception. By calling the inheritedgetMessage() method, you can retrieve the message associated with theexception.Property ClassThe Property class, SmProperty, holds the following information about aproperty:■■■NameValueType (encrypted / plain)The core methods of the SmProperty class include:MethodgetName()getType()getValue()setName()setType()setValue()DescriptionRetrieves the name of the property.Retrieves the type of the property (that is, 0 if plaintext, 1 if encrypted).Retrieves the value of the property.Sets the name of the property.Sets the type of the property, 0 if plain text & 1 ifencrypted.Sets the value of the property.30 Developer's Guide for Java

Chapter 3: Agent APIThis section contains the following topics:SiteMinder Agents (see page 31)Agent API Class Hierarchy (see page 32)Implement the JNI Java Agent API (see page 33)Implement the Pure Java Agent API (see page 34)Connection to a Policy Server (see page 36)User Access to Resources (see page 37)How Web Agents Use the Agent API (see page 39)Java Agent API Services (see page 40)Session Services (see page 40)Authorization Services (see page 42)Auditing Services and Transaction Tracking (see page 42)Management Services (see page 43)Tunnel Services (see page 44)Response Attributes (see page 44)Single Sign-on (see page 45)Server Clusters (see page 48)Timeouts (see page 51)Agent Type (see page 52)SiteMinder AgentsA SiteMinder Agent is a client of the Agent API. The agent enforces accesscontrol policies served by the Policy Server. The Policy Server is a generalpurposepolicy engine with no specific knowledge of resources. The specificknowledge of resources is provided by SiteMinder agents. Agents establishresource semantics and act as gate keepers to protect resources fromunauthorized users.Different agent types protect different kinds of resources. Some agent typesare pre-defined, standard agents that are shipped as part of the SiteMinderproduct—for example, the Web Agent, which provides HTTP access control forWeb Servers. However, you can also use the Agent API to implement customagents.Chapter 3: Agent API 31

Agent API Class HierarchyThe Agent API lets you create a custom agent that can authenticate andauthorize users in a variety of context-specific ways. For example, you couldcreate an agent for FTP transfers that does the following:■■Implements certificate-based authentication instead of basic name andpassword credentials.Allows uploads and downloads based on an individual user’s authorizationlevel.Custom agents can participate in a single sign-on environment with standardSiteMinder Web Agents.Agent API Class HierarchyThe primary point of access to the Java Agent API is the AgentAPI class.Several other classes are provided to hold data required by the AgentAPIclass:■■■■■■■■■■■■AttributeAttributeListBinaryBufferInitDefManagementContextDefRealmDefResourceContextDefServerDefSessionDefTokenDescriptorTunnelServiceRequestUserCredentials32 Developer's Guide for Java

Implement the JNI Java Agent APIImplement the JNI Java Agent APIApplications that are built using the JNI Java AgentAPI either directly orindirectly (through another agent) are insulated from underlyingimplementation details, including:■■■User namespaces, such as LDAP directories, SQL databases, or NTdomainsAuthentication methods as simple as username/password or as complex asPKI systemsAuthorizations based on group membership or individual profile dataAdditional benefits provided by the Java Agent API include full sessionmanagement support, automatic encryption key rollover, and real-time policyupdates.To implement the JNI Java Agent API1. Review the required software as listed in the accompanying release notes.2. Review the sample code.3. Write source code for your client application.4. Ensure that your system can find the JNI support library when the JavaVirtual Machine (JVM) is invoked, as follows:■On Windows: Change PATH to include the following, so thatsmjavaagentapi.dll can be found:\sdk\bin■On Solaris: Change LD_LIBRARY_PATH to include the following, so thatlibsmjavaagentapi.so can be found:/sdk/bin■On AIX: Change LIBPATH to include the following, so thatlibsmjavaagentapi.so can be found:/sdk/bin■On Linux: Change LD_LIBRARY_PATH to include the following, so thatlibsmjavaagentapi.so can be found:/sdk/binNote: Java agents on Linux require Java SDK v 1.3.1.■On HP-UX 11: Change SHLIB_PATH to include the following, so thatlibsmjavaagentapi.sl can be found:/sdk/binNote: The Java Agent API is not available for HP10.Chapter 3: Agent API 33

Implement the Pure Java Agent API5. Ensure that SiteMinder can find the JNI Java AgentAPI JAR file when youcompile or run an agent that uses the Java Agent API. The JAR file,smjavaagentapi.jar, is stored in the following locations:■Windows platforms:\sdk\java■UNIX platforms:/sdk/javaAdd smjavaagentapi.jar to your CLASSPATH setting. When compiling, youcan use the -classpath switch.6. Compile the Java Agent API application using javac.For an example, see java-build.bat or java-build.sh in the sample directorysmjavaagentapi.7. Configure the Policy Server to use the Java Agent API application.8. Run the application.For an example, see java-run.bat or java-run.sh in the sample directorysmjavaagentapi.Implement the Pure Java Agent APIApplications that are built using the pure Java Agent API either directly orindirectly (through another agent) are insulated from underlyingimplementation details, including:■■■User namespaces, such as LDAP directories, SQL databases, or NTdomainsAuthentication methods as simple as username/password or as complex asPKI systemsAuthorizations based on group membership or individual profile dataAdditional benefits provided by the Java Agent API include full sessionmanagement support, automatic encryption key rollover, and real-time policyupdates.To implement the pure Java Agent API1. Review the required software as listed in the accompanying release notes.2. Review the sample code.3. Write source code for your client application.34 Developer's Guide for Java

Implement the Pure Java Agent API4. Ensure that SiteMinder can find the pure Java Agent API .jar file when youcompile or run an agent that uses the Java Agent API. The JAR file,smagentapi.jar, is stored in the following locations:■Windows platforms:\sdk\java■UNIX platforms:/sdk/javaAdd smagentapi.jar to your CLASSPATH setting. When compiling, you canuse the -classpath switch.5. Compile the Java Agent API application using javac.For an example, see java-build.bat or java-build.sh in the sample directorysmjavaagentapi.6. Configure the Policy Server to use the Java Agent API application.7. Run the application.Backward compatibilityThe pure Java Agent API maintains binary and source compatibility with theJNI Java Agent API. The pure Java Agent API supports all of the otherSiteMinder Java SDK interfaces that rely on the Agent API for connectivity tothe SiteMinder Policy Server, including the SiteMinder Policy Management APIand the SiteMinder DMS API, in addition to extending the portability of thoseinterfaces.Configuration limitationsThe pure Java Agent API does not change the configuration of either theSiteMinder Application Server Agents or any agents developed with theSiteMinder SDK. The configuration of the pure Java Agent API is identical tothe configuration of the JNI Java Agent API with the following exceptions:■■Migration of UNIX agents from the JNI Java Agent API to the pure JavaAgent API requires re-registration of the trusted host entity with theSiteMinder Policy Server because the shared secret in the JNI Java API iscomputed differently from the pure Java implementation.On both Unix and Windows systems (due to file-locking incompatibilitieswith the native code Agent API), the SmHost.conf file cannot be sharedbetween agents using the C/C++ or JNI Java Agent API and agents usingthe pure Java Agent API. Therefore, a separate copy of the bootstrapconfiguration file must be kept for pure Java Agent API agents.Chapter 3: Agent API 35

Connection to a Policy Server■■Upgrades from the JNI Java Agent API on Unix systems requires users ofcustom 4.x-based agents that use shared secrets encrypted with the 4.xencryptkey tool to update their shared secret on the agent side forupgraded agents.The pure Java Agent API does not obtain Agent configuration informationfrom the Windows Registry.Connection to a Policy ServerBefore an agent can perform work on behalf of its users, it must initializeconnections to one or more Policy Servers by issuing the init() method.Through the InitDef parameter, you can specify connection parameters suchas failover mode and connection pool size. This step creates TCP connectionsand typically does not need to be done more than once per agent instance.After the Agent API is initialized, all API calls are fully thread-safe with respectto the initialized API instance.It is possible to initialize more than one API instance (for example, whenworking with Policy Servers that use separate policy stores).Immediately after initialization, the agent should communicate its versioninformation to the Policy Server by calling doManagement() with the constantMANAGEMENT_SET_AGENT_INFO set in the ManagementContextDef object.The actual information can be any string containing enough information aboutthe agent, such as the build number, and the version number. The string isrecorded in the Policy Server logs.After the Agent API has been initialized, the agent can perform useful work. Atthis point it can start accepting requests from its users, such as receiving GETrequests for URLs.36 Developer's Guide for Java

User Access to ResourcesUser Access to ResourcesThe agent must perform the following steps before granting a user access to arequested resource. The outcome of most steps can be cached to improveagent performance. The agent can choose to cache as little or as much aspossible.1. Accept a user request.Accept a user request to access a resource. This is the application-specificrequest. For example, the Web Agent would accept a user’s GET requestfor a URL.2. Check if the resource is protected.Call isProtected() to determine if the requested resource is protected.If the resource is protected, the policy server returns the requiredcredentials that must be obtained from the user in order to validate theuser’s identity. If the resource is not protected, access to the requestedresource should be allowed.The outcome of this step can be cached.3. Authenticate the user.Call login() to collect the required credentials from the user and toauthenticate the user.Upon successful authentication, the Policy Server creates a session andreturns response attributes, including the unique session id and sessionspecification. These response attributes are policy-driven and may includeuser profile data, static or dynamic privileges, a number of predefinedauthentication state attributes, or any other data that was designated by apolicy administrator.The agent can now perform session management by caching user sessioninformation and keeping track of session expiration.4. Check if the user is authorized.Call authorize() to validate that the user has access to the requestedresource.Upon successful authorization, the policy server returns responseattributes including resource-specific privileges. These response attributesare policy driven and may include user profile data, static or dynamicprivileges, or any other data that was designated by a policyadministrator.At this point the user’s authorization information with respect to therequested resource is known and can be cached to speed up futurerequests.Chapter 3: Agent API 37

User Access to Resources5. Audit cached authorization information.Both the authentication and authorization steps log the relevantinformation about the user, the protected resource, and the agent.However, if the agent performs authorizations out of its cache, thetransaction can still be logged through the audit() method.6. Allow access to resource.Now that the user’s identity is known, authorization has been verified, andthe required entitlements obtained, give the authorized user access tothe resource.7. Issue a management request.This is an optional step that is used to poll the Policy Server for updatecommands. In response to a command, agents update encryption keys orflush caches or both.When the agent is no longer needed, issue the unInit() method for each APIinstance. This closes TCP connections to all policy servers.Note: The Agent API does not provide a facility for caching in a manner thatenforces session validity. By choosing to cache user sessions and/or resourcespecificprivileges, the agent becomes obligated to perform its own sessionmanagement during each user request. This is required, since caching on theagent removes the need to contact the SiteMinder Policy Server to performsession validation and/or resource authorizations.38 Developer's Guide for Java

How Web Agents Use the Agent APIHow Web Agents Use the Agent APIThe following figure shows the process flow that occurs when a Web Agentuses the Agent API:Chapter 3: Agent API 39

Java Agent API ServicesJava Agent API ServicesThe Java Agent API provides a rich set of services that let you developsophisticated, secure, and robust agents. Building an agent involves usingthese services:■■■■■Session ServicesAuthorization ServicesAuditing Services and Transaction TrackingManagement Services (key encryption, cache updates)Tunnel ServicesThese services are accessed through the AgentAPI class.Session ServicesSessioning is used to maintain consistent user sessions across multi-tieredapplication environments.AgentAPI methods that implement session services are:■■login()logout()Agents that perform session management use the sessioning services of theJava Agent API to create, delegate, validate, and terminate user sessions.Note: For login and logout of SiteMinder administrators for Policy Server orDMS sessions, use the methods SmApiSession.login() andSmApiSession.logout() in the Utility package.Session Creation and the Session SpecificationA session is created after a successful user login. Once created, a user sessionpersists until it is terminated.When a user is authenticated, the Policy Server issues a session specification.A session specification contains information about the user.User-side session persistence in a multi-tiered application environment isaccomplished by saving and maintaining the user information in the sessionspecification. This session specification represents a user session. It is the keyto SiteMinder session management.40 Developer's Guide for Java

Session ServicesThe SiteMinder environment where the user session was created is responsiblefor the creation, maintenance, and persistent storage of the sessionspecification. For example, the Web Agent (HTTP environment) stores thesession specification in an HTTP cookie.Agents create sessions using login(). This method authenticates the usercredentials and gets the information for session specification (including theunique session id). Once created, the session specification is updated onsubsequent Java Agent API calls that also return updated expiration times.Agents can use this information to perform custom session management andkeep track of session timeouts.If your Web server’s user-tracking feature is enabled, the SiteMinder PolicyServer issues an identity ticket in addition to the session specification. Identitytickets can be used for identity-based personalization when a user is accessinga resource protected by anonymous authentication schemes. Identity ticketsnever expire.Another important feature that is seamlessly integrated with the sessioningmechanism is the SiteMinder universal ID. A universal ID identifies the user toan application in a SiteMinder environment through a unique identifier, such asa social security number or customer account number. The universal IDfacilitates identification of users between old and new applications bydelivering the user’s identification automatically, regardless of the application.Once configured on the Policy Server, a user’s universal id becomes part of thesession specification and is made available to agents for the duration of theentire session.Session ValidationAgents request validation of a session specification to make sure that a usersession has neither expired nor been terminated or revoked. This can occur atany time during the session’s lifetime. Agents call AgentAPI.login() to validatea session specification.Session DelegationWhen an application’s logic flow crosses application tiers, sessions may bedelegated by passing the session specification between two agents. Each agentcan choose to have the session specification validated.Chapter 3: Agent API 41

Authorization ServicesSession TerminationA session is terminated in any of the following ways:■■■■After a user logs outs and the agent discards the session specificationWhen the session expiresWhen the session is revokedWhen the user account is disabledTo terminate a session, the agent must discard the session specification. Oncea session is terminated, the user must log in again to establish a new session.Authorization ServicesAgents that perform access control functions use the authorization services ofthe AgentAPI class. These services enable clients to verify a user’s rights toaccess a resource, retrieve a user’s privileges with respect to specificresources, and determine the specific access control, if any, that is imposedupon a resource.You can determine whether a resource is protected by calling the isProtected()method. This method accepts as a parameter the resource that is served bythe requesting agent and returns information about the user’s credentials.Once the user’s identity is validated, the agent calls the authorize() method todetermine if the requesting user has access to the requested resource. Agentscan perform fine-grained access control by leveraging the collection ofresponse attributes that this method retrieves.Auditing Services and Transaction TrackingAgents can keep track of and log all user activity during a session. Althoughmuch of a user’s activity is logged by the Policy Server, there are times whenit may be necessary to log authorizations done out of agent cache. Agents callthe audit() method to log such requests for resources.By generating a unique transaction id, agents can correlate access controlactivity with application activity. The transaction id can be given to both theauthorization and auditing methods so that the Policy Server would record thetransaction-specific id associated with the application activity. This can be usedfor non-repudiation.42 Developer's Guide for Java

Management ServicesManagement ServicesA management protocol exists between agents and the SiteMinder PolicyServer. This protocol helps an agent manage its caches and encryption keys ina manner consistent with both SiteMinder policies and administrative changeson the Policy Server.To request the latest agent commands, an agent calls the methoddoManagement() with MANAGEMENT_GET_AGENT_COMMANDS set in theManagementContextDef object. Typically, this call is made every n seconds bya thread running in the background. The types of agent commands that can beretrieved are cache commands and encryption commands.Cache CommandsCache commands inform the agent of any changes to its caches that may needto be made as a result of administrative updates to the Policy Server.The cache commands are:■■■■■CACHE_FLUSH_ALLCACHE_FLUSH_ALL_USERSCACHE_FLUSH_THIS_USERCACHE_FLUSH_ALL_REALMSCACHE_FLUSH_THIS_REALMEncryption CommandsEncryption commands inform the agent of new encryption keys that aregenerated administratively or automatically by the Policy Server. Agents savesecure state can use this protocol to keep track of the latest encryption keys.The encryption commands are:■■■■■AFFILIATE_KEY_UPDATEAGENT_KEY_UPDATE_NEXTAGENT_KEY_UPDATE_LASTAGENT_KEY_UPDATE_CURRENTAGENT_KEY_UPDATE_PERSISTENTChapter 3: Agent API 43

Tunnel ServicesTunnel ServicesTunnel services enable agents to establish secure communications with acallable service located on the Policy Server. This allows agents to performcustom actions over a secure, VPN-like channel without having to addressissues such as encryption key management.Response AttributesResponse attributes enable the Policy Server to deliver information to agents.Response attributes are managed through methods in the AgentAPI class.There are two types of response attributes:■■Well-knownPolicy-basedThe well-known attributes are always returned by the Policy Server aftercertain calls such as login(). These attributes represent static, fixed data suchas the user DN and Universal ID.The policy-based attributes are returned by the login() and authorize()methods. These attributes are based on policies and are the vehicle fordelivering static and dynamic data from the Policy Server to agents, which candistinguish between authentication and authorization attributes. The actualsource of the data is defined on the Policy Server using the responses featurethat can be configured to deliver data from a variety of sources. Data mayinclude static information, information from a directory profile, or a customPolicy Server plug-in. Once the responses are properly configured, agents arecapable of performing fine-grained access control as well as profile-drivenpersonalization.Based on a policy definition, response attributes can time out or be cached forthe duration of the user session. The Policy Server delivers an attribute alongwith the TTL (Time-To-Live) value, calculated in seconds. If the agent iscaching user sessions and/or authorizations, it is responsible for keeping therelevant attributes up to date. Agents issue the updateAttributes() method toupdate stale attributes.44 Developer's Guide for Java

Single Sign-onSingle Sign-onIn a single sign-on environment, a user who successfully authenticatesthrough a given agent does not have to re-authenticate when accessing arealm protected by a different agent. When a custom agent is involved in asingle sign-on environment, the two agents must be in the same cookiedomain—for example, xxx.domainname.com.Single sign-on is made possible through a single sign-on cookie namedSMSESSION. This cookie is created and written to the user’s browser either bySiteMinder or by the custom agent.Class AgentAPI contains two methods that allow custom agents to participatein a single sign-on environment with standard SiteMinder Web Agents:decodeSSOToken()The custom agent extracts the cookie’s contents, called a token, from anexisting SMSESSION cookie and passes the token to this method. Themethod decrypts the token and extracts the specified information. Thismethod can also be used to update the last-access timestamp in thetoken.createSSOToken()After the user successfully logs in through the custom agent, the customagent passes information about the user to this method. The methodcreates an encrypted token from this user information and from sessioninformation returned from the login call. The custom agent writes thetoken to the SMSESSION cookie.See the sample custom agent code for an example of setting up theparameters for the single sign-on methods and parsing the results. Thesample custom agent code is located in the smjavaagentapi directory of\sdk\samples.Log on through a Custom AgentHere is the typical sequence of events in a single sign-on environment whenthe initial login is through the custom agent:1. User logs in through the custom agent.2. Custom agent calls login() to authenticate the user. The user is challengedfor credentials.3. Custom agent calls createSSOToken() and passes to it information aboutthe user (user name, user DN, IP address of the requesting client).SiteMinder adds this information to a token along with session informationreturned from the login call. SiteMinder also encrypts the information inthe token.Chapter 3: Agent API 45

Single Sign-on4. Custom agent creates the SMSESSION cookie in the user’s browser andwrites the token to the cookie.5. User requests a resource protected by a standard SiteMinder agent.6. The standard agent performs a login operation, which validates the userbased on the information in the single sign-on cookie. The user is notchallenged for credentials.Log on through a Standard AgentHere is the typical sequence of events that occurs in a single sign-onenvironment when the initial login is performed through the standardSiteMinder Web Agent:1. User logs in through the standard agent.2. Standard agent authenticates the user by challenging the user forcredentials through the login call.3. SiteMinder creates the SMSESSION cookie in the user’s browser andinserts the encrypted token containing session information.4. User requests a resource protected by a custom agent.5. The custom agent obtains the SMSESSION cookie from the user’s requestand extracts the token.6. The custom agent passes the token to the method decodeSSOToken().The method decodes the token and returns a subset of the token’sattributes to the custom agent.7. The custom agent obtains the session specification from the token andpasses the session specification to login(). The login call validates the userwithout challenging the user for credentials.8. User requests a resource protected by a standard SiteMinder agent.9. The standard agent performs a login operation, which validates the userbased on the contents of the SMSESSION cookie. The user is notchallenged for credentials.46 Developer's Guide for Java

Single Sign-onStandard Agent SupportCustom agents created with the SiteMinder SDK v6.x can accept SMSESSIONcookies created by a standard SiteMinder v4.x, v5.x, or v6.x Web Agent.However, standard SiteMinder v4.x or v5.x Web Agents can only acceptcookies created by a custom agent if the standard agent has been upgradedwith the appropriate Siteminder Agent Quarterly Maintenance Release (QMR).For information about the QMR version required for each standard agentversion, see the accompanying SDK release notes.To enable a SiteMinder v4.x or v5.x agent with the appropriate QMR upgradeto accept SMSESSION cookies created by a custom agent, the standardagent’s Agent configuration file (LocalConfig.conf with IIS servers orWebAgent.conf with other servers) or central configuration object (for v5.x orhigher) must contain the following entry:AcceptTPCookie="yes"Set AcceptTPCookie as follows:■■With 4.xQMR4 agents and above, add AcceptTPCookie="yes" directly inthe standard agent’s Agent configuration file.With 5.xQMR1 agents and above, add the entry to the standard agent’sAgent Configuration Object if the AllowLocalConfig parameter for thatobject is set to no. If AllowLocalConfig is set to yes, you can setAcceptTPCookie in the standard agent’s Agent configuration file.How Information Is Bound to a SessionSession information can consist of more than the session specification. Sessioninformation can include any information that the client application wants toassociate with the user’s session.Application-defined session information consists of name/value pairs calledsession variables. For example, business logic, certificate information, andSAML assertions for affiliate operations can all be stored as session variablesand bound to the session ID.The class AgentAPI provides the following methods for setting, retrieving, anddeleting session variables:■■■setSessionVariables()getSessionVariables()delSessionVariables()Session variables are stored in a server-side database called the session store.The session store is managed by the Policy Server.Chapter 3: Agent API 47

Server ClustersAdvantages of Session VariablesWhen a client application uses session variables:■■Up to 4K of data can be stored for each session variable value.The session information persists across multiple Policy Servers.Centralizing session information on the server allows features such ascross-domain session management, including enforcing logout and idletimeout across different domains.Requirements for Using Session VariablesFor a client application to use session variables, both of the followingprerequisites must be met:■■The Session Server must be enabled in the Policy Server ManagementConsole.During realm configuration in the Policy Server UI, Persistent Sessionmust be selected for at least one of the realms to be accessed during thesession. As soon as the user accesses a realm configured for persistentsessions, session variables can be used throughout the remainder of thesession.End of Session CleanupWhen the user logs out and the agent discards the session specification, thesession ends. In the case of a persistent session, SiteMinder removes allsession information, including any session variables, from the session store.Server ClustersTo help prevent service interruptions, SiteMinder includes a failover feature. Ifthe primary Policy Server fails and failover is enabled, a backup Policy Servertakes over policy operations. Beginning with SiteMinder v6.0, failover canoccur not only between Policy Servers, but between groups, or clusters, ofPolicy Servers.The cluster functionality also improves server performance by providingdynamic load balancing between the servers in a cluster. With dynamic loadbalancing, policy operations are automatically distributed between theavailable servers in a cluster according to the performance capabilities of eachserver.48 Developer's Guide for Java

Server ClustersClustered and Non-Clustered ServersAn agent running against Agent API v6.x can be associated with one or morePolicy Servers, or with one or more clusters of Policy Servers, as follows:■Clustered serversIn the ServerDef object for each clustered server, set clusterSeq() to thesequence number for the cluster. All servers in a cluster have the samecluster sequence number.Behavior: Failover occurs between clusters of servers if multiple clustersare defined. Also, requests to servers within a cluster are sent according tothe improved performance-based load-balancing techniques introducedwith Agent API v6.0.■Non-clustered serversIn the ServerDef object for each non-clustered server, set the methodclusterSeq() to 0.Behavior: Behavior is the same as in v5.x installations—that is, you canenable failover among the servers associated with the agent, or you canenable round-robin behavior among the servers.When round-robin behavior is enabled, the improved performance-basedload-balancing techniques introduced with Agent API v6.0 are used.Note: The same agent cannot be associated with both clustered and nonclusteredservers.Cluster ConfigurationYou can configure a cluster through the Agent API or through a hostconfiguration object using the Policy Server User Interface. If you configure acluster through the Agent API, be sure that the configuration does not conflictwith any cluster configuration information that may be defined in the hostconfiguration object.You configure the individual servers or clusters of servers that the agent isassociated with through the InitDef and ServerDef classes.Chapter 3: Agent API 49

Server ClustersCluster failover occurs according to the following configuration settings:■Failover threshold. The minimum percentage of servers within a clusterthat must be available for Policy Server requests. If the number ofavailable servers falls below the threshold, failover to the next clusteroccurs.The failover threshold percentage applies to all clusters associated with theagent.To determine the number of servers that the percentage represents in anygiven cluster, multiply the threshold percentage by the number of serversin the cluster, rounding to the nearest integer. For example, with a 60-percent failover threshold for a cluster of five servers, failover to the nextcluster occurs when the number of available servers in the currently activecluster falls below 3.Set through: InitDef constructor that contains the failOverThresholdparameter.■Sequence of cluster failover. Each cluster is assigned a sequencenumber. When cluster failover occurs, SiteMinder sends subsequent PolicyServer requests to the next cluster in the cluster sequence.Set through: ServerDef.clusterSeq().Cluster FailoverIf your site uses clusters, you typically will have a primary cluster and one ormore backup clusters.The primary cluster is the cluster to which SiteMinder sends requests as longas the number of available servers in the cluster does not fall below thefailover threshold. If there are not enough available servers in the primarycluster, failover to the next cluster in the cluster sequence occurs. If thatcluster also fails, failover to the third cluster occurs, and so on.When All Clusters FailIf the number of available servers falls below the failover threshold in allclusters associated with the agent, policy operations do not stop. Requests aresent to the first cluster in the cluster sequence that has at least one availableserver.For example, suppose an agent is associated with two clusters—C1 containingthree servers, and C2 containing five servers.The failover threshold for anycluster associated with the agent is set at 60 percent.50 Developer's Guide for Java

TimeoutsThe following table shows the minimum number of servers that must beavailable within each cluster:ClusterServers inClusterPercentageFailoverThresholdNumericFailoverThreshold(MinimumAvailable Servers)C1 3 60 1C2 5 60 3Version Compatibility and Failover BehaviorIf the number of available servers falls below the threshold in each cluster, sothat C1 has no available servers and C2 has just two, the next incomingrequest will be dispatched to a C2 server with the best response time. After atleast two of the three C1 servers are repaired, subsequent requests are loadbalancedamong the available C1 servers.Agent API v6 is backwards-compatible with Agent API v5, allowing completeinteroperability between v5/v6 agents and the v5/v6 Agent APIs.TimeoutsAgents can enforce session timeouts or rely on the Policy Server to validateeach request. Typically, caching of user sessions or privileges by the agentrequires some form of timeout enforcement on the agent side. In this case,the agent is responsible for keeping track of last access time and knowingwhen the session is going to expire.Agents that do not cache can leverage the Policy Server’s enforcement oftimeouts. The following Java Agent API methods return the updated timeoutinformation after every call:■■■login()authorize()audit()Chapter 3: Agent API 51

Agent TypeAgent TypeThe Agent Type defines the behavior of an agent. After you have developed acustom agent, you must configure a new Agent Type for the agent in thePolicy Server User Interface. For example, if you developed a custom FTPAgent, you would then need to configure an Agent Type for the FTP Agent inthe Policy Server User Interface.Note: For information on configuring an Agent Type for your custom agent,see the SiteMinder Programming Guide for C.52 Developer's Guide for Java

Chapter 4: Policy Management APIThis section contains the following topics:About Policy Management (see page 54)Policy Management Setup (see page 55)Required JAR File (see page 55)Policy Store Objects (see page 55)Write a Policy Management Application (see page 57)Administrator Methods (see page 59)Agent Methods (see page 59)Agent Configuration Object Methods (see page 60)Authentication and Authorization Map Methods (see page 60)Authentication Scheme Methods (see page 61)Certificate Map Methods (see page 61)Domain Methods (see page 61)General Object Methods (see page 62)Group Methods (see page 63)Host Configuration Object Methods (see page 63)ODBC Query Scheme Methods (see page 64)Password Policy Methods (see page 64)Policy Methods (see page 65)Policy Migration Methods (see page 65)Realm Methods (see page 66)Response Methods (see page 66)Root Configuration Methods (see page 67)Rule Methods (see page 67)Self-Registration Methods (see page 68)Trusted Host Object Methods (see page 68)User Directory Methods (see page 68)User Policy Methods (see page 69)Utility Methods (see page 70)Object Associations (see page 70)Add Objects to the Policy Store (see page 71)Retrieve Objects from the Policy Store (see page 72)Delete Objects from the Policy Store (see page 72)Authentication Scheme Configuration (see page 72)Performance Consideration (see page 111)Chapter 4: Policy Management API 53

About Policy ManagementAbout Policy ManagementPolicy management consists of creating, deleting, and modifying policy objectswithin a SiteMinder policy store. Through the Policy Management API, you canperform most of the data manipulations that you can perform through thenative Policy Server User Interface. For example, you can write a clientapplication that allows administrators to perform tasks such as:■■■■■■■■■■■■■■■■■Creating a policy domainCreating an Agent objectCreating an Agent configuration objectCreating a host configuration objectRegistering a trusted hostCreating a SiteMinder user directory objectCreating an authentication scheme objectCreating an administratorCreating a realmAdding a realm to a policy domainCreating a ruleCreating a responseCreating a policyAdding a user or group to a policyAdding a rule to a policySetting responses for rules in a policyMigrating an entire policy store or an individual policy domain remotely54 Developer's Guide for Java

Policy Management SetupPolicy Management SetupTo run applications built with the Policy Management API:■■Use the Policy Server Management Console to configure the Policy Serverso that it points to the policy store you want to access.Run your Policy Management application on the same machine as thePolicy Server or on a machine that has network access to the PolicyServer.Note: If an application built with the Policy Management API runs on thesame machine as the Policy Server, the application must run as the same userwho installed the Policy Server (for example, smuser on UNIX platforms).Required JAR FileThe JAR file smjavasdk2.jar is required for building and running PolicyManagement applications. The JAR file is stored in the following locations:■Windows platforms:\sdk\java■UNIX platforms:/sdk/javaPolicy Store ObjectsInterface SmPolicyApi is implemented by the class SmPolicyApiImpl. Use thisclass as the starting point for the Policy Management API. Each policy storeobject is associated with a class in the Policy Management API. You create andmanage policy store objects through the methods in an object’s class.Policy store objects can be classified according to scope:■■Domain objects are visible only within the domain. They cannot be sharedbetween domains.Global objects are visible across all domains.Global objects are sometimes called system objects.Global objects include:■■■AdministratorsAgent typesAgents and agent groupsChapter 4: Policy Management API 55

Policy Store Objects■■■■■■■■■■■Agent Configuration objectsHost Configuration objectsTrusted HostsAuthentication schemesAuthentication/authorization mapsCertificate mapsDomainsODBC query schemesPassword policiesRegistration schemesUser directoriesDomain objects include:■■■■■■PoliciesRealmsResponses and response groupsResponse attributesRules and rule groupsUser policiesWhen you are working in the Policy Server user interface, you will see most ofthe above objects listed in the System and Domain tabs of the SiteMinderAdministration window.Note: Descriptions in the Javadoc reference specify whether an object hasglobal scope or domain scope.56 Developer's Guide for Java

Write a Policy Management ApplicationWrite a Policy Management ApplicationTo write a Policy Management application1. Establish a Connection to the Policy Server2. Obtain a Session Object3. Pass in the Session Object4. Make Policy Management API Requests5. Terminate the Administrator SessionThe SiteMinder SDK contains a sample of how to use the classes and methodsin the Java Policy Management API.Establish a Connection to the Policy ServerTo establish a connection to the Policy Server, use the SmApiConnection classof the Utilities package. This class holds the Agent API handle through whichJava API requests are sent.There are two types of connection handles in this class:■A default connection handle. A default connection handle:■■■Represents a single instance of an Agent API object.Is static across the process.Allows connections to the Agent API object from both PolicyManagement and DMS clients.You can establish multiple connections to the Policy Server through thesingle Agent API object instance.■A user-defined connection handle. You can create multiple user-definedconnection objects; each one can support multiple connections to thePolicy Server.Chapter 4: Policy Management API 57

Write a Policy Management ApplicationObtain a Session ObjectA session object is obtained when a user or administrator successfully logs in.In this case, an administrator login is required, since only administrators canperform policy management.To log in a SiteMinder administrator and establish an administrator session,call the login() method in the SmApiSession class of the Utilities package.Once login is successful, the session object will hold a valid administratorsession specification.Pass in the Session ObjectAfter obtaining a valid session, create a Policy Management API object bypassing the session to the constructor of the SmPolicyApiImpl class—for example:SmPolicyApi policyApi = new SmPolicyApiImpl (apiSession);In the example, policyApi is the new Policy Management API object andapiSession is the session obtained when the administrator successfully loggedin.Make Policy Management API RequestsAfter you obtain a session object and create a Policy Management API object,you are ready to make Policy Management requests. Most of the methods inthe Policy Management API are categorized according to the SiteMinder objectthat a given method acts upon—for example, agents, policies, and rules.There is also a Utilities category for methods that perform services, such ascache and encryption key management. Use these categories to help you finda particular Policy Management API method to use in your custom policymanagement applications.Note: The methods in the policyapi package can only be called from aSiteminder administrator session.Terminate the Administrator SessionWhen you are finished making Policy Management API requests, log out theadministrator by calling the logout() method in the SmApiSession class of theUtilities package.58 Developer's Guide for Java

Administrator MethodsAdministrator MethodsUnless otherwise specified, the following methods are in the classSmPolicyApiImpl. The following methods act on administrator objects. Youcreate an administrator object by instantiating SmAdmin.MethodaddAdmin()addAdminToDomain()deleteAdmin()getAdmin()DescriptionAdds an administrator object to thepolicy store.Associates an administrator with adomain.Deletes an administrator.Gets the contents of an administrator.getAdminUserDirs()modifyAdmin()removeAdminFromDomain()Gets a list of user directories that anadministrator can manage.Modifies an administrator.Disassociates an administrator from adomain.Agent MethodsUnless otherwise specified, the methods listed in this table are in the classSmPolicyApiImpl. The following methods act on agent objects. You create anagent object by instantiating SmAgent.MethodaddAgent()deleteAgent()getAgent()modifyAgent()DescriptionAdds an agent object to the policystore.Deletes an agent.Gets the contents of an agent.Modifies an agent.Chapter 4: Policy Management API 59

Agent Configuration Object MethodsAgent Configuration Object MethodsUnless otherwise specified, the methods listed in this table are in the classSmPolicyApiImpl. The following methods act on agent configuration objects.You define an agent configuration object by instantiating SmAgentConfig.MethodaddAgentConfig()deleteAgentConfig()DescriptionAdds an agent configuration object tothe policy store.Deletes an agent configuration object.getAgentConfig()modifyAgentConfig()Gets the contents of an agentconfiguration object.Modifies an agent configurationobject.Authentication and Authorization Map MethodsUnless otherwise specified, the methods listed in this table are in the classSmPolicyApiImpl. The following methods act on authentication andauthorization directory mapping objects. You create an authentication andauthorization directory mapping object by instantiating SmAuthAzMap.MethodaddAuthAzMap()deleteAuthAzMap()getAuthAzMap()modifyAuthAzMap()DescriptionAdds an authentication andauthorization directory mappingobject to the policy store.Deletes an authentication andauthorization directory mappingobject.Gets the contents of anauthentication and authorizationdirectory mapping object.Modifies an authentication andauthorization directory mappingobject.60 Developer's Guide for Java

Authentication Scheme MethodsAuthentication Scheme MethodsUnless otherwise specified, the methods listed in this table are in the classSmPolicyApiImpl. The following methods act on authentication schemes. Youcreate an authentication scheme by instantiating SmScheme.MethodaddScheme()deleteScheme()getScheme()modifyScheme()DescriptionAdds an authentication scheme to thepolicy store.Deletes an authentication scheme.Gets the contents of anauthentication scheme.Modifies an authentication scheme.Certificate Map MethodsUnless otherwise specified, the methods listed in this table are in the classSmPolicyApiImpl. The following methods act on certificate mapping objects.You create certificate mapping objects by instantiating SmCertMap.MethodaddCertMap()deleteCertMap()getCertMap()modifyCertMap()DescriptionAdds a certificate mapping object tothe policy store.Deletes a certificate mapping object.Gets the contents of a certificatemapping object.Modifies a certificate mapping object.Domain MethodsUnless otherwise specified, the methods listed in this table are in the classSmPolicyApiImpl. The following methods act on domain objects. You createdomain objects by instantiating SmDomain.MethodaddDomain()DescriptionAdds a domain object to the policystore.Chapter 4: Policy Management API 61

General Object MethodsMethoddeleteDomain()getDomain()getDomainObject()getDomainObjectNames()isDomainObject()DescriptionDeletes a domain.Gets the contents of a domain.Gets a domain object for the specifiedobject name or OID.Gets a list of domain objects within adomain.Indicates whether an object is adomain object.In classes SmObjectImpl,SmDomainObjectImpl.modifyDomain()Modifies a domain.General Object MethodsUnless otherwise specified, the methods listed in this table are in the classSmPolicyApiImpl. The following methods act on multiple types of objects.MethodgetGlobalObjectNames()getObject()getOid()DescriptionGets a list of global objects.Gets a global object for the specifiedobject name or OID.Retrieves an object identifier for anobject.In class SmObjectImpl.isWriteable()Specifies whether an object iswriteable.In classes SmAgentType,SmDomainObjectImpl, andSmObjectImpl.renameObject()Renames an object.62 Developer's Guide for Java

Group MethodsGroup MethodsUnless otherwise specified, the methods listed in this table are in the classSmPolicyApiImpl. The following methods act on group objects. Group objectsare created with SmAgentGroup (for agent groups), SmResponseGroup (forresponse groups), or SmRuleGroup (for rule groups).MethodaddGroup()addToGroup()deleteGroup()getGroup()getGroupMembers()modifyGroup()removeFromGroup()DescriptionAdds an agent, response, or rulegroup to the policy store.Adds a group element of type rule,response, or agent to the specifiedgroup.Deletes an existing group.Gets the contents of an existinggroup.Get a list of groups of all types.Modify a group.Removes a group element from agroup.Host Configuration Object MethodsUnless otherwise specified, the methods listed in this table are in the classSmPolicyApiImpl. The following methods act on host configuration objects. Youdefine a host configuration object by instantiating SmHostConfig.MethodaddHostConfig()deleteHostConfig()getHostConfig()modifyHostConfig()DescriptionAdds a host configuration object tothe policy store.Deletes a host configuration object.Gets the contents of a hostconfiguration object.Modifies a host configuration object.Chapter 4: Policy Management API 63

ODBC Query Scheme MethodsODBC Query Scheme MethodsUnless otherwise specified, the methods listed in this table are in the classSmPolicyApiImpl. The following methods act on ODBC Query schemes. Youcreate ODBC Query schemes by instantiating SmODBCQuery.MethodaddODBCQuery()deleteODBCQuery()getODBCQuery()modifyODBCQuery()DescriptionAdds an ODBC query object to thepolicy store.Deletes an ODBC query object.Gets the contents of an ODBC queryobject.Modifies an ODBC query object.Password Policy MethodsUnless otherwise specified, the methods listed in this table are in the classSmPolicyApiImpl. The following methods act on password policy objects. Youcreate password policy objects by instantiating SmPasswordPolicy.MethodaddPasswordPolicy()deletePasswordPolicy()getPasswordPolicy()isEnabled()DescriptionAdds a password policy object to thepolicy store.Deletes a password policy.Gets the contents of a passwordpolicy.Specifies whether the password policyis enabled.In class SmPasswordPolicy.isEntireDir()Specifies whether the password policyapplies to the entire directory.In class SmPasswordPolicy.modifyPasswordPolicy()Modifies a password policy.64 Developer's Guide for Java

Policy MethodsPolicy MethodsThe following methods act on policy and policy link objects. A policy link is anassociation of a policy, a rule, and optionally, a response. Unless otherwisespecified, these methods are in the class SmPolicyApiImpl.Policy objects are created with SmPolicy. Policy link objects are created withSmPolicyLink.MethodaddPolicy()addPolicyLink()deletePolicy()deletePolicyLink()getPolicy()getPolicyLinks()modifyPolicy()modifyPolicyLink()DescriptionAdds a policy object to the policystore.Adds a policy link to a policy.Deletes the policy associated with thespecified domain.Removes a policy link from a policy.Gets the contents of a policy.Gets all of the policy links for thespecified policy and domain.Modify the policy associated with thespecified domain.Modifies the specified policy link.Policy Migration MethodsThe following methods enable you to migrate policy data between remotePolicy Servers. Unless otherwise specified, these methods are in the classSmPolicyApiImpl.Functionally, the remote policy data export and import methods behave in thesame manner as the smobjexport and smobjimport utilities.Policy export attributes are set with SmExportAttr. Policy import parametersare set with SmImportAttr.MethoddoExport()DescriptionExports an entire policy store or asingle policy domain from a remotePolicy Server and writes the outputon the client’s local file system.Chapter 4: Policy Management API 65

Realm MethodsMethoddoImport()DescriptionImports an entire policy store or asingle policy domain onto a remotePolicy Server.Realm MethodsThe following methods act on realm objects. Realm objects are created withSmRealm.MethodaddRealm(()deleteRealm()getRealm()getRealmRules()getRealmUserPolicies()modifyRealm()DescriptionAdds a realm object to the policystore.Deletes a realm.Gets the contents of a realm.Gets all the rules for the specifiedrealm and domain.Gets a list of user policies that canaccess a realm.Modifies the specified realm.Response MethodsThe following methods act on response and response attribute objects. Unlessotherwise specified, these methods are in the class SmPolicyApiImpl.Response objects are created with SmResponse. Response attribute objectsare created with SmResponseAttr.MethodaddResponse()addResponseAttr()deleteResponse()deleteResponseAttribute()getResponse()DescriptionAdds a response object to the policystore.Creates a response attribute andassociates it with a response.Deletes a response.Deletes a response attribute.Gets the contents of a response.66 Developer's Guide for Java

Root Configuration MethodsMethodgetResponseAttrs()modifyResponse()setResponseInPolicyLink()DescriptionGets a list of attributes for thespecified response.Modify the specified response.Changes the response for thespecified policy link.Root Configuration MethodsThe following methods act on root configuration objects. Unless otherwisespecified, the methods listed in this table are in the class SmPolicyApiImpl.You create root configuration objects by instantiating SmRootConfig.MethodaddRootConfig()deleteRootConfig()getRootConfig()modifyRootConfig()DescriptionAdds a root configuration object tothe policy store.Deletes a root configuration.Gets the contents of a rootconfiguration.Modifies a root configuration.Rule MethodsThe following methods act on rule objects. Unless otherwise specified, themethods listed in this table are in the class SmPolicyApiImpl. You create ruleobjects by instantiating SmRule.MethodaddRule()DescriptionAdds a rule object to the policy store.deleteRule()getRule()modifyRule()Deletes a rule.Gets the contents of a rule.Modifies a rule.Chapter 4: Policy Management API 67

Self-Registration MethodsSelf-Registration MethodsThe following methods act on self-registration objects. Unless otherwisespecified, the methods listed in this table are in the class SmPolicyApiImpl.You create self-registration objects by instantiating SmSelfReg.MethodaddSelfReg()deleteSelfReg()getSelfReg()modifySelfReg()DescriptionAdds a self-registration object to thepolicy store.Deletes a self-registration object.Gets the contents of a selfregistrationobject.Modifies a self-registration object.Trusted Host Object MethodsThe following methods act on Trusted Host objects. Unless otherwise specified,the methods listed in this table are in the class SmPolicyApiImpl. You define aTrusted Host object by instantiating SmTrustedHost.MethodaddTrustedHost()deleteTrustedHost()DescriptionRegisters a trusted host with thePolicy Server.Deletes a trusted host object.User Directory MethodsUser management functionality is provided in the DMS API. However, thePolicy Management API provides methods for getting and setting userattributes. These methods are in the SmUserDirectory class.For example:■■To specify which user attribute holds the disabled state of the user, callsetDisabledAttr() in SmUserDirectory.To disable and enable users, use the DMS API.68 Developer's Guide for Java

User Policy MethodsThe following methods act on user directory objects. Unless otherwisespecified, the methods listed in this section are in the class SmPolicyApiImpl.You create user directory objects by instantiating SmUserDirectory.MethodaddUserDirectory()addUserDirToDomain()deleteUserDirectory()getDirectoryContents()getUserDirectory()getUserDirSearchOrder()lookupDirectory()modifyUserDirectory()removeUserDirFromDomain()setUserDirSearchOrder()DescriptionAdds a user directory object to thepolicy store.Associates an existing user directorywith a domain.Deletes a user directory.Gets a list of distinguished names andclasses for the specified userdirectory.Gets the contents of a user directory.Retrieves the search order of userdirectories for a domain by retrievinga vector of user directory names.Gets a list of distinguished names andclasses for the specified userdirectory and search pattern.Modifies a user directory.Disassociates an existing userdirectory from a domain.Sets the search order of userdirectories in a domain.User Policy MethodsThe following methods act on user policy objects. Unless otherwise specified,the methods listed in this table are in the class SmPolicyApiImpl. You createuser policy objects by instantiating SmUserPolicy.MethodaddUserPolicy()deleteUserPolicy()DescriptionAdds a user policy object to the policystore.Deletes a user policy for a specifieddomain.Chapter 4: Policy Management API 69

Utility MethodsMethodgetUserPolicies()DescriptionGets all the user policies for thespecified policy and domain.Utility MethodsThe following methods provide a variety of services, including cache andencryption key management. Unless otherwise specified, the methods listed inthis table are in the class SmPolicyApiImpl.MethodchangeDynamicKey()changePersistentKey()changeSessionKey()flushAll()flushRealm()flushRealms()flushUser()flushUsers()search()setApiSession()DescriptionChanges a dynamic encryption key.Changes the persistent encryptionkey.Changes the session encryption key.Flushes all SiteMinder caches.Flushes a realm from the resourcecache.Flushes all realms from the resourcecache.Flushes a user from the userinformation cache.Flushes all users from the informationcache.Searches the specified object.Sets the API session object.Object AssociationsSome objects can be associated with or disassociated from one another—forexample, AddAdminToDomain() adds an administrator object to a domain, andRemoveAdminFromDomain() removes an administrator object from a domain.An add-to operation requires that both objects exist prior to the call. After aremove-from operation, both objects still exist, but they are no longerassociated with one other.70 Developer's Guide for Java

Add Objects to the Policy StoreWhen you are looking for a method that associates or disassociates twoobjects, look in the category of the method that you are adding or removing.For example, AddAdminToDomain() and RemoveAdminFromDomain() are bothfound in Administrator Methods.Add Objects to the Policy StoreAfter creating a Policy Management API object, you can create objects to addto the policy store.To add objects to the policy store1. Create an object to be added to the policy store.For example, if you want to create an agent object:SmAgent agent = new SmAgent();2. Set the appropriate fields for the object—for example:agent.setName ("myAgent");agent.setSecret ("siteminder");agent.setDescription ("Sample agent");agent.setAgentType (SmAgentType.DefaultAgentType);3. Add the object to the policy store, as follows:■■Call the add... method for the object you just created—for example,addAgent() for an agent object, or addDomain() for a domain object—and pass in the object you want to add to the policy store.Returning the result into a result object.For example:result = policyApi.addAgent(agent);4. Examine the result.If the call is successful:■■■The method returns an SmApiResult object whose isSuccess() methodreturns true.The object is added to the SiteMinder policy store.The Oid field in the corresponding object structure is set to the objectidentifier.Chapter 4: Policy Management API 71

Retrieve Objects from the Policy StoreRetrieve Objects from the Policy StoreTo retrieve an object from the policy store1. Create an object of the relevant class to store the returned properties. Forexample, the following code creates an agent object:SmAgent myAgent = new SmAgent();2. Call the appropriate get... function for the object you just created—forexample, getAgent() for an agent object, or getDomain() for a domainobject—and pass in the object you just created. For example, if you’reretrieving an agent named myAgent:result = myPolicyApi.getAgent ("myAgent", myAgent);If the method succeeds, it populates myAgent with the properties of thespecified agent object. (If a get... method retrieves a list, the list is written toa vector.) If no matching objects are found, the properties of the receivingobject retain their initial values.Delete Objects from the Policy StoreA delete operation deletes an object from the policy store. You can only deleteone object at a time from the policy store.To delete an object, use the object-deletion method for the object you’redeleting—for example, deleteAgent() for an agent object, or deleteDomain()for a domain objectAuthentication Scheme ConfigurationWhen you configure an authentication scheme programmatically, you provideinformation that would otherwise be provided through the AuthenticationScheme Properties dialog box of the Policy Server UI. For backgroundinformation on configuring an authentication scheme, see the chapter onauthentication schemes in CA eTrust Policy Design.72 Developer's Guide for Java

Authentication Scheme ConfigurationWhen you configure an authentication scheme, you use the get... and set...methods in the SmScheme class to provide the following information:■Scheme typeSiteMinder provides a number of standard authentication scheme types(also called templates). Each authentication scheme type is configureddifferently. The scheme types are descibed in subsequent topics.■DescriptionBrief description of the authentication scheme.■Protection levelProtection level values can range from 1 through 1000. The higher thenumber, the greater the degree of protection provided by the scheme.■LibraryAn authentication scheme library performs authentication processing forthe associated authentication scheme type. Each pre-definedauthentication scheme is shipped with a default library, which you typicallywill use. But optionally, you can use a custom library instead of thedefault.■ParameterAdditional information that the authentication scheme requires, such asthe URL of an HTML login page.With some authentication schemes, the parameter information isconstructed from field values in the Scheme Type Setup tab of theAuthentication Scheme Properties dialog box. To see how a parameterstring might be constructed for a given scheme type, open this dialog box,choose the appropriate scheme type, provide values to the fields in theScheme Type Setup tab, and view the constructed parameter in theAdvanced tab.For information on providing parameter values for different authenticationscheme types, see the chapter on authentication schemse in CA eTrustPolicy Design.■Shared SecretInformation that is known to both the authentication scheme and thePolicy Server. Different authentication schemes use different kinds ofsecrets. Most schemes use no secret.■Is template?A flag that specifies whether the authentication scheme is a template.Chapter 4: Policy Management API 73

Authentication Scheme Configuration■Is used by administrator?A flag that specifies whether the authentication scheme can be used toauthenticate administrators.■Save Credentials?A flag that specifies whether the user’s credentials will be saved.■Is RADIUS?A flag that specifies whether the scheme can be used with RADIUS agents.■Ignore password check?A flag that specifies whether password policies for the scheme areenabled. If True (1), password policies will be disabled.Note: These categories of information can be used for different purposes indifferent authentication schemes. For example, with the TeleID authenticationscheme, the shared secret is used to supply the encryption seed.74 Developer's Guide for Java

Authentication Scheme ConfigurationConfiguration InformationWhen you configure an authentication scheme, you provide the following kindsof configuration information. This information is managed through get... andset... methods in the SmScheme class.Note: The categories of information below can be used for different purposesin different authentication schemes. For example, with the TeleIDauthentication scheme, the shared secret is used to supply the encryptionseed.■Scheme typeSiteMinder provides a number of standard authentication scheme types(also called templates). Each authentication scheme type is configureddifferently.The following scheme types are available. The are listed below as theyappear in the Authentication Scheme Type field of the Policy ServerAuthentication Scheme Properties dialog box:■■■■■■■■■■■■■■■■■■■■Anonymous TemplateBasic Over SSL TemplateBasic TemplateCRYPTOCard RB-1 TemplateCustom TemplateHTML Form TemplateImpersonation TemplateMS Passport TemplateRADIUS CHAP/PAP TemplateRADIUS Server TemplateSafeWord HTML Form TemplateSafeWord TemplateSecurID HTML Form Template (ACE server)SecurID Template (ACE server)smauthetsso Authentication Scheme (uses Custom Template)TeleID Template (Encotone)Windows Authentication TemplateX.509 Client Cert and Basic TemplateX.509 Client Cert and Form TemplateX.509 Client Cert or Basic TemplateChapter 4: Policy Management API 75

Authentication Scheme Configuration■X.509 Client Cert or Form Template■■X.509 Client Cert TemplateDescriptionBrief description of the authentication scheme.■Protection levelProtection level values can range from 1 through 1000. The higher thenumber, the greater the degree of protection provided by the scheme.■LibraryAn authentication scheme library performs authentication processing forthe associated authentication scheme type. Each pre-definedauthentication scheme is shipped with a default library, which you typicallywill use. But optionally, you can use a custom library instead of thedefault.■ParameterAdditional information that the authentication scheme requires, such asthe URL of an HTML login page.With some authentication schemes, the parameter information isconstructed from field values in the Scheme Type Setup tab of theAuthentication Scheme Properties dialog box. To see how a parameterstring might be constructed for a given scheme type, open this dialog box,choose the appropriate scheme type, provide values to the fields in theScheme Type Setup tab, and view the constructed parameter in theAdvanced tab.■Shared SecretInformation that is known to both the authentication scheme and thePolicy Server. Different authentication schemes use different kinds ofsecrets. Most schemes use no secret.■Is template?A flag that specifies whether the authentication scheme is a template.■Is used by administrator?A flag that specifies whether the authentication scheme can be used toauthenticate administrators.■Save Credentials?A flag that specifies whether the user’s credentials will be saved.■Is RADIUS?A flag that specifies whether the scheme can be used with RADIUS agents.■Ignore password check?76 Developer's Guide for Java

Authentication Scheme ConfigurationA flag that specifies whether password policies for the scheme areenabled. If True (1), password policies will be disabled.Anonymous TemplateUse this table when configuring an authentication scheme based on thescheme type Anonymous. The Java methods referenced in the table are in theclass SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeAnonymous)The scheme type Anonymous.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(0)Set to 0. Not applicable to this scheme type.LibrarysetLibrary("smauthanon")The default library for this scheme type.ParametersetParameter(param)A string containing the guest DN. Policies associatedwith the guest DN must apply to anonymous users.Shared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(0)Set to false (0)—scheme is not used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(0)Set to false (0)—scheme is not used with RADIUSagents.Ignore passwordcheck?setIgnorePwCheck(1)Set to true (1)—ignore password checking.Chapter 4: Policy Management API 77

Authentication Scheme ConfigurationBasic Over SSL TemplateUse this table when configuring an authentication scheme based on thescheme type Basic over SSL. The Java methods referenced in the table are inthe class SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeBasicOverSSL)The scheme type Basic over SSL.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 10.LibrarysetLibrary("smauthcert")The default library for this scheme type.ParametersetParameter(param)A string containing the domain or IP address of the SSLserver and the name of the SSL Credentials Collector(SCC). Format:https://server/SCC?basicThe following example uses the default SCC:https://my.server.com/siteminderagent/nocert/smgetcred.scc?basicShared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(0)Set to false (0) for this scheme.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Chapter 4: Policy Management API 79

Authentication Scheme ConfigurationInformation TypeIs RADIUS?Value Assignment and MeaningsetIsRadius(0)Set to false (0)—scheme is not used with RADIUSagents.Ignore passwordcheck?setIgnorePwCheck(flag)Set to true (1) to ignore password checking, or false(0) to check passwords. Default is 0.CRYPTOCard RB-1 TemplateUse this table when configuring an authentication scheme based on thescheme type CRYPTOCard RB-1. The Java methods referenced in the table arein the class SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeCryptoCard)The scheme type CRYPTOCard RB-1.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 15.LibrarysetLibrary("smauthcryptocard")The default library for this scheme type.ParametersetParameter("")Set to an empty string. Not applicable to this scheme.Shared secretsetSecret(secret)The secret used to initialize the token cards. The secretis stored in the CRYPTOCard Ccsecret file. This file issupplied by the token vendor.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?setIsUsedByAdmin(1)Set to true (1)—scheme can be used to authenticateadministrators.80 Developer's Guide for Java

individuals might increase their inappropriate behavior in the group if contingent observationprovides them with the opportunity to engage in higher rates of self-stimulation. Someindividuals might also increase their inappropriate behavior in the group if the escape from thegroup or activity provided by contingent observation is reinforcing.10. Response Blocking or InterruptionResponse blocking is the physical interruption of a specific behavior by interposing abarrier (a hand, forearm, etc.) to temporarily prevent motion. Response blocking is intended toprevent the normal consequence of a behavior when said consequence may be immediatelyreinforcing.Response blocking does not involve extended grasping and holding of an individual. Byitself, response blocking does not promote adaptive behavior; hence the procedure is almostalways used in conjunction with DRO, DRI, DRA, or some other reinforcement procedure.Example of Response Blocking or InterruptionAs an example of response blocking, a staff member would stand behind a seatedindividual who regularly engages in head banging. When the individual attempts to hit himself,the staff member quickly interposes his own hand between the individual’s hand and head,momentarily blocking the individual’s range of motion and preventing a blow to the head.A second staff member concurrently works with the individual using reinforcementprocedures to promote the individual’s involvement in some functional task incompatible withhead banging.11. Restoration of EnvironmentRestoration of the environment is a method used to have the disruptive individual returnthe environment to the condition in which it was prior to the disruption displayed by thatindividual. Restoration of the environment is not restitution in that the individual does not haveto modify the environment into a vastly improved state. The staff working with the individualshould use the least amount of prompting and guidance necessary to ensure that the individualreturns items to their original location and condition. Verbal prompts and facial expressions ofstaff should be "matter of fact" with no emotions displayed. Excessive talk and expression duringthis procedure can be reinforcing to the individual who has disrupted the environment, leading toan increase in the disruptive behavior. The individual is simply directed to rearrange those partsof the environment that he has disrupted.In order to utilize restoration of the environment, the individual must have the skills andphysical ability necessary to restore the environment to its original condition. If the individual isunable to perform full restoration, then partial restoration may be appropriate. Successfulrestoration is not to be followed by praise for the individual. If praised, the individual could learnBehavior Supports Manual 81 of 88Applicable to Providers Under Contract or LOA with the Division of MHDDAD April 2005

Authentication Scheme ConfigurationInformation TypeLibraryValue Assignment and MeaningsetLibrary("smauthhtml")The default library for this scheme type.ParametersetParameter(param)A string containing a user attribute list plus the locationof the forms credential collector (FCC). The attributelist must begin with AL= and use commas as the listdelimiter character, and it must end with a semicolon—for example:AL=Password,SSN,age,zipcode;The complete parameter format is:attr-list;https:/server/fccThe following example uses the default FCC:AL=PASSWORD,SSN,age,zipcode;http://my.server.com/siteminderagent/forms/login.fccShared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(0)Set to false (0)—scheme is not used to authenticateadministrators.setAllowSaveCreds(flag)Set to true (1) to indicate that user credentials shouldbe saved, or false (0) to indicate that user credentialsshould not be saved. Default is 0.Is RADIUS?setIsRadius(0)Set to false (0)—scheme is not used with RADIUSagents.Ignore passwordcheck?setIgnorePwCheck(flag)Set to true (1) to ignore password checking, or false(0) to check passwords. Default is 0.Chapter 4: Policy Management API 83

Authentication Scheme ConfigurationImpersonation TemplateUse this table when configuring an authentication scheme based on schemetype Impersonation. The Java methods referenced in the table are in the classSmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeImpersonation)The scheme type Impersonation.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 5.LibrarysetLibrary("smauthimpersonate")The default library for this scheme type.ParametersetParameter(param)A string containing a user attribute list plus the locationof the forms credential collector (FCC). The attributelist must begin with AL= and use commas as the listdelimiter character, and it must end with a semicolon—for example:AL=Password,SSN,age,zipcode;The complete parameter format is:attr-list;https:/server/fccThe following example uses the default FCC:AL=PASSWORD,SSN,age,zipcode;http://my.server.com/siteminderagent/forms/imp.fccShared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(templateFlag)Set to false (0) to indicate that the scheme is not atemplate.84 Developer's Guide for Java

Authentication Scheme ConfigurationInformation TypeIs used byadministrator?Save credentials?Value Assignment and MeaningsetIsUsedByAdmin(0)Set to false (0)—scheme is not used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(0)Set to false (0)—scheme is not used with RADIUSagents.Ignore passwordcheck?setIgnorePwCheck(1)Set to true (1)—ignore password checking.MS Passport TemplateUse this table when configuring an authentication scheme based on schemetype MS Passport. The Java methods referenced in the table are in the classSmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeMSPassport)The scheme type MS Passport.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 1.LibrarysetLibrary("smauthmspp")The default library for this scheme type.Chapter 4: Policy Management API 85

Authentication Scheme ConfigurationInformation TypeParameterValue Assignment and MeaningsetParameter(param)The following information, separated by semicolons:• A DN for an anonymous user. Format:anonuser=anonUserDNIf you specify an anonymous user DN, the protectionlevel is 0.• The search string for looking up a user in a userdirectory of the specified type. Format:attribute=nameSpace:attrib=searchSpecValid namespaces are LDAP, AD, ODBC, WinNT, andCustom.• The registration URL. The URL can be a custom URLor a SiteMinder form. Formats:registrationurl=URL (custom URL)registrationurl=FORM=URL (SiteMinder form)Example using an LDAP attribute and a custom URL:attribute=LDAP:altSecurityIdentities=Kerberos:%s@company.local;registrationurl=http://passport.xanadu.local/registration/passportreg.aspShared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(templateFlag)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(0)Set to false (0)—scheme is not used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(0)Set to false (0)—scheme is not used with RADIUSagents.86 Developer's Guide for Java

Authentication Scheme ConfigurationInformation TypeIgnore passwordcheck?Value Assignment and MeaningsetIgnorePwCheck(1)Set to true (1)—ignore password checking.RADIUS CHAP/PAP TemplateUse this table when configuring an authentication scheme based on thescheme type RADIUS CHAP/PAP. The Java methods referenced in the table arein the class SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeRadiusChapPap)The scheme type RADIUS CHAP/PAP.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 5.LibrarysetLibrary("smauthchap")The default library for this scheme type.ParametersetParameter(param)A string containing the name of a user directoryattribute. This attribute is used as the clear textpassword for authentication.Shared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(0)Set to false (0)—scheme is not used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Chapter 4: Policy Management API 87

Authentication Scheme ConfigurationInformation TypeIs RADIUS?Value Assignment and MeaningsetIsRadius(1)Set to true (1)—scheme can be used with RADIUSagents.Ignore passwordcheck?setIgnorePwCheck(flag)Set to true (1) to ignore password checking, or false(0) to check passwords. Default is 0.RADIUS Server TemplateUse this table when configuring an authentication scheme based on thescheme type RADIUS Server. The Java methods referenced in the table are inthe class SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeRadiusServer)The scheme type RADIUS Server.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 5.LibrarysetLibrary("smauthradius")The default library for this scheme type.ParametersetParameter(param)A string containing the IP address and port of theRADIUS server—for example:123.123.12.12:1645The default UDP port is 1645.Shared secretsetSecret(secret)The user attribute that the RADIUS Server will use asthe clear text password.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.88 Developer's Guide for Java

Authentication Scheme ConfigurationInformation TypeIs used byadministrator?Save credentials?Value Assignment and MeaningsetIsUsedByAdmin(1)Set to true (1)—scheme can be used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(1)Set to true (1)—scheme can be used with RADIUSagents..Ignore passwordcheck?setIgnorePwCheck(flag)Set to true (1) to ignore password checking, or false(0) to check passwords. Default is 0.SafeWord HTML Form TemplateUse this table when configuring an authentication scheme based on thescheme type SafeWord HTML Form. The Java methods referenced in the tableare in the class SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeSafeWordHTMLForm)The scheme type SafeWord HTML Form.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 10.LibrarysetLibrary("smauthenigmahtml")The default library for this scheme type.ParametersetParameter(param)A string containing the name and location of the formscredentials collector. This example shows the defaultcredentials collector:http://my.server.com/siteminderagent/forms/safeword.fccChapter 4: Policy Management API 89

Authentication Scheme ConfigurationInformation TypeShared secretValue Assignment and MeaningsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(1)Set to true (1)—scheme can be used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(1)Set to true (1)—scheme can be used with RADIUSagents..Ignore passwordcheck?setIgnorePwCheck(1)Set to true (1)—ignore password checking.SafeWord TemplateUse this table when configuring an authentication scheme based on thescheme type SafeWord. The Java methods referenced in the table are in theclass SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeSafeWordServer)The scheme type SafeWord.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 10.LibrarysetLibrary("smauthenigma")The default library for this scheme type.90 Developer's Guide for Java

Authentication Scheme ConfigurationInformation TypeParameterValue Assignment and MeaningsetParameter("")Set to an empty string. Not applicable to this scheme.Shared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(1)Set to true (1)—scheme can be used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(1)Set to true (1)—scheme can be used with RADIUSagents..Ignore passwordcheck?setIgnorePwCheck(1)Set to true (1)—ignore password checking.SAML Artifact TemplateUse this table when configuring an authentication scheme based on SiteMinderFederation Security Services. The Federation Security Services feature islicensed separately. The Java methods referenced in the table are in the classSmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeSAMLArtifact)The scheme type SAML Artifact.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 5.Chapter 4: Policy Management API 91

Authentication Scheme ConfigurationInformation TypeLibraryValue Assignment and MeaningsetLibrary("smauthsaml")The default library for this scheme type.92 Developer's Guide for Java

Authentication Scheme ConfigurationInformation TypeParameterValue Assignment and MeaningsetParameter(param)The following required parameters:• Name. The name of the affiliate.• RedirectMode. The way in which the SAMLCredentials Collector redirects to the targetresource. One of the following numeric values:0. Meaning: 302 No Data.1. Meaning: 302 Cookie Data.2. Meaning: Server Redirect.• SRCID. The 20-byte source ID for the site thatproduces the SAML assertion. The ID is located atthe SAML producer’s site in the properties fileAMAssertionGenerator.properties.• AssertionRetrievalURL. The URL for obtaining theassertion from the SAML assertion producer’s site.• Audience. The URI of the document that describesthe agreement between the portal and the affiliate.This value is compared with the audience valuespecified in the SAML assertion.• Issuer. The SAML issuer specified in the assertion.• AttributeXPath. A standard XPath query run againstthe SAML assertion. The query obtains the datathat is substituted in a search specification thatlooks up a user.• attribute. The search string for looking up a user ina user directory of the specified type. Use a percentsign ( % ) to indicate where the value returnedfrom the XPath query should be inserted. Forexample, if you specify attribute LDAP:uid=%s,and user1 is returned from the query, the searchstring used for LDAP directories is uid=user1. Atleast one attribute must be specified.Format of the parameter string is as follows. Separatename/value pairs with semi-colons ( ; ). The formatexample includes LDAP and ODBC attributes:Name=name;RedirectMode=0|1|2;SRCID=srcid;AssertionRetrievalURL=url;Audience=audience;Issuer=issuer;AttributeXpath=XPathQuery;attribute=LDAP:srchSpc;attribute=ODBC:srchSpcChapter 4: Policy Management API 93

Authentication Scheme ConfigurationInformation TypeShared secretValue Assignment and MeaningsetSecret(secret)The password for the affiliate site.Is template?setIsTemplate(templateFlag)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(0)Set to false (0)—scheme is not used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(0)Set to false (0)—scheme is not used with RADIUSagents.Ignore passwordcheck?setIgnorePwCheck(1)Set to true (1)—ignore password checking.SecurID HTML Form TemplateUse this table when configuring an authentication scheme based on thescheme type SecurID HTML Form. The Java methods referenced in the tableare in the class SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeACEServerHTMLForm)The scheme type SecurID HTML Form.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 15.LibrarysetLibrary("smauthacehtml")The default library for this scheme type.94 Developer's Guide for Java

Authentication Scheme ConfigurationInformation TypeParameterValue Assignment and MeaningsetParameter(param)A string containing the name of the attribute thatcontains the ACE IDs, the Web server where the formscredential collector (FCC) is installed, and the targetexecutable file required for processing SecurIDauthentication with forms support. It also specifieswhether an SSL connection is required. Format:attr;https://server/targetNote: The "s" in "https" is optional, depending onwhether you want an SSL connection.The following example uses the default for processingSecurID authentication with forms support:ace_id;https://my.server.com/siteminderagent/pwcgi/smpwservicescgi.exeShared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(0)Set to false (0)—scheme is not used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(0)Set to false (0)—scheme is not used with RADIUSagents.Ignore passwordcheck?setIgnorePwCheck(1)Set to true (1)—ignore password checking.Chapter 4: Policy Management API 95

Authentication Scheme ConfigurationSecurID TemplateUse this table when configuring an authentication scheme based on thescheme type SecurID. The Java methods referenced in the table are in theclass SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeACEServer)The scheme type SecurID.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 15.LibrarysetLibrary("smauthace")The default library for this scheme type.ParametersetParameter(param)A string containing the attribute in the authenticationuser directory that contains the ACE Server user ID.Shared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(1)Set to true (1)—scheme can be used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(1)Set to true (1)—scheme can be used with RADIUSagents.Ignore passwordcheck?setIgnorePwCheck(1)Set to true (1)—ignore password checking.96 Developer's Guide for Java

Authentication Scheme Configurationsmauthetsso Authentication SchemeThe smauthetsso authentication scheme is similar to the SiteMinder X.509certification scheme, but with an eSSO cookie as the authentication credentialinstead of an X.509 credential.If this scheme is configured for either cookieorbasic or cookieorforms mode,and both an eSSO cookie and login name and password credentials are passedto it, the eSSO cookie is ignored, and the login name and password are usedto authenticate the user to SiteMinder.When the eSSO cookie is the only credential, the authentication scheme usesthe ETWAS API to connect to the configured eSSO Policy Server to validate thecookie and extract the user Distinguished Name (DN) from it.Use this table when configuring an smauthetsso authentication scheme, whichis based on the scheme type Custom. The Java methods referenced in thetable are in the class SmScheme.Information Type Value Assignment and MeaningScheme typesetType(TypeCustom)Uses the scheme type Custom.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 0 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 5.LibrarysetLibrary("smauthetsso")The name of the library for this authentication scheme.Chapter 4: Policy Management API 97

Authentication Scheme ConfigurationInformation Type Value Assignment and MeaningParametersetParameter(param)An ordered set of tokens, separated by semi-colons:[; ]; ; You can add spaces to make the string easier to read. specifies the type of credentials that theauthenticaion scheme will accept. The following valuesare possible:• cookie -- Only eTrust SSO Cookies are acceptable• cookieorbasic -- If an eTrust SSO Cookie is notprovided, a login name and password are requestedby using Basic Authentication.• cookieorforms -- If an eTrust SSO Cookie is notprovided, a login name and password are requestedby using Forms Authentication. is valid only with cookieorforms mode. This isidentical to the Target field for standard HTML FormsAuthentication Scheme. specifies the login ID of an administrator forthe eTrust Policy Server. The password for thisadministrator has been specified in the Shared Secretfield. specifies the name of the amchine onwhich the Policy Server is installed.SiteMinder will authenticate itself as to theeTrust Policy Server on the so thatSiteMinder can request validation of eTrust SSO cookies.Examples:"cookie; SMPS_sso; myserver.myco.com""cookieorforms; /siteminderagent/forms/login.fcc;SMPS_sso; myserver.myco.com"Shared secretsetSecret(secret)The password of the eTrust Policy Server administratornamed in the Parameter field.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.98 Developer's Guide for Java

Authentication Scheme ConfigurationInformation Type Value Assignment and MeaningIs used byadministrator?Save credentials?setIsUsedByAdmin(flag)Set to true (1) to specify that the scheme can be used toauthenticate administrators, or to false (0) to specifythat the scheme cannot be used to authenticateadministrators. Default is 0.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’t besaved.Is RADIUS?setIsRadius(0)Set to false (0)—scheme is not used with RADIUSagents.Ignore passwordcheck?setIgnorePwCheck(flag)Set to true (1) to ignore password checking, or false (0)to check passwords. Default is 0.TeleID TemplateUse this table when configuring an authentication scheme based on thescheme type TeleID. The Java methods referenced in the table are in the classSmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeEncotone)The scheme type TeleID.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 15.LibrarysetLibrary("smauthencotone")The default library for this scheme type.ParametersetParameter("")Set to an empty string. Not applicable to this scheme.Chapter 4: Policy Management API 99

Authentication Scheme ConfigurationInformation TypeShared secretValue Assignment and MeaningsetSecret(seed)The encryption seed. SiteMinder uses this value as anencryption seed for initializing hardware tokens.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(1)Set to true (1)—scheme can be used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(1)Set to true (1)—scheme can be used with RADIUSagents..Ignore passwordcheck?setIgnorePwCheck(1)Set to true (1)—ignore password checking.Windows Authentication TemplateUse this table when configuring an Integrated Windows Authentication schemebased on the scheme type Windows Authentication (previously known asNTLM). This scheme type is used to authenticate against WinNT or ActiveDirectory user stores.An Active Directory can be configured to run in mixed mode or native mode.An Active Directory supports WinNT style authentication when running inmixed mode. In native mode, an Active Directory supports only LDAP stylelookups.This authentication scheme supports either mixed mode or native mode.The Java methods referenced in the table are in the class SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeNTLM)The scheme type Windows Authentication (NTLM).100 Developer's Guide for Java

Authentication Scheme ConfigurationInformation TypeDescriptionValue Assignment and MeaningsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 5.LibrarysetLibrary("smauthntlm")The default library for this scheme type.Chapter 4: Policy Management API 101

Authentication Scheme ConfigurationInformation TypeParameterValue Assignment and MeaningsetParameter(param)The value of param determines the style ofauthentication to perform for this scheme:NTLM authentication (for WinNT or Active Directoryrunning in mixed mode)Format:iis-web-server-url/path-to-ntc-fileIn the format, iis-web-server-url is the name of the IISweb server that is the target of the redirection, andpath-to-ntc-file is the location of the .ntc file thatcollects the WinNT credentials.For example:http://myiiswebserver.mycompany.com/siteminderagent/ntlm/creds.ntcA SiteMinder Web Agent must be installed on thespecified server. By default, the Web Agent installationcreates a virtual directory for NTLM credentialcollection.Windows Authentication (for Active Directoryrunning in native mode)With this authentication style, param has an LDAP filteradded to the beginning of the redirection URL. Thefilter and URL are separated by a semi-colon (;). Forexample:cn=%{UID},ou=Users,ou=USA,dc=%{DOMAIN},dc=mycompany,dc=com;http://myiiswebserver.mycompany.com/siteminderagent/ntlm/creds.ntcSiteMinder uses the LDAP filter to map credentialsreceived from the browser/Web Agent to an LDAP DNor search filter.Shared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.102 Developer's Guide for Java

Authentication Scheme ConfigurationInformation TypeIs used byadministrator?Save credentials?Value Assignment and MeaningsetIsUsedByAdmin(0)Set to false (0)—scheme is not used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials will notbe saved.Is RADIUS?setIsRadius(0)Set to false (0)—scheme is not used with RADIUSagents.Ignore passwordcheck?setIgnorePwCheck(flag)For WinNT and for Active Directory running in mixedmode, this property must be true (1)—ignore passwordchecking.For Active Directory running in native mode, set to true(1) to ignore password checking, or false (0) to checkpasswords. The default is 0.X.509 Client Cert and Basic TemplateUse this table when configuring an authentication scheme based on thescheme type X.509 Client Certificate and Basic. The Java methods referencedin the table are in the class SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeX509ClientCertAndBasic)The scheme type X.509 Client Certificate and Basic.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 15.LibrarysetLibrary("smauthcert")The default library for this scheme type.Chapter 4: Policy Management API 103

Authentication Scheme ConfigurationInformation TypeParameterValue Assignment and MeaningsetParameter(param)A string containing the domain or IP address of the SSLserver and the name and path of the SSL CredentialsCollector (SCC). The server redirects a user’s X.509certificate over an SSL connection. Format:https://server:port/SCC?cert+basicThe following example uses the default SCC:https://my.server.com:80/siteminderagent/cert/smgetcred.scc?cert+basicShared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(0)Set to false (0)—scheme is not used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(0)Set to false (0)—scheme is not used with RADIUSagents.Ignore passwordcheck?setIgnorePwCheck(flag)Set to true (1) to ignore password checking, or false(0) to check passwords. Default is 0.104 Developer's Guide for Java

Authentication Scheme ConfigurationX.509 Client Cert and Form TemplateUse this table when configuring an authentication scheme based on thescheme type X.509 Client Certificate and Form. The Java methods referencedin the table are in the class SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeX509ClientCertAndForm)The scheme type X.509 Client Certificate and HTMLForm.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 15.LibrarysetLibrary("smauthcert")The default library for this scheme type.ParametersetParameter(param)A string containing the domain or IP address of the SSLserver and the name and path of the forms credentialscollector (FCC). The server redirects a user’s X.509certificate over an SSL connection. Format:https://server:port/FCC?cert+formsThe following example uses the default FCC:https://my.server.com:80/siteminderagent/certoptional/forms/login.fcc?cert+formsShared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to 0 to indicate that the scheme is not a template,or 1 if the scheme is a template. Default is 0.Is used byadministrator?setIsUsedByAdmin(0)Set to 0—scheme is not used to authenticateadministrators.Chapter 4: Policy Management API 105

Authentication Scheme ConfigurationInformation TypeSave credentials?Value Assignment and MeaningsetAllowSaveCreds(0)Set to 0 to indicate that user credentials won’t besaved.Is RADIUS?setIsRadius(0)Set to 0—scheme is not used with RADIUS agents.Ignore passwordcheck?setIgnorePwCheck(flag)Set to 1 to ignore password checking, or 0 to checkpasswords. Default is 0.X.509 Client Cert or Basic TemplateUse this table when configuring an authentication scheme based on thescheme type X.509 Client Certificate or Basic. The Java methods referenced inthe table are in the class SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeX509ClientCertOrBasic)The scheme type X.509 Client Certificate or Basic.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 5.LibrarysetLibrary("smauthcert")The default library for this scheme type.106 Developer's Guide for Java

Authentication Scheme ConfigurationInformation TypeParameterValue Assignment and MeaningsetParameter(param)A string containing the following information:Server for establishing an SSL connection. This serverredirects a user’s X.509 certificate over an SSLconnection.Name and path of the SSL Credentials Collector (SSC).If you are using basic authentication over SSL, alsoprovide the following two pieces of information:The fully qualified name of the SSL server used forestablishing an SSL connection for basic authentication.Name and path of the SSL Credentials Collector (SSC).https://SSLserver:port/SCC?certorbasic;[https://BasicServer/SCC]The following example uses the default SCC values:https://my.SSLserver.com:80/siteminderagent/certoptional/smgetcred.scc?certorbasic;https://my.BasicServer.com/siteminderagent/nocert/smgetcred.sccShared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(0)Set to false (0)—scheme is not used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(0)Set to false (0)—scheme is not used with RADIUSagents.Chapter 4: Policy Management API 107

Authentication Scheme ConfigurationInformation TypeIgnore passwordcheck?Value Assignment and MeaningsetIgnorePwCheck(flag)Set to true (1) to ignore password checking, or false(0) to check passwords. Default is 0.X.509 Client Cert or Form TemplateUse this table when configuring an authentication scheme based on thescheme type X.509 Client Certificate or Form. The Java methods referenced inthe table are in the class SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeX509ClientCertOrForm)The scheme type X.509 Client Certificate or HTMLForm.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 5.LibrarysetLibrary("smauthcertorform")The default library for this scheme type.108 Developer's Guide for Java

Authentication Scheme ConfigurationInformation TypeParameterValue Assignment and MeaningsetParameter(param)A string containing the following information:• Server for establishing an SSL connection. Thisserver redirects a user’s X.509 certificate over anSSL connection.• Name and path of the SSL and forms credentialscollector (SFCC).If you are using an alternate forms-basedauthentication over SSL, also provide the following twopieces of information:• The fully qualified name of the SSL server used forestablishing an SSL connection for authentication.• Name and path of the Forms Credentials Collector(FCC).https://SSLserver:port/SFCC?certorform;[https://BasicServer/FCC]The following example uses the default SCC values:https://my.SSLserver.com:80/siteminderagent/certoptional/forms/login.sfcc?certorform;https://my.BasicServer.com/siteminderagent/forms/login.fccShared secretsetSecret("")Set to an empty string. Not applicable to this scheme.Is template?setIsTemplate(0)Set to 0 to indicate that the scheme is not a template,or 1 if the scheme is a template. Default is 0.Is used byadministrator?Save credentials?setIsUsedByAdmin(0)Set to 0—scheme is not used to authenticateadministrators.setAllowSaveCreds(0)Set to 0 to indicate that user credentials won’t besaved.Is RADIUS?setIsRadius(0)Set to 0—scheme is not used with RADIUS agents.Chapter 4: Policy Management API 109

Authentication Scheme ConfigurationInformation TypeIgnore passwordcheck?Value Assignment and MeaningsetIgnorePwCheck(flag)Set to 1 to ignore password checking, or 0 to checkpasswords. Default is 0.X.509 Client Cert TemplateUse this table when configuring an authentication scheme based on thescheme type X.509 Client Certificate. The Java methods referenced in thetable are in the class SmScheme.Information TypeScheme typeValue Assignment and MeaningsetType(TypeX509ClientCert)The scheme type X.509 Client Certificate.DescriptionsetDescription(description)The description of the authentication scheme.Protection levelsetLevel(value)A value of 1 through 1000. The higher the number, thegreater degree of protection provided by the scheme.Default is 5.LibrarysetLibrary("smauthcert")The default library for this scheme type.ParametersetParameter(param)A string containing the domain or IP address of theserver responsible for establishing the SSL connectionand the name and path of the SSL Credentials Collector(SCC). The server redirects a user’s X.509 certificateover an SSL connection. Format:https://server/SCC?certThe following example uses the default SCC value:https://my.server.com/siteminderagent/cert/smgetcred.scc?certShared secretsetSecret("")Set to an empty string. Not applicable to this scheme.110 Developer's Guide for Java

Performance ConsiderationInformation TypeIs template?Value Assignment and MeaningsetIsTemplate(0)Set to false (0) to indicate that the scheme is not atemplate.Is used byadministrator?Save credentials?setIsUsedByAdmin(0)Set to false (0)—scheme is not used to authenticateadministrators.setAllowSaveCreds(0)Set to false (0) to indicate that user credentials won’tbe saved.Is RADIUS?setIsRadius(0)Set to false (0)—scheme is not used with RADIUSagents.Ignore passwordcheck?setIgnorePwCheck(1)Set to true (1)—ignore password checking.Performance ConsiderationThe following properties of the SmRealm object are set to true by default:■■PropProcessAuthEvents. When true, authentication event processingoccurs.PropProcessAzEvents. When true, authorization event processing occurs.Authentication and authorization event processing affect performance. If norules in the realm are triggered by authentication or authorization events, setthe associated property to false.Chapter 4: Policy Management API 111

Chapter 5: Authentication andAuthorization APIsThis section contains the following topics:Configuration of All Custom Classes (see page 113)Custom Classes for Authentication and Authorization (see page 114)Required Library File (see page 114)Shared Information (see page 115)Common Classes (see page 115)Create a Custom Authentication Scheme (see page 116)Use the Authorization API (see page 127)Configuration of All Custom ClassesThe following configuration information applies to all custom authenticationschemes and active expressions implemented with the Java Authentication APIand Java Authorization API:■■The library name is always smjavaapi.In the parameter field, the first item must be the name of the custom classyou implemented with the Authentication API or Authorization API, asfollows:■With authentication schemes, specify the name of the class youimplemented from the base interface SmAuthScheme. The class nameshould include the fully qualified package name, such as:com.myorg.sdk.myclass■With active policies, active rules, and active responses, specifythe name of the class you implemented from the base interfaceActiveExpression.Chapter 5: Authentication and Authorization APIs 113

Custom Classes for Authentication and Authorization■If any parameters are specified in the parameter field after the classname, the class name is separated from the parameters list by a spacecharacter.When SiteMinder calls the methods in an instance of your custom class, itpasses the specified parameters. The class name is not passed. Theparameters are passed as a single string. If the string contains multipleparameters, the parameters can be delimited in any way that the customclass requires.■■The class file specified in the parameter field must be referenced in theclasspath directive of the JVMOptions.txt configuration file. This file islocated in Netegrity/SiteMinder/Config within the SiteMinder installationpath.With active expressions, the function name (that is, the entry point for thesmjavaapi library file) is always JavaActiveExpression.Custom Classes for Authentication and AuthorizationThe basic steps for implementing and deploying custom authentication orauthorization classes are as follows:1. Implement the custom authentication or authorization class using theAuthentication or Authorization API and the common classes.2. Deploy the custom class or jar file on the Policy Server machine, andspecify its location in the classpath directive of the JVMOptions.txt file.This file is located in Netegrity/siteminder/config within the SiteMinderinstallation path.3. Configure the custom authentication or authorization functionality in thePolicy Server User Interface.Required Library FileAll custom authentication and authorization classes use the same library file—smjavaapi. This library file is included with the Policy Server. You do not haveto modify this library file. You simply reference it when you are configuringyour custom authentication or authorization class.114 Developer's Guide for Java

Shared InformationShared InformationCustom authentication and authorization objects may sometimes need tocommunicate request-specific information between themselves, such as topreserve state between object instances. These objects can share informationthrough AppSpecificContext, which is retrieved through ApiContext. ApiContextis one of the common classes that is passed to both authentication andauthorization objects.Information shared through AppSpecificContext has request-only scope. Forexample, a custom object running in the context of an authentication requestcannot exchange information with an object running in the context of anauthorization request.Common ClassesThe following classes are used by both the Authentication API and theAuthorization API. The services that these classes provide include:■■■Sending logging, tracing, and error messages to the Policy ServerProviding a mechanism for custom authentication and authorizationobjects to share informationMaking user context information available to authentication andauthorization objectsThe following table summarizes the common classes:ClassAPIContextAppSpecificContextSmJavaApiExceptionUserContextDescriptionAllows logging, tracing, and errormessages to be sent to the Policy Server.Provides methods that allow customauthentication and authorization objects toshare information.Provides exception functionality to customauthentication and authorization objects.Allows a custom object to set and retrieveinformation about a user in a userdirectory. The information includes userattributes and directory attributesassociated with the user.The methods for setting and retrievinguser directory attributes are available onlyif isUserContext() returns true.Chapter 5: Authentication and Authorization APIs 115

Create a Custom Authentication SchemeCreate a Custom Authentication SchemeAuthentication schemes provide a way to collect a user’s credentials anddetermine the user’s identity.The Policy Server includes a variety of standard authentication schemes. Theseschemes range from basic user name/password authentication and HTMLforms-based authentication to digital certificate and token authentication.If the standard authentication schemes included with the Policy Server do notprovide the kind of authentication functionality required at your site, you canuse the Java Authentication API to create a custom authentication scheme.Classes and Interfaces in the Authentication APISmAuthScheme MethodsThe base interface in the Java Authentication API is SmAuthScheme. Allcustom authentication schemes created with the Java Authentication API mustimplement this interface.SiteMinder calls the following methods in the base interface SmAuthScheme:Methodauthenticate()DescriptionPerforms the custom authentication and returns theauthentication result.SiteMinder calls this method at least twice—toestablish user context and to authenticate the user’scredentials.init()Performs any initialization procedures that theauthentication scheme requires. SiteMinder calls thismethod once for each authentication schemeinstance, when the authentication scheme is loaded.116 Developer's Guide for Java

Create a Custom Authentication SchemeMethodquery()DescriptionProvides SiteMinder with either of the following kindsof information, depending on the value SiteMinderpasses in the reason parameter (objectSmAuthQueryCode):The version and description of the authenticationscheme.The kind of credentials that SiteMinder should collectfrom the user, and optionally, the URL for the sitewhere credentials should be collected.release()Performs any rundown procedures that theauthentication scheme requires. SiteMinder calls thismethod once for each authentication schemeinstance, when SiteMinder is shutting down.Other Classes in the Authentication APIThe following classes are used in conjunction with the SmAuthScheme baseinterface:ClassSmAuthenticationContextDescriptionContains the following context classespassed to authenticate():APIContextUserContextUserCredentialsContextThe set... methods in this object passinformation directly to SiteMinder.SmAuthenticationResultContains status and reason codes returnedto SiteMinder after a call to authenticate().SmAuthQueryCodeContains the type of request thatSiteMinder is making of the authenticationscheme (version number and description,or information about the credentials thatSiteMinder must collect).SiteMinder passes this object to theauthentication scheme in query().Chapter 5: Authentication and Authorization APIs 117

Create a Custom Authentication SchemeClassSmAuthQueryResponseDescriptionContains constants that specify the kind ofcredentials that are required forauthentication, if any. Also allows a textmessage to be returned to SiteMinder fordisplay to the user.Optionally, the authentication scheme cancall setResponseBuffer() to specify a URLwhere credentials must be collected.The set... methods in this object passinformation directly to SiteMinder.SmAuthStatusContains Authentication API status codessuch as SMAUTH_ACCEPT andSMAUTH_REJECT.This object can be passed back toSiteMinder in SmAuthenticationResult. It isalso the return value type for theauthentication scheme’s init(), query(),and release() methods.UserCredentialsContextContains credentials information and otherinformation from the user directory whereuser context was established.This object is contained in theSmAuthenticationContext object passed toauthenticate().How SiteMinder Loads a Custom Authentication SchemeAn authentication scheme verifies the user credentials that SiteMinder passesto it and returns an authentication result.When user authentication is to occur against a custom authentication schemecreated with the Java API, SiteMinder loads the custom scheme by loading:■■The standard library file smjavaapi that is installed with the Policy ServerAn instance of the custom class implemented from SmAuthScheme118 Developer's Guide for Java

Create a Custom Authentication SchemeHow SiteMinder Initializes Authentication ProcessingImmediately after the scheme is loaded, SiteMinder calls the followingmethods in the custom class implemented from SmAuthScheme:■query(). SiteMinder passes SMAUTH_QUERY_DESCRIPTION in the requestparameter, requesting that the authentication scheme pass back theversion number and description of the Java Authentication API.Note: When SiteMinder passes SMAUTH_QUERY_CREDENTIALS_REQ inquery(), SiteMinder is requesting that the authentication scheme specifythe kind of credentials that are required. SiteMinder then collects thespecified credentials.■init(). SiteMinder passes the parameter string and shared secret that weredefined when the authentication scheme was configured in the PolicyServer. The scheme then performs any initialization procedures it requires.Chapter 5: Authentication and Authorization APIs 119

Create a Custom Authentication SchemeAuthentication of User CredentialsThe following figure shows the key activities that occur during authentication:120 Developer's Guide for Java

Create a Custom Authentication SchemeSupported CredentialsThe Java Authentication API supports authentication based on the followinggeneral types of credentials requirements:■■■Username/PasswordX.509 CertificateCustom user attributesYou specify the authentication credentials that are required through thesetResponseBuffer() method in the object SmAuthQueryResponse. This objectcontains a number of constants that indicate the specific credentials that arerequired or whether no credentials are required.User Disambiguation and AuthenticationThe authentication process includes two phases—user disambiguation and userauthentication.Before a user can be authenticated, the user’s profile information must beretrieved from the user store so that the user’s stored credentials can becompared with the credentials supplied at login. Looking up the user in a userstore (such as an LDAP user directory or an ODBC database) is called userdisambiguation. Either SiteMinder or the authentication scheme candisambiguate the user.SiteMinder calls SmAuthScheme.authenticate() at least once during thedisambiguation phase and at least once during the authentication phase:■■During disambiguation, it is called once per directory wheredisambiguation occurred.During authentication, it is called once per user found in the directory.Chapter 5: Authentication and Authorization APIs 121

Create a Custom Authentication SchemeUser DisambiguationThe basic steps are as follows:1. User login. The user supplies a login ID (such as jsmith) forauthentication purposes.2. Disambiguation phase. Before the user lookup in the data store canbegin, a complete DN or a search expression must be constructed basedupon the supplied login ID. For example, if the login ID is jsmith, the DNused to search the user store might be constructed as follows:uid=jsmith,ou=marketing,o=myorg.orgAn LDAP search expression can also be used to search an LDAP userdirectory, and a SQL query is used to search an ODBC database—forexample:(&(objectclass=inetOrgPerson)(uid=jsmith))select Name from SmUser where Name = 'jsmith'Multiple results are possible, given that the LDAP DN or the ID stored inthe ODBC database might apply to different users who have differentpasswords.3. Authentication phase. The custom authentication scheme compares theknown credentials of each disambiguated user with the credentialssupplied during login—for example, by comparing the hash of the suppliedpassword against the hash in the user store.SiteMinder first calls authenticate() at the beginning of the userdisambiguation phase.Either SiteMinder or the custom authentication scheme can disambiguate theuser. The authentication scheme indicates whether it has performed thedisambiguation through a combination of the following:■■One of the status codes listed belowWhether a value is passed to SiteMinder in the setUserText() method ofSmAuthenticationContext122 Developer's Guide for Java

Create a Custom Authentication SchemeThe status codes are set in the SmAuthStatus object. This object is passed inthe status parameter of the SmAuthenticationResult constructor.SmAuthenticationResult is returned from authenticate():■SMAUTH_NO_USER_CONTEXTThe authentication scheme asks SiteMinder to disambiguate the user.When returning this status code, the authentication scheme should alsoreturn an empty string through the setUserText() method. SiteMinder getsthe login ID from the Agent, constructs the DN or search expression basedon the login ID and the information defined in the SiteMinder UserDirectory Properties dialog box, and disambiguates the user by looking upthe user in the user store.■SMAUTH_SUCCESSThe authentication scheme asks SiteMinder to disambiguate the user.The authentication scheme passes the login ID to SiteMinder throughsetUserText(). SiteMinder uses that value to construct the DN or searchexpression and disambiguate the user in the user store. This approachgives the authentication scheme the opportunity to modify the login IDbefore SiteMinder disambiguates the user.Note: If the authentication scheme passes an empty string insetUserText(), SiteMinder uses the login ID provided by the Agent (thesame behavior as with return code SMAUTH_NO_USER_CONTEXT).■SMAUTH_SUCCESS_USER_DNThe authentication scheme disambiguates the user by constructing thecomplete DN or search expression and looking up the user in the userstore. The authentication scheme passes the user’s complete DN or ODBCdatabase ID to SiteMinder in setUserText(). Only one DN or database IDcan be passed in setUserText().■SMAUTH_ATTEMPT.The user cannot be found in the directory.■SMAUTH_FAILUREThis is returned if an error condition exists. Error text is returned toSiteMinder through the setUserText() method.Chapter 5: Authentication and Authorization APIs 123

Create a Custom Authentication SchemeUser AuthenticationDuring this phase, SiteMinder calls authenticate() again to allow theauthentication scheme to verify the supplied credentials after the user contexthas been established during disambiguation. The method sets one of thefollowing status codes:■■■■SMAUTH_ACCEPT. The user is authenticated.SMAUTH_REJECT. The user is not authenticated.SMAUTH_CHALLENGE. The user is challenged. The scheme passes thechallenge message to SiteMinder through the setUserText() method. Also,a reason code must be supplied in the SmAuthenticationResult objectreturned by authenticate().SMAUTH_FAILURE. An error condition occurred. Error text is passed toSiteMinder in setUserText().RedirectionYour authentication scheme can have the Policy Server instruct the agent toperform a redirect. To build redirection capabilities into your authenticationscheme:■Specify the redirection URL in:SmAuthenticationContext.setErrorText()■When creating an SmAuthenticationResult object to return fromauthenticate(), specify REASON_ERROR_MESSAGE_IS_REDIRECT in thereason parameter of the constructor.Authentication EventsAuthentication results are tied to SiteMinder events. If authentication eventsare enabled in the realm where the user is being authenticated, SiteMinderevaluates optional policies tied to OnAuthAccept, OnAuthReject,OnAuthAttempt, and OnAuthChallenge rules. You can configure these policiesto return custom responses based on a user’s identity, redirect the user toanother location based on the result of the authentication, or update the userdata in an external database.124 Developer's Guide for Java

Create a Custom Authentication SchemeExtend the SAML and WS-Federation Authentication SchemesThe SiteMinder SAML (1.x and 2.0) and WS-Federation authentication schemesprocess response messages. For business reasons, for example, you mightwant to add additional steps to further process a response. The MessageConsumer Extension API defines an interface that enables you to elaborate onthe SAML or WS-Federation response in two ways during the authenticationprocess:■■To report detailed failure reasons during user disambiguationTo customize user credential validationThe SiteMinder Java MessageConsumerPlugin API implements the MessageConsumer Extension (MCE) interface. You can code to your own requirementsand then integrate the custom plug-in into SiteMinder.The MessageConsumerPlugin includes the following four methods:Methodinit()release()DescriptionPerforms any initialization procedures that the plug-inrequires. SiteMinder calls this method once for eachplug-in instance, when the plug-in is loaded.Performs any rundown procedures that the plug-inrequires. SiteMinder calls this method once for eachplug-in instance, when SiteMinder is shutting down.Provides processing to disambiguate a user when theauthentication scheme is unable to do so, or to adddata for new federation users to a user store.postDisambiguateUser()postAuthenticateUser()Provides any additional code to determine the finaloutcome of assertion processing, regardless ofwhether the policy server processing results insuccess or failure.SiteMinder provides the following samples of the Message Consumer plug-inclass:■■MessageConsumerPluginSample.java in \sdk\samples\messageconsumerpluginMessageConsumerSAML20.java in \sdk\samples\authextensionsaml20Chapter 5: Authentication and Authorization APIs 125

Create a Custom Authentication SchemeThe Role of the MessageConsumerPluginThe following list describes the MessageConsumerPlugin in an elaboratedprocess of user authentication:1. The Federation Web Services (FWS) application forwards a request foruser authentication to the Policy Server.2. The Policy Server invokes the authentication scheme to disambiguate theuser.3. The authentication scheme disambiguates the user as follows:a. The authentication scheme metadata is obtained from the Policy store.b. The authentication scheme attempts to obtain the LoginID. If LoginIDis not found, the authentication scheme invokes theMessageConsumerPlugin as described in Step 4.c. If the LoginID is obtained successfully, the authentication schemesearches the current user directory with a predefined SearchSpec. Ifthe user is not found, the postDisambiguate() method is called asdescribed in Step 4. If the user is found, the Policy Server proceedswith credential validation, as described in Step 6 and following.d. When the authentication scheme does not provide the user storeSearchSpec, the Policy Server core searches for the user with thesearch string defined with the User Directory object. TheMessageConsumerPlugin is not called.4. The postDisambiguateUser() method searches a user directory todetermine whether a particular LoginID exists. The result is returned tothe authentication scheme. The method might be called several times ifmore than one user directory is configured. This method can also be usedto add data for new federation users from the assertion to a user store.5. When the user has been successfully disambiguated by the Policy Server,the authentication scheme, or the plug-in, the Policy Server returns theuser DN to the Policy Server and proceeds to credential validation (Step 8and following).6. If the user has not been successfuly disambiguated for this user directoryby either the Policy Server, the authentication scheme, orMessageConsumerPlugin, the FWS application checks the next userdirectory and repeats Steps 2 - 6 before proceeding with credentialvalidation.7. When a user has been disambiguated, the Policy Server again calls theauthentication scheme to determine whether the user has the propercredentials for the authentication request. The authentication schemedetermines whether the response message is acceptable.126 Developer's Guide for Java

Use the Authorization API8. After the the authentication scheme has attempted to authenticate thedisambiguated user with the response message, the Policy Server calls thepostAuthenticateUser() method from the MessageConsumerPlugin. ThePolicy Server always calls this method when a user is disambiguated, evenwhen the Policy Server core performs the user disambiguation.9. You can use postAuthenticateUser() to add any other procedures forfederation credential validation required by your implementation.10. The final result is passed back to the Policy Server by the authenticaitonscheme.11. If necessary, the FWS application can process any failure and redirect theuser to an appropriate URL.Use the Authorization APIThe Java Authorization API lets you implement custom functionality forcontrolling access to protected resources.The functionality is provided through custom Java classes that are referencedin Policy Server active expressions. An active expression is a string of variabledefinitions that appears in the following Policy Server objects:■Active policy—A policy that provides dynamic authorization based onexternal business logic.For example, you might implement a custom Java class that returns true ifthe user belongs to a particular organizational unit (ou) in an LDAPdirectory. The ou is passed to the custom Java class in the parameter(param) field of the active expression.■Active response—A response returned from a custom Java class. Using anactive response is one way you can define user-specific privilegeinformation.For example, you might define an active response that returns a user’scommon name (cn) if the user belongs to the ou passed in the param fieldof the active expression.■Active rule—A rule that provides dynamic authorization based on externalbusiness logic.For example, you might define a custom Java class that returns true if auser is a member of a group, such as Directory Administrator, that haspermission to view a realm. The group name is passed to the Java class inthe param field of the active expression.Chapter 5: Authentication and Authorization APIs 127

Use the Authorization APIActive ExpressionsActive expressions are constructed in the Policy Server User Interface usingthe following syntax:An active expression based on the Java Authorization API has the followingrequired fields:■■■lib contains the shared library name smjavaapi. This library is used with allactive expressions that reference a custom Java class in param.func contains the function name JavaActiveExpression. This function is theentry point for the smjavaapi library. It is used with all active expressionsthat reference a custom Java class in param.param contains the following information.■■The name of your custom Java classOptionally, any parameters to pass to an instance of your classExecute an Active ExpressionYou define an active expression when you configure the active policy, rule, orresponse in the Policy Server User Interface.When SiteMinder detects an active expression that references a custom Javaclass, it performs the following tasks:■■■Loads the shared library and instance of the custom Java class specified inthe active expression.Calls the library function specified in the active expression.Passes to the instance of the custom Java class the optional parameterstring plus the following context objects:■■APIContextRequestContext■■UserContextThe instance of the Java class performs the custom functionality andreturns a result to SiteMinder. Results are returned from the custom Javaclass’s invoke() method.128 Developer's Guide for Java

Use the Authorization APIInterpret an Active Expression ResultSiteMinder interprets the result returned by the instance of the custom Javaclass according to the type of active expression that references the Java class,as follows:■Active Policy—If the result returned is an empty string or if an exception isthrown, authorization is denied.The policy does not fire if the result returned matches any of the followingstrings (not case-sensitive): FALSE, F, or 0.Any other result causes the policy to fire.■Active Rule—If the result returned is an empty string or if an exception isthrown, the following behavior occurs:■■With Allow Access rules, the rule does not fire.With Deny Access rules, the rule fires.Otherwise, the behavior is the same as for Active Policies.■Active Response—The result is a string that corresponds to a responseattribute. How SiteMinder interprets the result string is determined bythe response attribute specified in the Policy Server User Interface.For example:■WebAgent-OnReject-Redirect. Given this response attribute,SiteMinder expects the result string to specify a location, such as aURL, to redirect a user who is denied access to a resource.(The URL that is passed back might vary according to informationpassed into the custom Java class. For example, a group name couldbe passed in the param field of the active expression. The custom Javaclass could then test for the group name to determine the URL to passback.)■WebAgent-HTTP-Cookie-Variable. Given this response attribute,SiteMinder expects that the result string, such as the user’s commonname, is to be assigned to a cookie variable. You can use the resultstring any way you like, such as to display the user’s common name topersonalize a form.You specify the cookie name in the SiteMinder Response AttributeEditor.If the method fails (that is, the method returns -1 or 0), the responseattribute is ignored.Chapter 5: Authentication and Authorization APIs 129

Use the Authorization APIClasses and Interfaces in the Authorization APIActiveExpression MethodsThe base interface in the Java Authorization API is ActiveExpression. All Javaclasses that provide custom authorization functionality must implement thisinterface.The name of the class that you implement from the base interface mustappear in the param field of any associated active expression.The base interface in the Java Authorization API is ActiveExpression. All Javaclasses that provide custom authorization functionality must implement thisinterface.The name of the class that you implement from the base interface mustappear in the param field of any associated active expression.SiteMinder calls the following methods in the base interface ActiveExpression:Methodinit()invoke()release()DescriptionPerforms any initialization procedures that the custom Javaclass requires. SiteMinder calls this method once perinstance of the custom ActiveExpression class.Performs the custom authorization functionality in theActiveExpression object and returns a result.Performs any rundown procedures that the ActiveExpressionobject requires. SiteMinder calls this method once for eachinstance of an ActiveExpression class, when SiteMinder isshutting down.Note: Classes that implement ActiveExpression should be implemented on astateless model that does not depend on instance state stored in membervariables of the ActiveExpression class.130 Developer's Guide for Java

Use the Authorization APIOther Classes in the Authorization APIThe following classes in the Authorization API are used in conjunction with theActiveExpression base interface:ClassActiveExpressionContextDescriptionContains the following context classespassed to invoke():• APIContext• RequestContextRequestContext• UserContextProvides information about the user’saccess request—for example, the server orresource portion of the request.Custom Authentication Scheme ConfigurationThe following diagram is an example of an authentication schemeconfiguration defined on the SiteMinder Authentication Scheme Dialog. TheAuthentication Scheme Type is Custom Template:Chapter 5: Authentication and Authorization APIs 131

Use the Authorization APITo configure a custom authentication scheme on the SiteMinder AuthenticationScheme Dialog, access the dialog box, click the Advanced tab, and selectCustom Template as the Authentication Scheme Type.Active Policy ConfigurationThe following diagram is an example of an active policy configuration definedin the SiteMinder Active Policy Editor:132 Developer's Guide for Java

Use the Authorization APIActive Rule ConfigurationThe following diagram is an example of an active rule configuration defined inthe SiteMinder Active Rule Editor:To access the editor from the Rule Properties dialog box, select the Active Ruletab in the Advanced group box, then click Edit.Chapter 5: Authentication and Authorization APIs 133

Use the Authorization APIActive Response ConfigurationThe following diagram is an example of an active response configurationdefined in the SiteMinder Response Attribute Editor. In the example, the activeresponse is associated with a WebAgent-HTTP-Cookie-Variable attribute:From the Response Properties dialog box, access the editor by clicking Create.Then, in the Attribute Setup tab, select the Active Response button in theAttribute Kind group box.Modify a SAML Assertion or ResponseAccording to SAML specifications, an assertion (SAML 1.x) or response (SAML2.0) is generated by a producer site and sent to a consumer site for validation.Typically, you will use the default SAML assertion or response that SiteMindergenerates at the producer site. If you want to modify the content of theassertion or the reponse, you can do so by implementing the Java assertiongenerator plug-in. This plug-in is appropriate for both consumers (SAML 1.x)and Service Providers (SAML 2.0).134 Developer's Guide for Java

Use the Authorization APITo modify the SAML assertion or response1. Implement a Java SAML assertion generator plug-in.The implementation is a plug-in for the SiteMinder Assertion GeneratorFramework. The Assertion Generator Framework sends a default token tothe custom plug-in object. After processing, the custom object passes amodified token to the Assertion Generator Framework.2. Configure the plug-in by specifying the fully-qualified name of the plug-inclass and any optional parameters that the plug-in might require.You configure a custom assertion generator plug-in in any of these ways:■■■For SAML 1.x support, on the Advanced tab of the SiteMinder AffiliateProperties dialog. For information, see CA eTrust Policy Design.For SAML 2.0 support, on the Advanced tab of the SiteMinder ServiceProvider Properties dialog. For information, see CA eTrust PolicyDesign.Through the C or Perl Policy Management API. For information, see theCA eTrust SiteMinder Developer’s Guide for C or the CA eTrustSiteMinder Scripting Guide for Perl.Note: Configuration of the assertion generator plug-in requires a PolicyManagement API session version of at least v6.0 SP 2.Interaction between SiteMinder and an Assertion GeneratorThe following steps outline the interaction between SiteMinder and a customassertion generator plug-in. The activities begin when an authorized usermakes a request, through a SiteMinder Policy Server, for a resource at a sitethat consumes assertions:1. An authorized user requires a SAML assertion or response for a consumeror Service Provider.2. The SiteMinder Assertion Generator Framework generates a default SAMLassertion or response.3. If an assertion generator plug-in is defined for the site that consumes theassertion, the SiteMinder Assertion Generator Framework requests aninstance of the plug-in object from the plug-in cache.Note: The site consuming assertions can have no more than oneassertion generator plug-in defined for it.Chapter 5: Authentication and Authorization APIs 135

Use the Authorization APIDevelopment and Deployment Notes4. If the plug-in has not yet been loaded into cache:a. SiteMinder instantiates the plug-in class and loads it into cache.b. SiteMinder calls the plug-in’s init() method. This method performs anyinitialization procedures that you have implemented for the plug-in.A successfully initialized plug-in object remains in cache until SiteMindershuts down. This avoids having to re-load and re-initialize the object everytime the plug-in is required.5. The SiteMinder Assertion Generator Framework passes the default XMLtoken, generated in step 2, to the plug-in’s customizeAssertion() method.6. The plug-in validates or modifies the information as required, and returnsthe processed assertion to the Assertion Generator Framework.7. The Assertion Generator Framework passes the processed token to theconsumer or Service Provider. This site uses the information in theassertion to determine how to respond to the user’s request.8. Steps through are repeated whenever a user requires an assertion forthe service provider.When SiteMinder is about to shut down, SiteMinder calls the plug-in’s release()method to allow the plug-in to perform any rundown activities it might require.When developing and deploying a custom assertion generator plug-in, keepthe following points in mind:■■■■The implemented plug-in class must provide a public default constructormethod with no parameters.The implementation must be stateless—that is, the single plug-in instancecan be concurrently used for multiple threads.The syntax requirements and use of the parameter string that is passedinto the customizeAssertion() method is the responsibility of the customobject.The custom object must parse the default assertion that is passed tocustomizeAssertion()—for example, through a Document Object Module(DOM) parser or a Simple API for XML (SAX) parser. The sample plug-inclass AssertionSample.java uses a DOM parser.136 Developer's Guide for Java

Use the Authorization API■■To enable SiteMinder to locate your deployed plug-in class, specify thedeployment location in -Djava.class.path of the configuration fileJVMOptions.txt. This file is in the following location of the SiteMinderinstalled directory structure: \siteminder\config.For a sample of an assertion plug-in class, see AssertionSample.java,which demonstrates the plug-in process for a SAML 1.x assertion, in thefollowing location of the SiteMinder installed directory structure: \sdk\samples\assertiongeneratorplugin.In the same directory thereare samples for the Assertion Generator Plugin for SAML 2.0,SAML2AppAttrPlugin.java, and WS-Federation, WSFedAppAttrPlugin.java.Chapter 5: Authentication and Authorization APIs 137

Chapter 6: Delegated ManagementServices APIThis section contains the following topics:About the DMS API (see page 139)The Required JAR File (see page 140)SiteMinder User Directories (see page 140)Attribute-based Delegation (see page 142)DMS Users (see page 143)Implementation Class (see page 144)Context Class (see page 144)Object Class (see page 145)Search Class (see page 146)Cursor Class (see page 146)Write a Directory Management Application (see page 148)Searches (see page 157)User Password State (see page 164)ODBC Support (see page 165)Restricted Methods (see page 166)About the DMS APIDirectory management consists of managing objects within a SiteMinder userdirectory. For example, a user of your directory management application cancreate organizations, add groups to organizations, and add end users togroups. Your application performs directory management operations with theDMS API.The Delegated Management Services (DMS) API lets you perform directorymanagement operations on LDAP and ODBC directories.With LDAP directories, you can use the DMS API to write a client applicationthat allows a user with the specified privileges to perform tasks such as (butnot limited to):■■■Creating an organizationCreating a groupAdding a group to an organizationChapter 6: Delegated Management Services API 139

The Required JAR File■■Adding a user to a groupModifying the profile of a userWith ODBC directories, you can perform many but not all DMS API operations.Note: The DMS API (available in Java only) has different functionality thanthe DMS Workflow API (available in C/C++ only). The DMS API lets youdevelop directory management applications that perform similar operations asthe SiteMinder DMS product. The DMS Workflow API works in conjunction withDMS and fires when certain pre-process and post-process DMS events occur,allowing you to develop applications that perform additional functionalitybefore and/or after these events.The Required JAR FileThe JAR file smjavasdk2.jar is required for building and running DelegatedManagement applications. The JAR file is stored in the following locations:■Windows platforms:\sdk\java■UNIX platforms:/sdk/javaSiteMinder User DirectoriesA SiteMinder user directory is a conceptual view of a single organizational unit(such as Engineering or Human Resources) within a larger entity (such as acorporation). SiteMinder user directories make managing an entire directorystructure easier by breaking up the directory into smaller, more manageable,and logically related segments.The methods in your custom DMS application reference a particular SiteMinderuser directory by specifying its unique organization DN. The organization DNpoints to the root, or top level, of the SiteMinder user directory’s inverted treestructure or to one of its sub-levels.140 Developer's Guide for Java

SiteMinder User DirectoriesEvery DMS request references an organization DN. In the following illustration,two SiteMinder user directories are enclosed in broken-line boxes. Thedirectories are identified by the organization DNs ou=eng, o=swdev.com(representing the Engineering organizational unit) and ou=hr, o=swdev.com(representing the Human Resources organizational unit):SiteMinder user directories can exist within other SiteMinder user directories.In the preceding illustration, the Engineering organizational unit has threeSiteMinder user directories within it. These have the attribute and organizationnames ou=dev, ou=qa, and ou=doc. The Human Resources organizational unithas two SiteMinder user directories within it—ou=benefits and ou=recruit.SiteMinder User Directory ContainersAn organization DN in a SiteMinder user directory typically has one or moresub DNs. Sub DNs are also called "containers" because they contain lists ofinformation. The default names of these containers and the information theycontain are:■■■■people—End users in the Siteminder user directory.roles—Roles used in the SiteMinder user directory.groups—Groups used in the SiteMinder user directory.orgadmin—Group for administrators who can manage the organizationalunit.Sub DNs are managed by the class SmDmsConfig. When you create anSmDmsConfig object, you can keep the default sub DN names or assignnew ones.Organization administrators are listed in the orgadmin container. In ahierarchical organization, an organization administrator listed in a givenorgadmin container can manage the organizational unit associated with thatcontainer and any organizational units below it.Chapter 6: Delegated Management Services API 141

Attribute-based DelegationAttribute-based DelegationIn addition to hierarchical organization, DMS also provides an administrationmodel for sites that have implemented a flat directory structure. In this model,delegation is based on attributes in user profiles instead of hierarchical levels.In a flat directory, DMS adds attribute/value pairs to user profiles to groupusers together. Once users are grouped together, another attribute/value pairdetermines which users can manage the groups.DMS groups users into organizations by adding an attribute/value pair to userprofiles. For example, users who belong to the organization East Bank havethe attribute/value pair ou=East Bank in their profiles, where ou is theattribute that indicates the organization to which a user belongs.An organization administrator can only manage organizations that are listed inthe organization administrator’s profile. The list of organizations is assigned toa profile attribute that you specify in the SmDmsConfig constructor. Forexample, if you specify departmentnumber as the attribute that contains theorganizations that an organization administrator can manage, theattribute/value pair departmentnumber=East Bank means that theorganization administrator can manage the East Bank organization and noothers.The following illustration describes how attribute-based delegation isimplemented:In this example, Donna Gibson is an organization administrator for East Bankand North Bank. She can manage Edward Johnson and Carrie Winham becausethey belong to organizations that are listed in the departmentnumber attributein Donna’s user profile.142 Developer's Guide for Java

DMS UsersConfigure Attribute-based DelegationYou specify the attributes that enable attribute-based delegation in theSmDmsConfig constructor. Three attributes are required to identify thefollowing information:■A user as an organization administrator. This attribute can be any attributein your LDAP directory that you are not using to store other information—for example, o.You specify a user as an organization administrator through theconstructor’s OrgAdminSubDn parameter, as in the following example:OrgAdminSubDn="(title=OrgAdmin)";■The organization(s) that an organization administrator can manage. Bydefault, DMS uses the departmentnumber attribute to store managedorganizations.You specify this attribute through the constructor’s OrgAdminOrgsparameter—for example:OrgAdminOrgs="departmentnumber";■The organization to which a user belongs. By default, DMS uses the ouattribute.You specify this attribute through the constructor’s DnOrgs parameter—forexample:DnOrgs="ou";DMS UsersDMS users are assigned one of the following categories of directorymanagement privileges. The categories are listed below from lowest tohighest:■■End user—Can manage certain information about the end user’s ownaccount, such as changing the user’s password and viewing (but notadding) the roles that the user is a member of.Organization administrator—Can manage an entire organization and anyorganizations below it.Chapter 6: Delegated Management Services API 143

Implementation Class■SiteMinder administrator—Can manage directories in one or moredomains.SiteMinder administrator privileges can vary. With DMS, SiteMinderadministrators must have system-level Manage User privileges, and theymust be present in at least one domain.■Super administrator—Can manage all directories in all domains.You use different login() methods to log in different categories of DMS users.Implementation ClassInterface SmDmsApi is implemented by the class SmDmsApiImpl. Use thisclass as the starting point for the DMS API.This class lets you determine how you want to access the information in theSmDmsDirectory object. You can do so by providing either of two kinds ofinformation:■■The name or OID of the target user directory. To provide this information,call getDirectoryContext().The OID of the protected realm that the user is attempting to access. Toprovide this information, call getDmsContext().These methods fill the context object that is passed into them.Context ClassThe getDirectoryContext() and getDmsContext() methods in classSmDmsApiImpl create a context object—either SmDmsDirectoryContextor SmDmsContext. The context object contains information such as userdirectory, session, and connection information. The context object is so-namedbecause its information is derived within the context of the provided realm OIDor the user directory name or OID. When you have a context object, you callits getDmsDirectory() method to retrieve an SmDmsDirectory object. Thisobject represents an LDAP or other namespace and gives you access toorganizations and other elements in the namespace.144 Developer's Guide for Java

Object ClassObject ClassThe Object class, SmDmsObject, and its subclasses provide methods forcreating and managing directory objects. SmDmsObject and its subclasses areshown below:SmDmsDirectory represents a user namespace, such as LDAP. It providesaccess to the information in an entire directory.SmDmsOrganization represents an organization, such as Engineering orHuman Resources, within a directory. A SiteMinder user directory is aconceptual view of an organization. It is managed by an organizationadministrator and uniquely identified by an organization DN.SmDmsGroup represents a group within an organization. Groups are sets ofobjects that have something in common—for example, a group of employeeswho have been with the company for less than a year. With group objects,users can be assigned privileges collectively instead of individually.SmDmsRole represents a role within an organization. A role describes a user’sfunction in an organization. This allows the user to be managed with otherusers who have the same privileges. For example, a user who can order itemsonline and view an inventory list may have the role buyer.SmDMSUser represents a user within an organization. Users can be end usersor administrators.Object ModelWhen performing an operation on a directory, organization, group, role, oruser object, you sometimes have a choice of using the generic SmDmsObjector one of its subclasses. However, for object-specific operations (such asauthenticating a user, changing a user’s password, or getting a user’sprivileges), you have to use an object-specific subclass.Chapter 6: Delegated Management Services API 145

Search ClassThe objects corresponding to the subclasses are distinguished by a classidentifier, such as DMSOBJECT_CLASS_USER for a user object. Theseidentifiers are defined in SmDmsObject. When you create an object using asubclass, such as creating a user with SmDmsUser, and then you calladdObject(), the class identifier is automatically set. However, if you create ageneric directory, organization, group, role, or user object with SmDmsObject,you must set the class identifier before calling addObject().Search ClassThe Search class, SmDmsSearch, represents a configuration object for thesearch operation. It holds the search base and the filter. The filter expects astring-based search expression for the object class.The search class returns a list of distinguished names paired with thecorresponding class identifier, and optionally, selected attribute information forthe items retrieved in the search.Cursor ClassThe SmDmsCursor class lets you define sorting and paging behavior for resultset operations—for example:■■■Set the sort parameter of the SmDmsCursor constructor to specify thecolumns to use for sorting rows.Call setBlockSize() to define the maximum number of rows that can bereturned from a result set at one time—that is, the maximum number ofrows in a page.Call setOffset() to specify the starting offset (row number) of the blockreturned from the result set.146 Developer's Guide for Java

Cursor Class■Call isSortingCritical() to specify whether a result set must be sorted.■If you specify true, a result set will be retrieved only if it can besorted.■■If you specify false, an unsorted result set will be sent if it cannot besorted. An isSorted() call on the same SmDmsCursor object will returnfalse.Call isPagingCritical() to specify whether a result set must be paginated.■■If you specify true, a result set will be retrieved only if it can bepaginated.If you specify false, a complete result set will be sent if it cannot besorted. An isPaginated() call on the same SmDmsCursor object willreturn false.Searches that Support Cursor OperationsYou can perform sorting and paging operations by passing a definedSmDmsCursor object into any of the following methods:■One of the search methods in SmDmsOrganization:■■■search()searchForward()searchBack()■■■■ searchRefresh()SmDmsObject.getGroups()SmDmsOrganization.getGroups()SmDmsGroups.getMembers()Note: getGroups() and getMembers() are not supported in searches of ODBCdirectories.Searches of Microsoft LDAP DirectoriesSorting and paging operations are not supported for Active Directories throughthe AD namespace. Sorting and paging operations are supported for ActiveDirectories through the LDAP namespace.Chapter 6: Delegated Management Services API 147

Write a Directory Management ApplicationWhen communicating with an Active Directory through the AD namespace,SiteMinder responds to sorting and paging requests as follows:■■If both isPagingCritical() and isSortingCritical() return false in theSmDmsCursor object, the result set is returned. No sorting and pagingoperations are performed.If either isPagingCritical() or isSortingCritical() returns true in theSmDmsCursor object, an error occurs. No result set is returned.You specify whether sorting and paging operations are critical in theSmDmsCursor constructor.Write a Directory Management ApplicationTo write a Directory Management application1. Establish a Connection to the Policy Server2. Obtain a Session ObjectA session object is obtained when a user or administrator successfully logsin:■To log in a SiteMinder administrator and establish a SiteMinderadministrator session, call the login() method in the SmApiSessionclass of the Utilities package.If login is successful, the session object contains the sessionspecification.■To log in an end user, DMS organization administrator, or DMS superadministrator, call the login() method in the AgentAPI class of theAgent API package.If the login is successful, the session specification is put into the specfield of the SessionDef object. Set the spec value in the SmApiSessionobject.148 Developer's Guide for Java

Write a Directory Management Application3. Pass in the Session ObjectAfter obtaining a valid session, create a DMS API object by passing thesession to the constructor of the SmDmsApiImpl class—for example:SmDmsApi dmsApi = new SmDmsApiImpl (apiSession);In the example, dmsApi is the new DMS API object, and apiSession is thesession obtained when the administrator successfully logged in.Note: Whenever you create a DMS API object, you pass the session andconnection information to the object.4. Create a Directory Management ContextTo use the DMS API to access a user directory, you need to know either:■The OID of a realm that has a self-registration scheme configured forit.Call SmDmsApiImpl.getDmsContext() to pass in this information.■The SiteMinder user directory where you are operating.Call SmDmsApiImpl.getDirectoryContext() to pass in this information.The type of information you know or choose to provide determines thedirectory management context for accessing the user directory, as follows:If You Know... And... Then Use...The OID of a realmthat contains a selfregistrationschemeThe user is aSiteMinderadministratorDelegated ManagementServices (DMS) contextThe SiteMinder userdirectory name or OID— Directory contextDMS context and directory context provide two different avenues forreaching the same destination—an SmDmsDirectory object where you canaccess and manipulate directory information.The following figure illustrates the process flow of the DMS API through acontext object:Chapter 6: Delegated Management Services API 149

Write a Directory Management ApplicationOnce you choose the context information you want to provide, you createthe context.5. Create and Manipulate ObjectsAfter creating a context, you can create and manipulate directory objectsusing the DMS Object Model. When working with directory objects, youneed to know:■■The distinguished name of the object.The type of object, such as:■■■■■Top-level organizationOrganizational unitGroupUserRoleDMS ContextDMS context lets you access an SmDmsDirectory object within the context of arealm OID that you provide. The DMS context class is SmDmsContext.You can create a DMS context object as follows:SmDmsContext dmsContext = new SmDmsContext();You can retrieve a DMS context object, use the method getDmsContext() inthe class SmDmsApiImpl.Note: SiteMinder administrator privileges are required for callinggetDmsContext().Before retrieving the DMS context object information, you need to create arealm object to pass into the getDmsContext() call. The realm object must:■■Have a valid object identifier (OID) obtained from an agent call toAgentAPI.isProtected().Be configured with a registration scheme.150 Developer's Guide for Java

Write a Directory Management ApplicationYou create the SmRealm object as follows:SmRealm realm = new SmRealm();Then, set the realm OID by calling setOid(). You can call this method throughan object that extends the SmObjectImpl class of the Policy Management API.After setting the OID for the realm object, call getDmsContext() and pass inthe realm object.Example:An agent calls isProtected() to determine if the resource that a user isattempting to access is protected. The Policy Server indicates that theresource is protected by returning the credentials required for accessing theresource. Included with the return information is the OID of the protectedrealm. As shown in the example below, you use the returned realm OID (inthe example, m_REALM_OID) to set the OID for the realm object you arecreating and passing to getDmsContext():// Create a DMS API object from a valid session.SmDmsApi dmsApi = new SmDmsApiImpl (apiSession);// The realm below should contain a registration scheme.// You can get a directory OID from the registration scheme.SmRealm realm = new SmRealm ();realm.setOid (m_REALM_OID);// Create the DMS context object.SmDmsContext dmsContext = new SmDmsContext ();// This call returns the realm, self registration,// and user directory information through dmsContext.result = dmsApi.getDmsContext (realm,new SmDmsConfig(),dmsContext);To get complete directory information from the dmsContext object, calldmsContext.getDmsDirectory().To get just the directory OID, call dmsContext.getSelfReg(), and then callSmSelfReg.getUserDir().Chapter 6: Delegated Management Services API 151

Write a Directory Management ApplicationDirectory ContextDirectory context lets you access an SmDmsDirectory object within the contextof a user directory name or OID that you provide. The directory context classis SmDmsDirectoryContext. To get a directory context, use the methodgetDirectoryContext() in the class SmDmsApiImpl.In the following example, an SmDmsDirectoryContext object is returned indirContext. Call getDmsDirectory() to get the information about the directoryobject.// Create a DMS API object from a valid session.SmDmsApi dmsApi = new SmDmsApiImpl (apiSession);// Create the directory context object.SmDmsDirectoryContext dirContext=new SmDmsDirectoryContext();// Directory object to pass in to getDirectoryContext().SmUserDirectory userDir = new SmUserDirectory ();// setOid() method can take the name of the user directory.userDir.setOid ("smdev");// This call returns directory information through dirContext.result=dmsApi.getDirectoryContext(userDir,new SmDmsConfig(),dirContext);Change the User Type in DMS ContextIn a directory context, you can perform operations on behalf of any usertype—super administrator, SiteMinder administrator, organizationadministrator, or end user. But to create a DMS context object, you must callthe method getDmsContext(), and SiteMinder administrator privileges arerequired to call this method.After getDmsContext() is called and DMS context is established for thesession, it’s possible to change the user type for subsequent operations in thesession. For example, after a SiteMinder administrator opens a session in DMScontext, you might want an end user to modify his user profile later in thesame session. To make the profile request on the end user’s behalf rather thanthe SiteMinder administrator’s, you need to change the user type.152 Developer's Guide for Java

Write a Directory Management ApplicationTo create a DMS context object, you call SmDmsApiImpl.getDmsContext().When you do so, connection information and the SiteMinder administrator’ssession specification are included the DMS context object.As a chain of subsequent objects is created in the session (for example,SmDmsDirectory/SmDmsOrganization/SmDmsUser), the connection andsession information is passed from object to object. To change the user typefor a given object, you replace the SiteMinder administrator’s sessionspecification for that object with the session specification for the new user typeon whose behalf subsequent calls will be made. You can change the sessionspecification at any object level.To change the user type for an object created in DMS context1. Create the object that will be the target of requests by the new user type.For example, to make requests against the new user object dmsUser inorganization dmsOrg on behalf of an end user with the distinguished nameUSER_DN:SmDmsUser dmsUser = dmsOrg.newUser(USER_DN);In the example, the SiteMinder administrator session specification in thedmsOrg object is passed to the dmsUser object.2. Get a session specification for the new user in either of these ways:■■With standard SiteMinder agents, use the default HTTP headerHTTP_SM_SERVERSESSIONSPEC.With custom agents, use the Agent API to log in the new user.3. Pass in the session specification for the new user and DMS object. Forexample, if sessionSpec is the session specification:dmsUser.getApiSession().setSessionSpec(sessionSpec);More Information:Context Class (see page 144)Chapter 6: Delegated Management Services API 153

Write a Directory Management ApplicationCreate an ObjectTo create an object, such as an organization object, a group object, a userobject, or a role object:1. Use the context to get a directory object by calling getDmsDirectory() on aDMS context or directory context. For example, using a DMS context:SmDmsDirectory dmsDir = dmsContext.getDmsDirectory();2. Use the directory object to create an organization object by callingnewOrganization() in class SmDmsDirectory. Pass in the distinguishedname of the organization, such as o=swdev.com. For example:SmDmsOrganization org=dmsDir.newOrganization("o=swdev.com");3. Use the organization object to create other objects, such as group objectsor organizational unit objects. The following example creates a groupobject named grp with the distinguished name ou=UI,ou=eng,o=swdev.com.SmDmsGroup grp=org.newGroup("ou=UI,ou=eng,o=swdev.com");Note: This code does not add the group to the directory.The following figure illustrates the DMS API flow for creating directory objects:Get Directory Entry AttributesTo retrieve a value for a specific attribute, call getAttribute() in classSmDmsObject and pass in the attribute name as a string. Attribute values areavailable after you fetch the attributes with getObject(). The methodgetAttribute() returns a member of the java.lang.Object class. If the attributeis multi-valued, the returned object will contain multiple values delimited by acaret (^).154 Developer's Guide for Java

Write a Directory Management ApplicationAdd an Object to a DirectoryTo add an object to a directory:1. Set the attributes for the object by calling setAttribute() in classSmDmsObject and passing to it the attribute name and its value. Attributenames are defined in your directory system.Call setAttribute() as many times as necessary to define the object.2. Call the method addObject() in class SmDmsObject. For example:result = grp.addObject();In the example, result is an SmApiResult object.Note: If you want to call addObject() on a (generic) SmDmsObjectobject, you must first call setClassId() to set the class identifier.When adding an object, you can set multiple values for the objectclassattribute, but not for other attributes. When modifying an object with themodifyObject() method, you can set multiple values for any attribute.To set multiple values for an attribute, you can either:■■Pass in a string, using a caret (^) to delimit the values.Pass in a vector of values and have SiteMinder convert the vector to astring.For example, to pass in a string containing the values top andorganizationalunit, you could use the following code:group.setAttribute("objectclass","top^organizationalunit");To pass in a vector for the same values, you could use the following code:Vector objectclass = new Vector();objectclass.add("top");objectclass.add("organizationalunit");group.setAttribute("objectclass", objectclass);Note: For existing objects, object class can be modified through themodifyObjectClass() method. This method also allows you to set multiplevalues for object class.Chapter 6: Delegated Management Services API 155

Write a Directory Management ApplicationAdd a User to a GroupTo add a user to a group, call the addToGroup() method in classSmDmsObject. In the following example, the user user1 is added to the groupdevGroup:SmDmsDirectory dmsDir = dmsContext.getDmsDirectory();SmDmsOrganization org = dmsDir.newOrganization(ORG_ROOT);SmDmsGroup devGroup = org.newGroup(GROUP_DN);SmDmsUser user1 = org.newUser(USER_DN1);result = devGroup.addToGroup(user1);Add a User to a RoleTo add a user to a role, call the addToRole() method (class SmDmsUser). Inthe following example, the user user1 is added to the role role:SmDmsDirectory dmsDir = dmsContext.getDmsDirectory();SmDmsOrganization org = dmsDir.newOrganization(ORG_ROOT);SmDmsRole role = org.newRole(ROLE_DN);SmDmsUser user1 = org.newUser(USER_DN1);result = user1.addToRole(role);Get, Modify, or Delete an ObjectTo get or modify an object’s attributes, or to delete an object, call getObject(),modifyObject(), or deleteObject(). These methods are defined in classSmDmsObject.For example, to get the attributes of the organization org whose DN isreferenced by ORG_ROOT in the directory namespace dmsDir:ORG_ROOT="o=swdev.com";SmDmsDirectory dmsDir = dmsContext.getDmsDirectory();SmDmsOrganization org = dmsDir.newOrganization(ORG_ROOT);SmApiResult result = org.getObject();To modify an object’s attributes, you first fetch the existing attributes withgetObject(). Then, you set the new attribute(s) by calling setAttribute() (inclass SmDmsObject), just as you do when adding an object.). For example, tomodify the user USER_DN1 in the organization org above by setting attribute lto the value Boston:SmDmsUser user = org.newUser(USER_DN1);result = user.getObject();user.setAttribute("l", "Boston");result = user.modifyObject();156 Developer's Guide for Java

SearchesYou can modify multiple values for all attributes, not just the objectclassattribute.To delete the user in the previous example:SmDmsUser user = org.newUser(USER_DN1);result = user.deleteObject();SearchesYou can search LDAP directories and ODBC directories. You search anorganization using one of the search... methods in the classSmDmsOrganization.You define a search using the following objects:■■SmDmsSearch to set search parameters such as the search starting point,the maximum number of records to retrieve, and the search filter. Thefollowing sections describe the use of this object.SmDmsCursor to define optional sorting and paging preferences.You can specify the search parameters to use when searching the directory.There are two times when you can specify search parameters:■■When you create the search objectAfter you create the search objectYou can use either option or both options. They are not mutually exclusive.Chapter 6: Delegated Management Services API 157

SearchesSet Search Parameters When You Create the Search ObjectTo specify a search parameter when you create a search object, pass one ormore search parameter names to the constructor of the SmDmsSearch class.There are some search parameters that you cannot specify during creation ofthe search object—for example, scope. The constructor for the SmDmsSearchclass accepts only the following search parameters:■■■■filterrootpropertyNamesmaxItemsYou can create an SmDmsSearch object without passing any searchparameters to the constructor.Set Search Parameters After Creating the Search ObjectAfter a search object is created, you can use the set... methods in theSmDmsSearch class to:■■Set additional search parameters.Reset search parameters that you set when the search object was created.By using the set... methods, you can set or reset any of the parameters shownin the following table:Parameter Default Set Method DefinitionclassIdUnknown(not setyet)setClassId()Class identifier.filter " " setFilter() Search filter, or thestring you want to find.Can also be set when thesearch object is created.maxItems 50 setMaxItems() Maximum number ofresult set items todisplay at a time.Can also be set when thesearch object is created.158 Developer's Guide for Java

SearchesParameter Default Set Method DefinitionnMaxResults -1 setMaxResults() Maximum number ofitems for the result set.For example, ifnMaxResults is 500, but750 items match thesearch criteria, only thefirst 500 matches will bereturned from thesearch.nextItem -1 setNextItem() The item to start with onthe next searchforward—for example:nextItem += maxItemspreviousItem -1 setPreviousItem()The item to start with onthe next searchbackward—for example:previousItem-=maxItemspropertyNames null setPropertyNames()Properties to return fromthe search.Can also be set when thesearch object is created.root " " setRoot() Directory entry wherethe search should start.Can also be set when thesearch object is created.Valid for LDAP searchesonly.scope None setScope() Levels searched.For LDAP searches only.timeout -1 setTimeout() Maximum duration of thesearch, in seconds.Chapter 6: Delegated Management Services API 159

SearchesSet the Search FilterThe search filter defines the items you want to retrieve in the search. You canset the search filter through an SmDmsSearch constructor or through theSmDmsSearch method setFilter().The search filter is described differently for LDAP directories and ODBCdirectories.Set the Search Filter for LDAP DirectoriesWith LDAP directories, you provide a complete LDAP search filter in the filterparameter of an SmDmsSearch constructor or setFilter() method. Forexample, if you pass filter and root to the SmDmsSearch constructor to searchthe organization swdev.com for groups, you could specify the following:SmDmsSearch search = new SmDmsSearch ("(&(objectclass=organizationalUnit) (ou=groups))","o=swdev.com");Set the Search Filter for ODBC DirectoriesA search of an ODBC directory is performed through a SQL query. The DMSAPI supports the SQL SELECT statement.The information you provide in the search filter depends on whether yoursearch uses an SmDmsCursor object to provide sorting and paging operations:■■With ODBC searches that do not pass an SmDmsCursor object to thesearch method, use a fully defined SQL SELECT statement in the searchfilter.With ODBC searches that do pass an SmDmsCursor object to the searchmethod, use a partial SQL SELECT statement in the search filter,consisting only of FROM and WHERE clauses.160 Developer's Guide for Java

SearchesWith ODBC database searches that pass an SmDmsCursor object to the searchmethod, the DMS API constructs the complete SQL SELECT statement fromvarious sources, as follows:■■The FROM and WHERE clauses are taken from the filter parameter of anSmDmsSearch constructor or setFilter() method.The SELECT columns portion of the query is taken from attributes specifiedin either of the following parameters:■■The propertyNames parameter of setPropertyNames(). Theseattributes are used when an SmDmsSearch object is passed to one ofthe search methods in SmDmsOrganization.The attrNames parameter of a getGroups() or getMembers() method.■The ORDER BY keywords portion is taken from the order of the attributesyou specify in the sort parameter of the SmDmsCursor constructor.Consider the following code fragment:String DIR_ROOT = "root";String SRCH_FILTER ="from SmGroup";SmDmsSearch search = new SmDmsSearch(SRCH_FILTER);String[] prop = {"Name", "'Group' as Class"};search.setPropertyNames(prop);Vector SortOrder = new Vector();SortOrder.add("uid");SmDmsCursor cursor = new SmDmsCursor(SortOrder,blockSize,false,true);The DMS API uses the information in the previous example to build thefollowing SQL statement:SELECT Name, 'Group' AS Class FROM SmGroup ORDER BY uid ASCCode SourceSRCH_FILTER parameter ofSmDmsSearch constructorSortOrder parameter ofSmDmsCursor constructorprop parameter ofsetPropertyNames()Portion of SQL Statementfrom SmGrouporder by uid ascselect Name, 'Group' as ClassChapter 6: Delegated Management Services API 161

SearchesSearch an OrganizationIn the DMS API, searches are performed on an organization object.To search an organization:1. Create a search object. This search object holds the search parameters.For example, the following SmDmsSearch constructor call creates a searchobject to search for groups. The root parameter specifies a start point ofo=swdev.org.SmDmsSearch mySearch = new SmDmsSearch ("(&(objectclass=organizationalUnit) (ou=groups))","o=swdev.org");Note: The root is the top level of the SiteMinder user directory to search.It is not necessarily the top level of the entire directory structure.Use the set... methods in the SmDmsSearch class to set any other searchparameters—for example:mySearch.setScope(2);2. Optionally, define sorting and paging preferences in the SmDmsCursorobject.3. Call the search() method in class SmDmsOrganization on the organizationyou want to search—for example:result = targetOrg.search (mySearch, 1);The second parameter of the search() method indicates the direction tosearch, as shown in the following table:DirectionInteger ValueReset 0Forward 1Back 2Refresh 34. To get the items returned from the search, call getResults() on thesearch object—for example:Vector mySearchResults = search.getResults();The first element of the results vector contains the search parameters in aSmDmsSearchResultParams object. The remaining elements areSmDmsObject objects. To distinguish object types, the classId attribute ofeach object is set through the setClassId() method. For example, if theclassId is DMSOBJECT_CLASS_USER, the object is a user. If the classId isDMSOBJECT_CLASS_GROUP, the object is a group.162 Developer's Guide for Java

SearchesExamples of a SearchThe following example searches an organization using the search parametersset through the search.set... methods below. The results of the forward searchare assigned to the vector vsearch and are printed along with the searchparameters.SmDmsContext dmsContext = new SmDmsContext();SmDmsDirectory dmsDir = dmsContext.getDmsDirectory();SmApiResult result = new SmApiResult();SmDmsOrganization org = dmsDir.newOrganization (DIR_ROOT);// SearchSmDmsOrganization test = org.newOrganization("");SmDmsSearch search = new SmDmsSearch ("(&(objectclass=organizationalUnit) (ou=groups))","o=swdev.com");// Define search parameterssearch.setScope(2); // Number of levels to search.search.setNextItem(0); // Initialize forward search startsearch.setMaxItems(20); // Max number of items to displaysearch.setPreviousItem(0); // Initialize back search startsearch.setMaxResults(500); // Max items in the result setresult = test.search(search, 1);Vector vsearch = search.getResults();System.out.println("Search object vector size " + vsearch.size());SmDmsSearchResultParams searchParams =(SmDmsSearchResultParams)vsearch.firstElement();System.out.println("***Search Parameters***");System.out.println(searchParams.toString());System.out.println("removed element at 0");vsearch.removeElementAt(0);System.out.println("Search object vector size " + vsearch.size());for (int i=0; i

User Password StateThe following code fragment configures sorting and paging features throughan SmDmsCursor object and performs a search. The parameters for theSmDmsSearch object search would be defined in the same way as in theprevious example:Vector SortOrder = new Vector();SortOrder.add("uid");int blockSize = 20;SmDmsCursor cursor=new SmDmsCursor(SortOrder,blockSize,false,true);cursor.setOffset(15);result = org.search(search, cursor, 1); //Forward searchSystem.out.println(keys.nextElement() + " = " +values.nextElement() );User Password StatePassword state refers to activities relating to a given user’s password—forexample, the last time the password was changed, and the last time thepassword was used to log in the user. To retrieve an existingSmDmsUserPWState object for a user, or to set a new password state objectwith any attribute changes, call getUserPWState() or setUserPWState() inSmDmsUser.The following table lists the password state attributes you can access for agiven user, and the method used to set or retrieve an attribute value. Allmethods are in the class SmDmsUserPWState, unless otherwise noted.Password StateAttributeMethodDescriptionLogin failuressetLoginFailures()getLoginFailures()Sets or retrieves thenumber of times the userfailed to log in since theuser’s last successful login.Last login timePrevious login timesetLastLoginTime()getLastLoginTime()setPrevLoginTime()getPrevLoginTime()Sets or retrieves the timethe user last logged insuccessfully.Sets or retrieves the nextto-lasttime the user loggedin successfully.164 Developer's Guide for Java

ODBC SupportPassword StateAttributeMethodDescriptionDisabled timePassword historysetDisabledTime()getDisabledTime()SmDmsUser.setUserPWState()Sets or retrieves the timethe user object wasdisabled.Optionally, clears the user’spassword history whensetting the password stateobject for the user.You cannot retrievepassword history or setpassword history entries.Last passwordchange timesetLastPWChangeTime()getLastPWChangeTime()Sets or retrieves the timethe user’s password was lastchanged.If you change a password state attribute, the change applies to the currentpassword state object only. To apply the change to a password state objectthat may be subsequently retrieved, pass the current password state object ina call to SmDmsUser.setUserPWState(). This method sets a new passwordstate object containing the attribute values passed into the method.ODBC SupportWhen operating against ODBC-based user directories, you can use thefollowing DMS API methods:■■■■■■■■SmDmsApiImpl.getDirectoryContext(SmUserDirectory,SmDmsConfig, SmDmsDirectoryContext)SmDmsDirectory.getCapabilities(Vector)SmDmsDirectory.getUserChallengeText(String)SmDmsDirectory.getUserTempPassword(String, String)SmDmsObject.getGroups(Vector, boolean)SmDmsObject.getObject()SmDmsObject.getObject(Vector)All search... methods in SmDmsOrganizationChapter 6: Delegated Management Services API 165

Restricted Methods■■SmDmsUser.authenticate(String)SmDmsUser.changePassword(String, String, boolean)DMS roles are not supported. Also not supported are operations such asadding and deleting users and groups, adding users to a group, and removingusers from a group.Restricted MethodsSome of the methods in the DMS API can only be called within a sessionestablished at a minimum level of the user privilege hierarchy or higher. Forexample, adding an end user to a role requires an organization administratorsession, Siteminder administrator session, or super administrator session.The following table shows the DMS methods (plus the login() and logout()methods in the apiutil package) that have security restrictions, the minimumprivilege level required to call the methods, and the classes that the methodsare called from:MethodaddObject()addToGroup()addToRole()authenticate()changePassword()deleteObject()getCapabilities()getDirectoryContext()getDisabledState()getDmsContext()Minimum Privilege Level and ClassOrganization administrator sessionSmDmsObject and subclassesOrganization administrator sessionSmDmsObject and subclassesOrganization administrator sessionSmDmsUser classEnd user sessionSmDmsUser classEnd user sessionSmDmsUser classOrganization administrator sessionSmDmsObject and subclassesEnd user sessionSmDmsDirectory classEnd user sessionSmDmsApiImpl classEnd user sessionSmDmsUser classSiteMinder administrator sessionSmDmsApiImpl class166 Developer's Guide for Java

Restricted MethodsMethodgetDmsRoles()getGroups()getGroups()getMembers()getMembers()getObject()getOrganizations()getRoles()getRoles()getUserChallengeText()getUserPWState()getUserTempPassword()login()logout()modifyObject()removeFromGroup()search()searchBack()Minimum Privilege Level and ClassOrganization administrator sessionSmDmsDirectory classEnd user sessionSmDmsObject and subclassesOrganization administrator sessionSmDmsOrganization classOrganization administrator sessionSmDmsGroup classOrganization administrator sessionSmDmsRole classEnd user sessionSmDmsObject and subclassesOrganization administrator sessionSmDmsOrganization classEnd User sessionSmDmsUser classOrganization administrator sessionSmDmsOrganization classSuper administrator sessionSmDmsDirectory classEnd user sessionSmDmsUser classSuper administrator sessionSmDmsDirectory classNo sessionSmApiSession classSiteMinder administrator sessionSmApiSession classEnd user sessionSmDmsObject and subclassesOrganization administrator sessionSmDmsObject and subclassesOrganization administrator sessionSmDmsOrganization classOrganization administrator sessionSmDmsOrganization classChapter 6: Delegated Management Services API 167

Restricted MethodsMethodsearchForward()searchRefresh()setDisable()setDisabledState()setEnable()modifyObjectClass()setPasswordMustChange()setUserPWState()Minimum Privilege Level and ClassOrganization administrator sessionSmDmsOrganization classOrganization administrator sessionSmDmsOrganization classOrganization administrator sessionSmDmsUser classOrganization administrator sessionSmDmsUser classOrganization administrator sessionSmDmsUser classOrganization administrator sessionSmDmsObject and subclassesEnd user sessionSmDmsUser classEnd user sessionSmDmsUser class168 Developer's Guide for Java

IndexAAbout Policy Management • 54About the DMS API • 139accessing a resource • 37accounting port • 19Active Expressions • 128active policies • 132active policies, rules, and responses • 127, 129Active Policy Configuration • 132Active Policy Editor • 132Active Response Configuration • 134Active Rule Configuration • 133Active Rule Editor • 133ActiveExpression interface • 130ActiveExpression Methods • 130ActiveExpressionContext class • 131AD namespace for user directory • 147Add a User to a Group • 156Add a User to a Role • 156Add an Object to a Directory • 155Add Objects to the Policy Store • 71addAdmin() • 59addAdminToDomain() • 59addAgent() • 59addAgentConfig() • 60addAuthAzMap() • 60addCertMap() • 61addDomain() • 61addGroup() • 63addHostConfig() • 63adding objects to a directory • 155adding to directories • 155adding to groups • 156adding to roles • 156addObject() • 166addODBCQuery() • 64addPasswordPolicy() • 64addPolicy() • 65addPolicyLink() • 65addRealm(() • 66addResponse() • 66addResponseAttr() • 66addRootConfig() • 67addRule() • 67addScheme() • 61addSelfReg() • 68addToGroup() • 63, 156, 166addToRole() • 156, 166addTrustedHost() • 68addUserDirectory() • 68addUserDirToDomain() • 68addUserPolicy() • 69Administrator Methods • 59administrator session • 58Advantages of Session Variables • 48affiliates • 91Agent API • 31Agent API Class Hierarchy • 32Agent Configuration Object Methods • 60agent information • 37Agent JAR file • 33Agent Methods • 59Agent Type • 52agents • 47AIX agent • 33Anonymous Template • 77API instance initialization • 36APIContext class • 115AppSpecificContext class • 115Assertion Generator Framework • 134AssertionGeneratorPlugin interface • 134AssertionSample.java • 136Attribute-based Delegation • 142attributes • 68auditing • 37, 42Auditing Services and Transaction Tracking •42authenticate() • 116, 124, 166authenticating • 37, 72, 116authenticating a user • 37, 124Authentication and Authorization APIs • 113Authentication and Authorization Map Methods• 60Authentication API • 14, 114, 115, 116, 117Authentication API JAR file • 113, 114Authentication Events • 124authentication events and performance • 111Authentication of User Credentials • 120authentication port • 19authentication scheme • 91, 100Authentication Scheme Configuration • 72Index 169

Authentication Scheme Dialog • 116, 125, 131Authentication Scheme Methods • 61authentication schemes • 72, 113, 116, 125,131Authorization API • 15, 114, 115, 127, 131Authorization API JAR file • 113, 114authorization events and performance • 111authorization port • 19Authorization Services • 42authorizing • 37, 127automatic connections • 18Bbackup Policy Server • 48balancing Policy Server load • 48base interface • 116, 130Basic Over SSL Template • 79Basic Template • 78block offset • 146block size • 146building and running applications • 12CCA Product References • iiiCache Commands • 43cached authorization • 37, 42calling sequence • 119Certificate Map Methods • 61challenging a user • 124Change the User Type in DMS Context • 152changeDynamicKey() • 70changePassword() • 166changePersistentKey() • 70changeSessionKey() • 70changing user type • 152class identifiers • 145classes • 117, 131Classes and Interfaces in the AuthenticationAPI • 116Classes and Interfaces in the Authorization API• 130Classes for Internal Use • 25Cluster Configuration • 49Cluster Failover • 50Clustered and Non-Clustered Servers • 49Code Samples • 12Common Classes • 115components • 13, 16configuration • 113configuration file • 18, 19, 47Configuration Information • 75Configuration of All Custom Classes • 113Configure Attribute-based Delegation • 143configuring • 72, 113, 131Connection Class • 26connection handles • 17connection parameters • 36Connection to a Policy Server • 36connection types • 17Contact Technical Support • iiicontainers in directories • 141Context Class • 144cookies, SMSESSION • 45Core Methods in the Result Class • 29Create a Custom Authentication Scheme • 116Create an Object • 154create token • 45createSSOToken() • 45creating • 18, 19, 36, 154creating objects • 154credentials, custom authentication • 116, 117,120, 121CRYPTOCard RB-1 Template • 80Cursor Class • 146custom authentication • 116, 120Custom Authentication Scheme Configuration •131custom authorization • 127Custom Classes for Authentication andAuthorization • 114Custom Template • 81customizeAssertion() • 135DdecodeSSOToken() • 45decrypt token • 45default object handle • 17Delegated Management Services API • 15, 139Delete Objects from the Policy Store • 72deleteAdmin() • 59deleteAgent() • 59deleteAgentConfig() • 60deleteAuthAzMap() • 60deleteCertMap() • 61deleteDomain() • 61deleteGroup() • 63deleteHostConfig() • 63deleteObject() • 156, 166170 Developer's Guide for Java

deleteODBCQuery() • 64deletePasswordPolicy() • 64deletePolicy() • 65deletePolicyLink() • 65deleteRealm() • 66deleteResponse() • 66deleteResponseAttribute() • 66deleteRootConfig() • 67deleteRule() • 67deleteScheme() • 61deleteSelfReg() • 68deleteTrustedHost • 68deleteUserDirectory() • 68deleteUserPolicy() • 69deleting • 156delSessionVariables() • 47description • 142Development and Deployment Notes • 136direction • 162directory • 145Directory Context • 152directory context class • 152disambiguation • 121, 122discarding • 42Djava.class.path • 136DMS API • 139, 140, 143, 144DMS API support • 166DMS Context • 150DMS Context class • 150DMS hierarchy • 143DMS Users • 143doExport() • 65doImport() • 65DOM parser • 136Domain Methods • 61domain objects • 55doManagement() • 36dynamic load balancing • 48Eelements • 27Encryption Commands • 43End of Session Cleanup • 48end user session • 143equals() • 23, 28, 29errors on server • 27Establish a Connection to the Policy Server •17, 57Establish a Default Connection • 18Establish a User-Defined Connection • 19event processing and performance • 111events and custom authentication • 124Examples of a Search • 163Exception class • 29Exception Class • 29exceptions • 23, 27, 29Execute an Active Expression • 128execute() • 26execution sequence • 128existing connections • 19Extend the SAML and WS-FederationAuthentication Schemes • 125FFacility portion of result • 27failover • 16, 36, 48, 50failures • 164filter for directory searches • 159filters • 159flat directories • 142flow of calls • 17flushAll() • 70flushing caches • 37, 70flushing from cache • 70flushRealm() • 70flushRealms() • 70flushUser() • 70flushUsers() • 70FROM clause • 160GGeneral Object Methods • 62Get Directory Entry Attributes • 154Get, Modify, or Delete an Object • 156getAdmin() • 59getAdminUserDirs() • 59getAgent() • 59getAgentApiConnection() • 26getAgentConfig() • 60getApiConnection() • 26getAttribute() • 154getAuthAzMap() • 60getCapabilities() • 166getCertMap() • 61getDirectoryContents() • 68getDirectoryContext() • 144, 166getDisabledState() • 166getDisabledTime() • 164Index 171

getDmsContext() • 144, 166getDmsDirectory() • 144getDmsRoles() • 166getDomain() • 61getDomainObject() • 61getDomainObjectNames() • 61getError() • 29getFacility() • 29getGlobalObjectNames() • 62getGroup() • 63getGroupMembers() • 63getGroups() • 166getHostConfig() • 63getLastLoginTime() • 164getLastPWChangeTime() • 164getLoginFailures • 164getMembers() • 166getMessage() • 29getName() • 30getObject() • 62, 156, 166getODBCQuery() • 64getOid() • 62getOrganizations() • 166getPasswordPolicy() • 64getPolicy() • 65getPolicyLinks() • 65getPrevLoginTime() • 164getRealm() • 66getRealmRules() • 66getRealmUserPolicies() • 66getReason() • 27, 29getResponse() • 66getResponseAttrs() • 66getResults() • 162getRoles() • 166getRootConfig() • 67getRule() • 67getScheme() • 61getSelfReg() • 68getSessionSpec() • 26getSessionVariables() • 47getSeverity() • 29getStatus() • 29getType() • 30getUserChallengeText() • 166getUserDirectory() • 68getUserDirSearchOrder() • 68getUserPolicies() • 69getUserPWState() • 164, 166getUserTempPassword() • 166getValue() • 30global objects • 55Group Methods • 63Hhierarchical directories • 140Host Configuration Object Methods • 63How Information Is Bound to a Session • 47How Java Components Fit Together • 16How SiteMinder Initializes AuthenticationProcessing • 119How SiteMinder Loads a Custom AuthenticationScheme • 118How Web Agents Use the Agent API • 39HP-UX 11 agent • 33HTML Form Template • 82Iidentity ticket • 40identity tracking • 40Impersonation Template • 84Implement the JNI Java Agent API • 33Implement the Pure Java Agent API • 34Implementation Class • 144initializing a connection • 36initializing an Agent API instance • 36Installation Path • 11installation path of Java APIs • 11Interaction between SiteMinder and anAssertion Generator • 135Interpret a Result Object • 28Interpret an Active Expression Result • 129interpreting as an object • 28invoke() • 130isDomainObject() • 61isEnabled() • 64isEntireDir() • 64isProtected() • 37, 42isSuccess() • 23, 29, 71isValidApiConnection() • 26isWriteable() • 62JJAR file • 33, 55, 140jar file deployment • 114Java Agent API • 13, 33Java Agent API Services • 40Java API Flow • 17172 Developer's Guide for Java

Java API Overview • 11Java Authentication API • 116Java Authorization API • 127Java components • 13Java components of SDK • 13Java Components of the SiteMinder SDK • 13Java DMS API • 139Java Policy Management API • 54Javadoc • 24Javadoc Reference • 24JVMOptions.txt • 113, 114, 136LLDAP directories • 160libraries for authentication schemes • 75library entry point • 113library file • 114libsmjavaagentapi.sl • 33libsmjavaagentapi.so • 33Linux agent • 33load balancing • 16, 48load distribution • 48loading and initializing • 118LocalConfig.conf • 19, 47Log in as a SiteMinder Administrator • 22Log on through a Custom Agent • 45Log on through a Standard Agent • 46Log Trace Information • 23logging trace information • 23login • 22, 26, 40, 41, 58login() • 166logout • 26, 40, 58logout() • 166lookupDirectory() • 68MMake API Requests and Handle Results • 23Make Policy Management API Requests • 58Management Services • 43managing agents • 37managing user attributes • 68manual connections • 19Message portion of result • 27messages • 115method security in DMS • 166methods • 147Microsoft LDAP searches • 147mixed mode • 100Modify a SAML Assertion or Response • 134modifyAdmin() • 59modifyAgent() • 59modifyAgentConfig() • 60modifyAuthAzMap() • 60modifyCertMap() • 61modifyDomain() • 61modifyGroup() • 63modifyHostConfig() • 63modifyObject() • 156, 166modifyObjectClass() • 166modifyODBCQuery() • 64modifyPasswordPolicy() • 64modifyPolicy() • 65modifyPolicyLink() • 65modifyRealm() • 66modifyResponse() • 66modifyRootConfig() • 67modifyRule() • 67modifyScheme() • 61modifySelfReg() • 68modifyUserDirectory() • 68MS Passport Template • 85Nnamespace • 145native mode • 100network architecture • 16Network Architecture • 16new session specification • 22non-clustered Policy Servers • 49OObject Associations • 70Object class • 145Object Class • 145object creation • 58, 154Object Model • 145Obtain a Session • 21Obtain a Session Object • 58ODBC directories • 160ODBC Query Scheme Methods • 64ODBC Support • 166offset of result set block • 146ORDER BY clause • 160organization administrators • 40, 142organization DN • 140, 145organization objects, creating • 154organizational units (ou). See SiteMinder userdirectory • 140Index 173

organizations in flat directories • 143organizations. See SiteMinder user directory •140Other Classes in the Authentication API • 117Other Classes in the Authorization API • 131Ppackage name • 13paginating • 146paging preferences • 146parameter for authentication scheme • 75parameter value • 75Pass in the Session Object • 58Password Policy Methods • 64password state • 164percentage for failover threshold • 50performance • 48Performance Consideration • 111performance issue with realms • 111persistent sessions • 48plug-in. See SAML assertions • 134policies, active • 127, 129, 132Policy Management API • 14, 53, 55, 57, 58Policy Management Setup • 55Policy Methods • 65Policy Migration Methods • 65Policy Server • 17, 36Policy Server Prerequisite • 12Policy Store Objects • 55policy-based response attributes • 44portals • 91ports • 19prerequisites for Policy Management setup • 55primary cluster • 50privilege hierarchy • 143privilege hierarchy in DMS • 143process flow • 39properties • 30Property class • 30Property Class • 30PropProcessAuthEvents • 111PropProcessAzEvents • 111protected resources • 37, 42, 127protection level for authentication schemes •75Purpose of the Java APIs • 11Purpose of the Utilities Package • 25Qquery() • 116RRADIUS CHAP/PAP Template • 87RADIUS Server Template • 88Realm Methods • 66reason code for a result • 27redirection • 124Redirection • 124reference documentation • 24removeAdminFromDomain() • 59removeFromGroup() • 63, 166removeUserDirFromDomain() • 68renameObject() • 62RequestContext class • 131requests, storing results of • 27required attributes • 143Required JAR File • 55Required Library File • 114required, attribute-based delegation • 143requirements • 33Requirements for Using Session Variables • 48resource access • 37, 42resources, check if protected • 37, 42Response Attribute Editor • 134response attributes • 37, 42, 44, 129Response Attributes • 44Response Methods • 66responses, active • 127, 129, 134Restricted Methods • 166Result class • 27Result Class • 27result objects • 23results • 129Retrieve Objects from the Policy Store • 72retrieving an attribute value • 154retrieving attributes • 156retrieving for object • 156retrieving results • 162Root Configuration Methods • 67root of SiteMinder user directory • 140, 162round-robin Policy Servers • 49Rule Methods • 67rules, active • 127, 129, 133running applications • 55174 Developer's Guide for Java

SSafeWord HTML Form Template • 89SafeWord Template • 90SAML Artifact Template • 91samples • 12SAX parser • 136scheme. See authentication scheme • 72SDK installation path • 11SDK samples • 12Search an Organization • 162Search Class • 146search filter • 160search() • 70, 166search... methods • 147searchBack() • 166Searches • 157Searches of Microsoft LDAP Directories • 147Searches that Support Cursor Operations • 147searchForward() • 166searching • 162searching directory • 68searchRefresh() • 166SecurID HTML Form Template • 94SecurID Template • 96security • 58, 143SELECT statement • 160Self-Registration Methods • 68sequence number • 49Server Clusters • 48server. See Policy Server • 48server-side errors • 27services • 40session • 22, 58, 143Session Class • 26Session Creation and the Session Specification• 40Session Delegation • 41session management • 37Session Server • 48session services • 40Session Services • 40session specification • 26, 40Session Termination • 42session ticket. See session specification • 26session types • 48Session Validation • 41session variables • 48sessions • 21, 143Set Search Parameters After Creating theSearch Object • 158Set Search Parameters When You Create theSearch Object • 158Set the Search Filter • 159Set the Search Filter for LDAP Directories • 160Set the Search Filter for ODBC Directories •160setAgentApiConnection() • 26setApiConnection() • 26setApiSession() • 70setAttribute() • 155, 156setDisable() • 166setDisabledAttr() • 68setDisabledState() • 166setDisabledTime() • 164setEnable() • 166setFilter() • 159setLastLoginTime() • 164setLastPWChangeTime() • 164setLoginFailures() • 164setName() • 30setPasswordMustChange() • 166setPrevLoginTime() • 164setResponseInPolicyLink() • 66setSessionSpec() • 26setSessionVariables() • 47setting the search order • 68setType() • 30setUserDirSearchOrder() • 68setUserPWState() • 164, 166setValue() • 30Severity portion of result • 27Shared Information • 115shared secret in authentication schemes • 75sharing information • 115single process • 19single server • 19Single Sign-on • 45SiteMinder administrators • 22, 26, 58SiteMinder Agents • 31SiteMinder User Directories • 140SiteMinder user directory • 162SiteMinder User Directory Containers • 141SmAdmin() • 59SmAgent() • 59SmAgentConfig() • 60SmAgentGroup() • 63SmApiException class • 29Index 175

SmApiResult class • 27SmApiSession class • 26SmAuthAzMap() • 60SmAuthenticationContext class • 117SmAuthenticationResult class • 117smauthetsso Authentication Scheme • 97SmAuthQueryCode class • 117SmAuthQueryResponse class • 117SmAuthScheme interface • 116SmAuthScheme Methods • 116SmAuthStatus class • 117SmCertMap() • 61SmDmsApi interface • 144SmDmsApiImpl class • 144SmDmsConfig class • 141, 142, 143SmDmsContext class • 144, 150SmDmsCursor class • 146, 162SmDmsDirectory class • 144, 145SmDmsDirectoryContext class • 144, 152SmDmsGroup class • 145SmDmsObject class • 145SmDmsOrganization class • 145SmDmsRole class • 145SmDmsSearch class • 146SmDmsUserPWState class • 164SmDomain() • 61SmExportAttr() • 65SmHostConfig() • 63SmImportAttr() • 65smjavaagentapi.dll • 33smjavaagentapi.jar • 33smjavaapi • 113, 114SmJavaApiException class • 115SmODBCQuery() • 64SmPasswordPolicy() • 64SmPolicyApiImpl() • 59, 60, 61, 62, 63, 64,65, 66, 67, 68, 69, 70SmProperty class • 30SmRealm() • 66SmResponseAttr() • 66SmResponseGroup() • 63SmRootConfig() • 67SmRule() • 67SmRuleGroup() • 63SmScheme class • 75SmScheme() • 61SmSelfReg() • 68SMSESSION cookie • 45SmTrustedHost() • 68SmUserDirectory() • 68SmUserPolicy() • 69Solaris agent • 33sorting • 146sorting and paginating results • 147sorting and paging operations • 147sorting preferences • 146SQL • 160SSO. See single sign-on • 45Standard Agent Support • 47starting class • 144Status portion of result • 27stored as session variables • 47sub DNs • 141super administrators • 40Support for Custom Code • 24Supported Credentials • 121system objects. See global objects • 55TTeleID Template • 99templates for authentication schemes • 75Terminate the Administrator Session • 58termination • 42, 48The Required JAR File • 140The Role of the MessageConsumerPlugin • 126threshold percentage • 50ticket. See identity ticket, session specification• 26timeout information • 51Timeouts • 51tokens • 45toString() • 29trace information, logging • 23tracking, identity • 40transaction ID • 42Trusted Host Object Methods • 68Tunnel Services • 44types, and realms • 48UunInit() • 37uninitializing an Agent API instance • 37unique constants • 28universal ID • 40updateAttributes() • 44updating encryption keys • 37, 70usage flow • 17Use the Authorization API • 127176 Developer's Guide for Java

User Access to Resources • 37User Authentication • 124User Directory Methods • 68user disambiguation • 121, 122User Disambiguation • 122User Disambiguation and Authentication • 121User Password State • 164User Policy Methods • 69user privilege hierarchy • 143UserContext class • 115UserCredentialsContext class • 117user-defined Agent object handle • 17using Authentication • 116using Authorization • 127using Policy Management • 57using the DMS API • 139Utilities Package • 15, 25Utility Methods • 70Vvariables, session • 47Version Compatibility and Failover Behavior •51version of custom authentication scheme • 116WWeb Agent • 39WebAgent.conf • 19, 47well-known response attributes • 44When All Clusters Fail • 50WHERE clause • 160Windows agent • 33Windows Authentication Template • 100workflow • 120Write a Directory Management Application •148Write a Policy Management Application • 57writing applications • 148XX.509 Client Cert and Basic Template • 103X.509 Client Cert and Form Template • 105X.509 Client Cert or Basic Template • 106X.509 Client Cert or Form Template • 108X.509 Client Cert Template • 110Index 177