The Agent API provides a rich set of services that let you develop sophisticated, secure, and robust agents. Building an agent involves using these services:
A session is created after a successful user login. Once created, a user session persists until it is terminated. To maintain consistent user sessions in a multi-tiered application environment, a user session specification is maintained by the Web Agent (not the Policy Server). The session specification is also called the session ticket. The session specification represents a user session and is the key to SiteMinder Session Management. The environment in which the user session was created is responsible for persistent storage of the session specification. For example, the Web Agent (HTTP environment) stores the session specification in an HTTP cookie.
SiteMinder’s universal ID is integrated with the sessioning mechanism. A universal ID identifies the user to an application in a SiteMinder environment using a unique identifier, such as a 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. When configured on the Policy Server, a user’s universal id is part of the session specification and is made available to agents for the duration of the entire session.
Agents create sessions using Sm_AgentApi_Login(). This function authenticates the user credentials and returns the session specification and unique session id in Sm_AgentApi_Session_t. The session specification is updated on subsequent Agent API calls that also return the 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, SiteMinder 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.
When an application’s logic flow crosses application tiers, sessions can be delegated by passing the session specification between two agents. Each agent can choose to have the session specification validated.
The session specification is validated 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 Sm_AgentApi_Login() to validate a session specification.
A session is terminated after a user logs out and the agent discards the session specification, when the session expires, or when the session is revoked. When a session is terminated, the user must log in again to establish a new session.
You should terminate a session if a user is disabled after a session has begun. To find a user's disabled state, call Sm_AgentApi_Login() to validate the session.
To terminate a session, the agent calls Sm_AgetnApi_Logout(). Note that any memory allocated for the session specification (Sm_AgentApi_Session_t) must be deallocated.
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 Agent API provides the following functions 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.
Advantages of Session Variables
When a client application uses session variables:
Requirements for Using Session Variables
For a client application to use session variables, both of the following prerequisites must be met:
End of Session Cleanup
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.
Agents can enforce session timeouts themselves 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 the 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 Agent API methods return the updated timeout information after every call:
Agents that perform access control functions use authorization services of the Agent API. These services enable clients to determine what access control is imposed on resources, verify users rights to access resources, and retrieve users privileges for specific resources.
Whether a resource is protected can be determined by calling the Sm_AgentApi_IsProtected() method. This method accepts a resource that is served by the requesting agent, and returns information about the credentials required for authentication.
After the user’s identity has been validated, agents call the Sm_AgentApi_Authorize() method to determine if the requesting user has access to the requested resource. Agents can perform fine-grained access control by testing the values of the response attributes returned by this method.
A facility is provided for agents to keep track of all user activity during a session. Although much of the activity is logged by the Policy Server, there are times when it may be necessary to log authorizations done out of agent cache. Agents can call the Sm_AgentApi_Audit() method to log 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 Policy Server. This protocol helps agents manage its caches and encryption keys in a manner consistent with policies and administrative changes on the Policy Server.
Agents issue the Sm_AgentApi_DoManagement() call with the SM_AGENTAPI_MANAGEMENT_GET_AGENT_COMMANDS command to request the latest agent commands. Typically, this is done every N seconds by a thread running in the background. The types of agent commands that can be received 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. These agent commands are:
Encryption commands inform the agent of new encryption keys that are generated automatically by the Policy Server or administratively. Agents that need to save secure state can leverage this protocol to keep track of the latest encryption keys. These agent 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 deal with issues such as encryption and key management.
|
Copyright © 2015 CA Technologies.
All rights reserved.
|
|