SSO Flow of Siteminder Agent with Policy Server

After working into CA Siteminder based projects for more than 5 years, I have came to the following conclusions about Siteimnder.

 
 Flow-1:
============
a. The user enters the application url in the browser, it goes to the web server, if web agent is installed on the web server, The request is first intercepted by the webagent.conf file

b. In web agent.conf file it finds the path of the smhost.conf file and the request goes to smhost.conf file.

c.  In the smhost.conf file it finds the policy server which it needs to contact.

d. Then Web server contacts the policy server through the ports 4444(1,2,3) that are mentioned in smhost.conf file. This is done by LLAWP(Low Level Agent Worker Process)

e. The LLAWP sends the request to policy server asking for initializing the communication between the web agent and policy server. In the request web agents send the details of trusted host that is present in smhost.conf file

f. While policy server receives the request it checks whether it can trust the request by seeing whether the trusted host present is present in policy store and if it belongs to web server from which it got the request.

g. This initial request sent by web agent is encrypted by the shared secret present in smhost file. So the request is securely and only policy server can decry-pt it.

h. If policy server trusts the request it starts the communication with the web agent. This communication will be started HLA process from policy server. HLA process uses HCO that web agent used to register with policy server.

i. When the communication from policy server reaches the web agent it decrypts the communication using shared secret and in communication it will have details about the HCO which have started the communication, it compares if HCO in communication is same as HCO present in smhost.conf file.

j. This way the policy server and web agent handshake with each other and sets the communication.Now Web agent sends the details of the ACO present in webagent.conf to policy server.

k. The policy server now takes the this ACO and it will see if it is present in policy store, if it is present it will get the agent name present in ACO and also the properties of the agent present in ACO.

l. Now policy server asks for the resource and web agents sends the resource it go from browser.

m. policy server gets the list of all the realms present in policy store which are linked to the agent that is present in the ACO. It compares the resource it got from web agent is present in any realm in the list (Here it sees the longest match) and gets the realm which has this resource and policy server see's whether this realm is configured for protected or not protected. If not protected , it will say web agent it is not protected.

n. If it is protected, it will whether the request that got from browser has smsession. If no smsession then policy server fetches the authscheme (Authentication Scheme) from realm and gives the corresponding login page to web agent and it gives it to browser.

This the process that will occur to check whether the resource or request got from browser is protected or not.

All the communication that occur after handshake between policy server and web agent is in encrypted for security. The encryption and decryption is done using keys present in key store.

Flow- 2:
=========
The WebAgent Initialization:
========================

While you register the agent with the policy server thru smreghost command, The SmHost.conf file gets created and SmHost.conf file contains information that the Web Agent uses to make initial connections to the Policy Servers to which it is associated.it also creates a trustedHost object into the policy store.which you specify at the time of registration.
Trusted Host is a client computer where one or more Web Agents is installed. It handles the connection to the Policy Server. The term trusted host refers to the physical system. You can have more than one trusted host on a physical server, but each must be identified by a unique name.

Hence when you enable the webagent and bounce the webserver, the initial connection flow goes like this, the webagent reads the WebAgent.conf file and looks for the path of SmHost.conf file, from that path it reads the SmHost.conf file and tries to connect to the IP Address of the policy Server m/c which are present there. once that is done, it then fetches the trustedHost object from the policy store (The policy Store is connected with the policy Server). Once that is done then a successful TCP connection is established between the webAgent and the policy server. the WebAgent then never uses the SmHost.conf file.


Before explaining the request processing part, let me explain the connection between WebAgent and the WebServer. There is a Http connection between the WebAgent and the WebServer. As soon as you configure the webagent with the webserver, remember we specify the webagent binaries inside the configuration of webserver. so when you bounce the webserver after configuration, it loads the webagent DLL / Binaries into the webserver process. This is how a Http connection is made.

Request Processing:
===================
When user access a resource from the browser say http://www.test.com/site/test.html . The WebAgent filters this request from the web server module and after parsing the host and the resource name webagent sends the resource name to the policy server thru the TCP socket connection in form of packets. for e.g. ACO, AgentName, HostName, Client IP, resourceName etc. each in a seperate encrypted packet. 

The Policy Server decrypts the each packet and it knows the agent name which has sent the request, from the agent name it fetches all the matching Realm Object and from the Realm object it checks the resource which has been associated with a specific realm, it then checks that if the resource is protected in a realm and if it is protected, it sends a challange response back to the webagent over the same TCP socket connection, WegAgent who is listing over that socket connection reads the response and throw a chalange to the user in the browser.

The Banawar Caves (Barabar Caves)

While all of us are familiar with the murals and temple complexes of Ajanta and Ellora, did you know that there are as many as 1200 rock-cut cave shrines found across India with more than 800 of them in the Western Ghats alone. Kanheri, Bhaja, Karle, Bhedse, Junnar, Undavalli, Udayagiri… the list is long. While most of these are Buddhist shrines built along old and important trade routes, there is one older than all the rest, dedicated to a forgotten sect. To visit it you have to go to Jehanabad.

The  Barabar Caves, around 30 km south-east of Jehanabad in Bihar, is all that remains of the lost Ajivika sect. Traced back to 5th century BCE, the Ajivikas once competed with Buddhism and Jainism for influence, only to lose out and get wiped off. Today everything including the texts of this faith have been lost.

The Barabar cave complex is one place where you can get a peep into their history. These are a set of 7 rock-cut caves, dating back to the 3rd century CE, situated on the twin hills of Barabar (4 caves) and Nagarjuni (3 caves).  Oral folklore through centuries has assigned them names familiar from the epics, such as ‘Lomas Rishi cave’ ‘Sudama cave’ and ‘Vishwamitra cave’, but these names have no historical antecedents.

Carved out of granite, each of these caves features two chambers each, with a highly polished surface. There are no sculptures or embellishments present in any of these caves. The oldest of these caves is the so-called ‘Lomas Rishi cave’ which is also considered a landmark in the architectural history of India. It is here where you will find the  first known use of the ‘Chaitya arch’ in stone which would be later replicated in caves across India, including Ajanta, and Kanheri.

The fact that these caves date back to the Mauryan times, is known from the still clear inscriptions found in these caves. The inscription in the Sudama cave, tells us that the four caves on Barabar hill were assigned by King Ashoka to Ajivika monks in the year 261 BCE. A later inscription, on the Nagarjuni hill, is of  Dasaratha Maurya, the grandson of King Ashoka, which tells us that the Ajivikas continued to enjoy imperial Mauryan patronage for long. It states -

"The Vahiyaka cave has been given by Dasaratha, dear to the gods, to venerable  Ajivakas, to be a place of abode during the monsoon as long as sun and moon shall endure."

So who were these Ajivikas, who enjoyed such imperial patronage? The most comprehensive study of the subject is by SOAS Historian AL Basham in his book ‘History and doctrines of the Ajivikas, a vanished Indian religion’. This religion probably emerged, in  the Indo-Gangetic plains, 2500 years ago. These were extraordinary times. Not only was the region experiencing a great wave of urbanization, but there was also a great intellectual ferment taking place, which gave birth to Buddhism, Jainism and the Ajivika faith. The social turmoil as independent states became hierarchical monarchies, threw up a new wave of thinkers who came to represent  the ‘Sramana’ tradition of wandering mendicants, who rejected conventional Vedic beliefs and travelled from place to place preaching their own philosophies.

Many great religious traditions grew out of it which were termed as ‘nastika darsana’ or ‘heterodox philosophies’, as they did not believe in the Vedas. Some like Buddhism and Jainism transformed into thriving religions, while others perished. The Ajivika was one such religious tradition.

The founder of the Ajivika faith was a preacher named Makkhali Gosala, a contemporary of Gautama Buddha, the founder of Buddhism and Mahavira, the 24th Tirthankara of the Jains. A companion of Mahavira, with whom he had a spectacular fallout, Makkhali Gosala went his own path. Gosala also had his own rivalry with the Buddhists, as he frequently appears in Buddhist texts, as one of the ‘six heretics’, who are unable to solve philosophical problems, before Buddha comes in and saves the day.

Ironically, since all the Ajivika texts have been lost, we only know of them and their beliefs from the Buddhist and Jain sources, which don't paint a very positive picture of this rival sect. It’s no surprise then that the Ajivikas have been portrayed as ‘Charlatans’ and their beliefs trashed. We do know that they were fatalistic, and their central tenet was of ‘Niyati’ or Fate. They believed that there was no free will and everything that has happened, is happening and will happen is entirely preordained and nothing could change it.

This fatalistic belief system had many takers at its time. It even travelled to Sri Lanka, where as per Mahavamsha, the chronicle of Sinhala kings, King Pandukabhaya built a ‘House of Ajivakas’ (Ajivakanam Gruham) at the capital, Anuradhapura.

Such was the popularity of the Ajivika faith,  that by the 1st century BCE  the Ajivikas  were considered a serious threat to Buddhism.

Ajivikas thrived under the patronage of the Nanda and Mauryan kings but saw a spectacular fall after that. In fact, by 5th century CE, the Ajivikas were completely wiped out in North India, though we don’t know exactly why. However, it did thrive in the South far longer. The great Tamil epics. Silpattakam refers to the flourishing Ajivika community in Madurai, while Manimekalai speaks of the great Ajivika teachers at Vanji (Tirukarur near Kochi), the capital of the Chera  kingdom.

After the Avijikas faded off, the Barabar caves were occupied by Buddhist, Jains and Hindus. Today, these caves are a popular tourist spot for visitors to Gaya. But most are unaware, that what they are looking at as they gaze at these caves, is the last vestiges of a lost religion.

Here is the link of Video uploaded by 'Mystery History' on Youtube which tells everything about this Ancient Cave:

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.