This section contains the following topics:
Implement the JNI Java Agent API
Implement the Pure Java Agent API
How Web Agents Use the Agent API
Auditing Services and Transaction Tracking
A SiteMinder Agent is a client of the Agent API. The agent enforces access control policies served by the Policy Server. The Policy Server is a general-purpose policy engine with no specific knowledge of resources. The specific knowledge of resources is provided by SiteMinder agents. Agents establish resource semantics and act as gate keepers to protect resources from unauthorized users.
Different agent types protect different kinds of resources. Some agent types are pre-defined, standard agents that are shipped as part of the SiteMinder product—for example, the Web Agent, which provides HTTP access control for Web Servers. However, you can also use the Agent API to implement custom agents.
The Agent API lets you create a custom agent that can authenticate and authorize users in a variety of context-specific ways. For example, you could create an agent for FTP transfers that does the following:
Custom agents can participate in a single sign-on environment with standard SiteMinder Web Agents.
The Agent Type defines the behavior of an agent. After you have developed a custom agent, you must configure a new Agent Type for the agent in the Policy Server User Interface. For example, if you developed a custom FTP Agent, you would then need to configure an Agent Type for the FTP Agent in the Policy Server User Interface.
Note: For information on configuring an Agent Type for your custom agent, see the SiteMinder Programming Guide for C.
The primary point of access to the Java Agent API is the AgentAPI class. Several other classes are provided to hold data required by the AgentAPI class:
Applications that are built using the JNI Java AgentAPI either directly or indirectly (through another agent) are insulated from underlying implementation details, including:
Additional benefits provided by the Java Agent API include full session management support, automatic encryption key rollover, and real-time policy updates.
To implement the JNI Java Agent API
<install_path>\sdk\bin
<install_path>/sdk/bin
<install_path>/sdk/bin
<install_path>/sdk/bin
<install_path>/sdk/bin
Note: The Java Agent API is not available for HP10.
<install_path>\sdk\java
<install_path>/sdk/java
Add smjavaagentapi.jar to your CLASSPATH setting. When compiling, you can use the -classpath switch.
For an example, see java-build.bat or java-build.sh in the sample directory smjavaagentapi.
For an example, see java-run.bat or java-run.sh in the sample directory smjavaagentapi.
Applications that are built using the pure Java Agent API either directly or indirectly (through another agent) are insulated from underlying implementation details, including:
Additional benefits provided by the Java Agent API include full session management support, automatic encryption key rollover, and real-time policy updates.
To implement the pure Java Agent API
<install_path>\sdk\java
<install_path>/sdk/java
Add smagentapi.jar, crypto.jar, cryptoFIPS.jar to your CLASSPATH setting. When compiling, you can use the -classpath switch.
For an example, see java-build.bat or java-build.sh in the sample directory smjavaagentapi.
Backward compatibility
The pure Java Agent API maintains binary and source compatibility with the JNI Java Agent API. The pure Java Agent API supports all of the other SiteMinder Java SDK interfaces that rely on the Agent API for connectivity to the SiteMinder Policy Server, including the SiteMinder Policy Management API and the SiteMinder DMS API, in addition to extending the portability of those interfaces.
Configuration limitations
The pure Java Agent API does not change the configuration of either the SiteMinder Application Server Agents or any agents developed with the SiteMinder SDK. The configuration of the pure Java Agent API is identical to the configuration of the JNI Java Agent API with the following exceptions:
The pure Java Agent API supports detailed trace messages, which are printed to the console. These messages can be useful when running a command line tool that uses the Agent API, such as smreghost.
To enable trace messages, set a system property named enableDebug to "true". From the command line, add -Dcom.ca.siteminder.sdk.agentapi.enableDebug="true". For example:
>SM_SMREGHOST_CLASSPATH="c:\ca\sdk\java\smagentapi.jar;c:\ca\sdk\java\cryptoj.jar" >java -Dcom.ca.siteminder.sdk.agentapi.enableDebug="true" -classpath %SM_SMREGHOST_CLASSPATH% com.ca.siteminder.sdk.agentapi.SmRegHost -i 127.0.0.1 -hc host_conf1 -hn trustedhost3 -u siteminder -p firewall
Before an agent can perform work on behalf of its users, it must initialize connections to one or more Policy Servers by issuing the init() method. Through the InitDef parameter, you can specify connection parameters such as failover mode and connection pool size. This step creates TCP connections and 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 respect to the initialized API instance.
It is possible to initialize more than one API instance (for example, when working with Policy Servers that use separate policy stores).
Immediately after initialization, the agent should communicate its version information to the Policy Server by calling doManagement() with the constant MANAGEMENT_SET_AGENT_INFO set in the ManagementContextDef object. The actual information can be any string containing enough information about the agent, such as the build number, and the version number. The string is recorded in the Policy Server logs.
After the Agent API has been initialized, the agent can perform useful work. At this point it can start accepting requests from its users, such as receiving GET requests for URLs.
The agent must perform the following steps before granting a user access to a requested resource. The outcome of most steps can be cached to improve agent performance. The agent can choose to cache as little or as much as possible.
Accept a user request to access a resource. This is the application-specific request. For example, the Web Agent would accept a user’s GET request for a URL.
Call isProtected() to determine if the requested resource is protected.
If the resource is protected, the policy server returns the required credentials that must be obtained from the user in order to validate the user’s identity. If the resource is not protected, access to the requested resource should be allowed.
The outcome of this step can be cached.
Call login() to collect the required credentials from the user and to authenticate the user.
Upon successful authentication, the Policy Server creates a session and returns response attributes, including the unique session id and session specification. These response attributes are policy-driven and may include user profile data, static or dynamic privileges, a number of predefined authentication state attributes, or any other data that was designated by a policy administrator.
The agent can now perform session management by caching user session information and keeping track of session expiration.
Call authorize() to validate that the user has access to the requested resource.
Upon successful authorization, the policy server returns response attributes including resource-specific privileges. These response attributes are policy driven and may include user profile data, static or dynamic privileges, or any other data that was designated by a policy administrator.
At this point the user’s authorization information with respect to the requested resource is known and can be cached to speed up future requests.
Both the authentication and authorization steps log the relevant information about the user, the protected resource, and the agent. However, if the agent performs authorizations out of its cache, the transaction can still be logged through the audit() method.
Now that the user’s identity is known, authorization has been verified, and the required entitlements obtained, give the authorized user access to the resource.
This is an optional step that is used to poll the Policy Server for update commands. In response to a command, agents update encryption keys or flush caches or both.
When the agent is no longer needed, issue the unInit() method for each API instance. This closes TCP connections to all policy servers.
Note: The Agent API does not provide a facility for caching in a manner that enforces session validity. By choosing to cache user sessions and/or resource-specific privileges, the agent becomes obligated to perform its own session management during each user request. This is required, since caching on the agent removes the need to contact the SiteMinder Policy Server to perform session validation and/or resource authorizations.
The following figure shows the process flow that occurs when a Web Agent uses the Agent API:
The Java Agent API provides a rich set of services that let you develop sophisticated, secure, and robust agents. Building an agent involves using these services:
These services are accessed through the AgentAPI class.
Sessioning is used to maintain consistent user sessions across multi-tiered application environments.
AgentAPI methods that implement session services are:
Agents that perform session management use the sessioning services of the Java Agent API to create, delegate, validate, and terminate user sessions.
Note: For login and logout of SiteMinder administrators for Policy Server or DMS sessions, use the methods SmApiSession.login() and SmApiSession.logout() in the Utility package.
A session is created after a successful user login. Once created, a user session persists 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 is accomplished by saving and maintaining the user information in the session specification. This session specification represents a user session. It is the key to SiteMinder session management.
The SiteMinder environment where the user session was created is responsible for the creation, maintenance, and persistent storage of the session specification. For example, the Web Agent (HTTP environment) stores the session specification in an HTTP cookie.
Agents create sessions using login(). This method authenticates the user credentials and gets the information for session specification (including the unique session id). Once created, the session specification is updated on subsequent Java Agent API calls that also return updated expiration times. Agents can use this information to perform custom session management and keep track of session timeouts.
If your Web server’s user-tracking feature is enabled, the SiteMinder Policy Server issues an identity ticket in addition to the session specification. Identity tickets can be used for identity-based personalization when a user is accessing a resource protected by anonymous authentication schemes. Identity tickets never expire.
Another important feature that is seamlessly integrated with the sessioning mechanism is the SiteMinder universal ID. A universal ID identifies the user to an application in a SiteMinder environment through a unique identifier, such as a social security number or customer account number. The universal ID facilitates identification of users between old and new applications by delivering the user’s identification automatically, regardless of the application. Once configured on the Policy Server, a user’s universal id becomes part of the session specification and is made available to agents for the duration of the entire session.
Agents request validation of a session specification to make sure that a user session has neither expired nor been terminated or revoked. This can occur at any time during the session’s lifetime. Agents call AgentAPI.login() to validate a session specification.
When an application’s logic flow crosses application tiers, sessions may be delegated by passing the session specification between two agents. Each agent can choose to have the session specification validated.
A session is terminated in any of the following ways:
To terminate a session, the agent must discard the session specification. Once a session is terminated, the user must log in again to establish a new session.
Agents that perform access control functions use the authorization services of the AgentAPI class. These services enable clients to verify a user’s rights to access a resource, retrieve a user’s privileges with respect to specific resources, and determine the specific access control, if any, that is imposed upon 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 by the requesting agent and returns information about the user’s credentials.
Once the user’s identity is validated, the agent calls the authorize() method to determine if the requesting user has access to the requested resource. Agents can perform fine-grained access control by leveraging the collection of response attributes that this method retrieves.
Agents can keep track of and log all user activity during a session. Although much of a user’s activity is logged by the Policy Server, there are times when it may be necessary to log authorizations done out of agent cache. Agents call the audit() method to log such requests for resources.
By generating a unique transaction id, agents can correlate access control activity with application activity. The transaction id can be given to both the authorization and auditing methods so that the Policy Server would record the transaction-specific id associated with the application activity. This can be used for non-repudiation.
A management protocol exists between agents and the SiteMinder Policy Server. This protocol helps an agent manage its caches and encryption keys in a manner consistent with both SiteMinder policies and administrative changes on the Policy Server.
To request the latest agent commands, an agent calls the method doManagement() with MANAGEMENT_GET_AGENT_COMMANDS set in the ManagementContextDef object. Typically, this call is made every n seconds by a thread running in the background. The types of agent commands that can be retrieved are cache commands and encryption commands.
Cache commands inform the agent of any changes to its caches that may need to be made as a result of administrative updates to the Policy Server.
The cache commands are:
Encryption commands inform the agent of new encryption keys that are generated administratively or automatically by the Policy Server. Agents save secure state can use this protocol to keep track of the latest encryption keys.
The encryption commands are:
Tunnel services enable agents to establish secure communications with a callable service located on the Policy Server. This allows agents to perform custom actions over a secure, VPN-like channel without having to address issues such as encryption key management.
Response 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:
The well-known attributes are always returned by the Policy Server after certain calls such as login(). These attributes represent static, fixed data such as 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 for delivering static and dynamic data from the Policy Server to agents, which can distinguish between authentication and authorization attributes. The actual source of the data is defined on the Policy Server using the responses feature that can be configured to deliver data from a variety of sources. Data may include static information, information from a directory profile, or a custom Policy Server plug-in. Once the responses are properly configured, agents are capable of performing fine-grained access control as well as profile-driven personalization.
Based on a policy definition, response attributes can time out or be cached for the duration of the user session. The Policy Server delivers an attribute along with the TTL (Time-To-Live) value, calculated in seconds. If the agent is caching user sessions and/or authorizations, it is responsible for keeping the relevant attributes up to date. Agents issue the updateAttributes() method to update stale attributes.
In a single sign-on environment, a user who successfully authenticates through a given agent does not have to re-authenticate when accessing a realm protected by a different agent. When a custom agent is involved in a single sign-on environment, the two agents must be in the same cookie domain—for example, xxx.domainname.com.
Single sign-on is made possible through a single sign-on cookie named SMSESSION. This cookie is created and written to the user’s browser either by SiteMinder or by the custom agent.
Class AgentAPI contains two methods that allow custom agents to participate in a single sign-on environment with standard SiteMinder Web Agents:
The custom agent extracts the cookie’s contents, called a token, from an existing SMSESSION cookie and passes the token to this method. The method decrypts the token and extracts the specified information. This method can also be used to update the last-access timestamp in the token.
After the user successfully logs in through the custom agent, the custom agent passes information about the user to this method. The method creates an encrypted token from this user information and from session information returned from the login call. The custom agent writes the token to the SMSESSION cookie.
See the sample custom agent code for an example of setting up the parameters for the single sign-on methods and parsing the results. The sample custom agent code is located in the smjavaagentapi directory of <install_path>\sdk\samples.
Here is the typical sequence of events in a single sign-on environment when the initial login is through the custom agent:
Here is the typical sequence of events that occurs in a single sign-on environment when the initial login is performed through the standard SiteMinder Web Agent:
Custom agents created with the SiteMinder SDK v6.x can accept SMSESSION cookies 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 accept cookies created by a custom agent if the standard agent has been upgraded with the appropriate Siteminder Agent Quarterly Maintenance Release (QMR). For information about the QMR version required for each standard agent version, see the accompanying SDK release notes.
To enable a SiteMinder v4.x or v5.x agent with the appropriate QMR upgrade to accept SMSESSION cookies created by a custom agent, the standard agent’s Agent configuration file (LocalConfig.conf with IIS servers or WebAgent.conf with other servers) or central configuration object (for v5.x or higher) must contain the following entry:
AcceptTPCookie="yes"
Set AcceptTPCookie as follows:
Session information can consist of more than the session specification. Session information can include any information that the client application wants to associate with the user’s session.
Application-defined session information consists of name/value pairs called session variables. For example, business logic, certificate information, and SAML assertions for affiliate operations can all be stored as session variables and bound to the session ID.
The class AgentAPI provides the following methods for setting, retrieving, and deleting session variables:
Session variables are stored in a server-side database called the session store. The session store is managed by the Policy Server.
When a client application uses session variables:
For a client application to use session variables, both of the following prerequisites must be met:
When the user logs out and the agent discards the session specification, the session ends. In the case of a persistent session, SiteMinder removes all session information, including any session variables, from the session store.
To help prevent service interruptions, SiteMinder includes a failover feature. If the primary Policy Server fails and failover is enabled, a backup Policy Server takes over policy operations. Beginning with SiteMinder v6.0, failover can occur not only between Policy Servers, but between groups, or clusters, of Policy Servers.
The cluster functionality also improves server performance by providing dynamic load balancing between the servers in a cluster. With dynamic load balancing, policy operations are automatically distributed between the available servers in a cluster according to the performance capabilities of each server.
An agent running against Agent API v6.x can be associated with one or more Policy Servers, or with one or more clusters of Policy Servers, as follows:
In the ServerDef object for each clustered server, set clusterSeq() to the sequence number for the cluster. All servers in a cluster have the same cluster sequence number.
Behavior: Failover occurs between clusters of servers if multiple clusters are defined. Also, requests to servers within a cluster are sent according to the improved performance-based load-balancing techniques introduced with Agent API v6.0.
In the ServerDef object for each non-clustered server, set the method clusterSeq() to 0.
Behavior: Behavior is the same as in v5.x installations—that is, you can enable failover among the servers associated with the agent, or you can enable round-robin behavior among the servers.
When round-robin behavior is enabled, the improved performance-based load-balancing techniques introduced with Agent API v6.0 are used.
Note: The same agent cannot be associated with both clustered and non-clustered servers.
You can configure a cluster through the Agent API or through a host configuration object using the Policy Server User Interface. If you configure a cluster through the Agent API, be sure that the configuration does not conflict with any cluster configuration information that may be defined in the host configuration object.
You configure the individual servers or clusters of servers that the agent is associated with through the InitDef and ServerDef classes.
Cluster failover occurs according to the following configuration settings:
The failover threshold percentage applies to all clusters associated with the agent.
To determine the number of servers that the percentage represents in any given cluster, multiply the threshold percentage by the number of servers in the cluster, rounding to the nearest integer. For example, with a 60-percent failover threshold for a cluster of five servers, failover to the next cluster occurs when the number of available servers in the currently active cluster falls below 3.
Set through: InitDef constructor that contains the failOverThreshold parameter.
Set through: ServerDef.clusterSeq().
If your site uses clusters, you typically will have a primary cluster and one or more backup clusters.
The primary cluster is the cluster to which SiteMinder sends requests as long as the number of available servers in the cluster does not fall below the failover threshold. If there are not enough available servers in the primary cluster, failover to the next cluster in the cluster sequence occurs. If that cluster also fails, failover to the third cluster occurs, and so on.
If the number of available servers falls below the failover threshold in all clusters associated with the agent, policy operations do not stop. Requests are sent to the first cluster in the cluster sequence that has at least one available server.
For example, suppose an agent is associated with two clusters—C1 containing three servers, and C2 containing five servers.The failover threshold for any cluster associated with the agent is set at 60 percent.
The following table shows the minimum number of servers that must be available within each cluster:
|
Cluster |
Servers in Cluster |
Percentage |
Numeric |
|---|---|---|---|
|
C1 |
3 |
60 |
1 |
|
C2 |
5 |
60 |
3 |
If the number of available servers falls below the threshold in each cluster, so that C1 has no available servers and C2 has just two, the next incoming request will be dispatched to a C2 server with the best response time. After at least two of the three C1 servers are repaired, subsequent requests are load-balanced among the available C1 servers.
Agent API v6 is backwards-compatible with Agent API v5, allowing complete interoperability between v5/v6 agents and the v5/v6 Agent APIs.
Agents can enforce session timeouts or rely on the Policy Server to validate each request. Typically, caching of user sessions or privileges by the agent requires some form of timeout enforcement on the agent side. In this case, the agent is responsible for keeping track of last access time and knowing when the session is going to expire.
Agents that do not cache can leverage the Policy Server’s enforcement of timeouts. The following Java Agent API methods return the updated timeout information after every call:
|
Copyright © 2013 CA.
All rights reserved.
|
|