Siteminder

How the Agent Reads SiteMinder Cookies

 

Web Agents use agent keys to encrypt and decrypt SiteMinder cookies so the data they contain can be read. The Agent uses the key to encrypt cookies before sending them to a user’s browser and to decrypt cookies received from other Web Agents.

All Web Agents need to be aware of the same keys, and the keys must be set to the same value for all Agents communicating with a Policy Server. This rule is particularly important for Agents in a single sign-on environment. To ensure that the keys remain secure, the Policy Server performs a key rollover. A key rollover is the process of generating new keys, encrypting them, and distributing them to all Web Agents within a SiteMinder environment.

When a Web Agent starts up and makes a management call request, the Policy Server supplies the current set of keys. Each time the Web Agent polls the Policy Server, the agent again makes the management call. The Web Agent receives the updated keys.

The Policy Server provides the following types of keys:

 

Dynamic Keys

Refers to a key that is generated by a Policy Server algorithm and distributed to other connected Policy Servers and their associated Web Agents. Dynamic keys can be rolled over automatically at a regular interval, or they can be changed manually by using the Policy Server User Interface.

 

Static Keys

Refers to a key that remains the same indefinitely, and can be generated by a Policy Server algorithm or configured manually. SiteMinder uses this type of key for a subset of features that requires information to be stored in cookies over extended periods.

Automated key changes ease the process of managing agent keys for large SiteMinder installations that share a single key store. A key store is a storage location for all key information. Policy Servers access the key store to obtain the current keys, which are then passed on to the Web Agents. For Agents that are configured for single sign-on, the key store must be replicated and shared across all Policy Servers in the single sign-on environment. Automating key changes also ensures the integrity of the keys.

Note: For more information, see the Policy Server documentation. How Web Agents Secure Resources Chapter 1: Web Agents 21

Web Agents and Dynamic Key Rollovers

You can use the Policy Server User Interface to configure dynamic Agent key rollover. Web Agents poll the Policy Server for key updates at regular intervals. If keys have been updated, Web Agents pick up the changes during polling. The default polling time is 30 seconds, but you can customize it by changing the value of the PSPollInterval parameter for a Web Agent.

When a Web Agent detects that a key rollover has occurred, the Agent retrieves new values for the following Agent keys:

 

Old Key

Contains the last value used for the dynamic Agent key before the current value.

 

Current Key

Contains the value of the current dynamic Agent key.

 

Future Key

Contains the next value that will be used as the current key in a dynamic Agent key rollover.

 

Static Key

Contains a long-term key that the Agent can use for SiteMinder features that need to identify a user and maintain this information for long periods. Static keys also support cookie encryption for single sign-on when dynamic keys are not enabled.

Web Agents require multiple keys to preserve cookie data and ensure a smooth transition between old keys and new keys.

 

More information:

Change How Often an Agent Checks for Policy or Key Updates (see page 50)

 

Key Stores

When the Policy Server generates dynamic keys, it saves and maintains these keys in the key store. The key store is a repository from which all Policy Servers retrieve the most current keys. Web Agents obtain the current keys from the Policy Servers. The key store may be part of a SiteMinder policy store or maintained as a stand-alone key store.

Note: If an administrator issues multiple agent key rollovers in rapid succession, this action may invalidate all cookies issued for single sign-on and may disrupt single sign-on for all users currently logged in. After these users re-authenticate, single sign-on will operate normally.

 

How to Edit an Agent Configuration File

 

The agent configuration file controls the settings of a locally-configured Web Agent. To change those settings, use the following process:

1. Create a backup copy of WebAgent.conf (for a traditional agent) or LocalConfig.conf file (for a Framework agent).

2. Open the original copy of the agent configuration file with a text editor.

3. Enable or disable parameters by doing any of the following:

■ Removing the pound sign (#) from the beginning of the line to enable a parameter.

■ Adding the pound sign (#) to the beginning of the line to disable a parameter.

 

4. Change the values of parameters using the following guidelines:

– Do not add spaces between the parameter names, the equals sign (=), and the parameter values.

– Surround the parameter values with quotation marks.

– The WebAgent.conf and LocalConfig.conf files are not case-sensitive. You do not have to match the case shown in the sample file installed with the Agent.

– Many values are shown in the file as descriptive variables, such as ,. Replace the angle brackets and text with the values you want.

– In cases where the value is Empty, a blank is valid as the default. A default value applies only if there is no pound sign (#) preceding the parameter.

5. Set EnableWebAgent to yes only when you are done making changes, then save and close the file.

 

 

 

Forms Credential Collector (FCC)

 

Gathers credentials based on HTML forms that are presented to the user during an authentication challenge. The forms that the FCC presents are based on templates that have the file extension .fcc. For example, the Web Agent is installed with a form called login.fcc, which you can customize and use for login purposes. This file is written using standard HTML tags and some proprietary notation required by SiteMinder.

 

A SiteMinder credential collector is an application within the Web Agent that gathers specific user credentials to authenticate a user. The credentials gathered by the credential collector are based on the type of authentication scheme configured for a particular group of protected resources. Credential collectors are used for forms, SSL, and Windows authentication schemes, and for single sign-on across multiple cookie domains.

 

Cookie Provider (CCC)

Tracks SiteMinder sessions across multiple cookie domains for single sign-on. Unlike other types of credential collectors, the cookie provider does not collect credentials or perform an authentication challenge of the user. The cookie provider is handling credentials; however, in this case, the session is the credential.

 

 

Policy Store

 

(Required) The SiteMinder policy store (policy store) is an entitlement store that resides in an LDAP directory server or ODBC database. The purpose of this component is to store all policy-related objects, including the:

■ Resources SiteMinder is protecting

■ Methods used to protect those resources

■ Users or groups that can or cannot access those resources

■ Actions that must take place when users are granted or denied access to protected resources

 

The Policy Server uses this information, collectively known as a policy, to determine if a resource is protected and if an authenticated user is authorized to access the requested resources.

 

CA Directory as a Policy Store

 

Policy Servers installed on either Windows or UNIX systems can use CA Directory as a policy store. The following sections detail how to configure your directory server as a policy store.

 

Gather Directory Server Information

 

Configuring a CA Directory as a policy store requires specific directory server information.

 

Note: Policy and data store worksheets are provided to help you gather and record information before configuring or upgrading a SiteMinder data store. You can print the applicable worksheet and use it to record required information before beginning.

Gather the following information before configuring the policy store. You can use the Policy Store Worksheets to record your values.

 

■ Host information—Determine the fully qualified host name or the IP address of the system on which CA Directory is running.

■ DSA port number—Determine the port on which the DSA is to listen.

 

■ Base DN—Determine the distinguished name of the node in the LDAP tree in which policy store objects are to be defined.

 

■ Administrative DN—Determine the LDAP user name of the user with the privileges to create, read, modify, and delete objects in the DSA.

■ Administrative password—Determine the password for the administrative user.

 

 

How to Configure the Policy Store

 

To configure CA Directory as a policy store, complete the following procedures:

1. Create a DSA for the policy store.

2. Create the policy store schema.

 

3. Open the DSA.

 

4. Create the base tree structure for policy store data.

 

5. Create a super user administrator for the DSA.

 

6. Point the Policy Server to the policy store.

 

7. Set the SiteMinder super user password.

 

8. Verify the CA Directory cache configuration.

 

9. Import the default policy store objects.

 

10. Import the policy store data definitions.

11. Prepare for the Administrative UI registration.

 

 

Create the Base Tree Structure for Policy Store Data

 

You create a base tree structure to hold policy store data. You use the JXplorer GUI to create the organizational units.

To create the base tree structure for policy store data

 

1. Select the root element of your DSA.

2. Create an organizational unit under the root element called:

 

Netegrity

3. Create an organizational unit (root element) under Netegrity called:

 

SiteMinder

4. Create an organizational unit (root element) under SiteMinder called:

 

PolicySvr4

The base tree structure is created.

 

Web Agent Configuration File (WebAgent.conf or LocalConfig.conf)

 

Stored on the web server where the Agent resides, this file is used for local configuration. The LocalConfig.conf file holds the Agent configuration parameters for each Web Agent. The WebAgent.conf file enables or disables the agent and loads any related plug-ins.

 

Host Configuration File (SmHost.conf)

 

Stored on the web server where the Web Agent resides, this file holds initialization parameters for the trusted host. Once the trusted host connects to a Policy Server, the trusted host uses the settings in the Host Configuration Object. The Host Configuration Object is named in the hostconfigobject parameter of this file.

 

Enable a Web Agent

You can only enable and disable an agent from the WebAgent.conf file.

The EnableWebAgent parameter value determines whether an Agent is enabled or disabled. Set it to yes to enable the Agent.

To enable the agent, complete the following prerequisites:

■ Set up all the necessary objects for Policy Server and agent communication.

■ Installed and configured the agent.

 

Configure ODBC Directory Connections

 

You can configure a user directory connection that lets the Policy Server communicate with an ODBC user store.

If you use a Microsoft SQL Server database for audit logs and caching is turned on, under heavy load, performance may suffer as the Policy Server queues messages for logging. Turn on asynchronous auditing for the realms associated with the resources being accessed by a high volume of users to alleviate the problem. How to Configure an ODBC User Directory Connection Chapter 5: User Directories 173

Follow these steps:

 

1. Click Infrastructure, Directory.

 

Objects related to user directories appear on the left.

2. Click User Directories.

 

The User Directories screen appears.

3. Click Create User Directory.

 

The Create User Directory screen appears and displays the required settings to configure an LDAP connection.

4. Select ODBC from the Namespace list.

 

ODBC settings appear.

5. Complete the remaining required connection information in the General and Directory Setup areas.

 

Note: If the Policy Server is operating in FIPS mode and the directory connection is to use a secure SSL connection when communicating with the Policy Server, the certificates used by the Policy Server and the directory store must be FIPS compliant.

6. Select a SQL query scheme.

 

7. (Optional) Do the following in the Administrator Credentials area:

a. Select Require Credentials.

b. Enter the credentials of an administrator account.

 

Note: The user name must match the user who owns the tables containing user directory data. For example, if you are using the SmSampleUsers schema, this user must be the owner of the SmUser, SmUserGroup, and SmGroup tables. The administrator account must have read or read/write privileges for the user directory.

8. (Optional) Specify the user directory profile attributes that are reserved for CA SiteMinder® use in the User Attributes area.

 

9. (Optional) Click Create in the Attribute Mapping List area to configure user attribute mapping.

10. Click Submit.

 

The user directory connection is created.

 

Directory Mapping Overview

 

The Policy Server assumes that a user is authenticated and authorized against the same user directory. However, users can be authenticated against one directory, and authorized against a separate directory. This feature is called directory mapping.

 

You can map a central directory that stores authentication information with separate distributed user directories that store authorization information. The authorization directories are associated with particular network applications. The mappings locate authenticated users in separate authorization directories.

 

HTML Forms Authentication Scheme

HTML Forms authentication schemes provide a method for authentication that is based on credentials gathered in a custom HTML form.

 

Configure an HTML Form Authentication Scheme

You can use an HTML Forms authentication scheme to authenticate users with a custom HTML form.

Note: The following procedure assumes that you are creating an object. You can also copy the properties of an existing object to create an object. For more information, see Duplicate Policy Server Objects.

Follow these steps:

1. Click Infrastructure, Authentication.

2. Click Authentication Schemes.

 

3. Click Create Authentication Scheme.

 

Verify that the Create a new object of type Authentication Scheme is selected.

Click OK

4. Enter a name and protection level.

 

5. Select HTML Form Template from the Authentication Scheme Type list.

 

6. Enter Web Server Name, Target, and Additional Attribute List information.

 

Note: Verify that the .fcc file you specify in the Target field complies with the guidelines for this field.

7. Click Submit.

 

The authentication scheme is saved and can be assigned to a realm.

 

Authentication Events

Authentication events occur as CA SiteMinder® tries to establish a user identity. As a rule action, an authentication event causes the Policy Server to fire a rule at a particular point in the authentication process.

Authentication events occur when a user accesses a resource protected by a rule that includes an On-Auth event. Unlike Web Agent actions or authorization events, authentication events always apply to the entire realm. You cannot create an On-Auth rule that applies to a portion of a realm.

The following is a list of possible authentication events:

 

OnAuthAccept:

Occurs if authentication was successful. This event can be used to redirect a user after a successful authentication.

 

OnAuthAcceptCredentials:

Occurs only during the login stage. The user credentials are presented and generate the creation of a new session.

 

OnAuthReject:

Occurs if authentication failed for a user that is bound to a policy containing an On-Auth-Reject rule. This event may be used to redirect the user after a failed authentication.

OnAuthAccept and OnAuthReject events fire both at authentication time (when the user enters their username and password) and at validation time (when the user cookie is read for user information). However, there are certain special actions that only occur at authentication time:

 

Realm timeout override (unless EnforceRealmTimeouts is used)

Unless your Web Agent supports the EnforceRealmTimeouts option and that option is enabled, the user Idle and Max Timeouts remain at the values for the realm in which the user last authenticated. The values only change if the user has to reenter their credentials.

Redirects

Redirects are only allowed at authentication time to prevent the possibility of infinite redirect loops.

Access to the user password

The password is not stored in the SMSESSION cookie, so the only time it is available is when the user actually enters it (authentication time).

Note: OnAuth event results are per realm. So for example, if a user goes from realm A to realm B and the user has an OnAuthAccept header in realm A, it is not available in realm B. When the user goes back to realm A, the header is set again.

OnAuthAttempt

Occurs if the user is rejected because CA SiteMinder® does not know this user. For example, an unregistered user can be redirected to register first.

 

Authorization Events

Authorization events occur as CA SiteMinder® verifies whether or not a user is authorized to access a resource. As a rule action, an authorization event causes the Policy Server to fire a rule at a particular point in the authorization process.

The following is a list of possible authorization events:

 

OnAccessAccept:

Occurs as the result of successful authorization. This event may be used to redirect users who are authorized to access a resource.

 

OnAccessReject:

Occurs as the result of failed authorization. This event may be used to redirect users who are not authorized to access a resource.

A rule with an authorization event action may be coupled with a CA SiteMinder® response in a policy. When a user is authorized (or rejected), the Policy Server passes any responses associated with the applicable On-Access rule back to the requesting Agent.