Programming Guides › Programming Guide for C › Agent API › How to Access a Resource Using the Agent API

How to Access a Resource Using the Agent API

After the Agent API has been initialized, the agent can start accepting requests from its users, such as receiving GET requests for URLs.

The following steps describe what is required for an agent to grant access to a resource. The outcome of most steps can be cached to improve agent performance. The agent can choose to cache as little as possible or as much as possible.

To grant user access to a resource

1. Accept a user request to access a resource. This is the application-specific request. For example, the Web Agent can accept a user's GET request for a URL.
2. Determine if the requested resource is protected by calling Sm_AgentApi_IsProtected(). If the resource is protected, the Policy Server returns the required credentials that must be obtained from the user 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.

   Collect the required credentials from the user and authenticate the user by calling Sm_AgentApi_Login(). After 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 pre-defined 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.

3. Validate that the user has access to the requested resource by calling Sm_AgentApi_Authorize(). After successful authorization, the Policy Server returns response attributes, including resource-specific privileges. These response attributes are policy driven and can include user profile data, static or dynamic privileges or any other data that was designated by a policy administrator. The user's authorization information for the requested resource is available and can be cached to speed up future requests.
4. (Optional) Log the transactions for authentication and authorization by calling Sm_AgentApi_Audit() if the agent performs authorizations out of its cache.
5. Allow the user to access the resource when the user's identity is known, authorization has been verified and the required entitlements obtained.
6. (Optional) Issue a management request by calling Sm_AgentApi_DoManagement(). This is an optional step that is used to poll the Policy Server for update commands. In response to a command, agents can update encryption keys or flush caches.
7. Release all API instances by calling Sm_AgentApi_UnInit() for each API instance. This closes TCP connections to all Policy Servers.

The Agent API does not provide a facility for caching in a manner that enforces session validity. By choosing to cache user sessions or resource-specific privileges, the agent becomes obligated to perform its own session management during each user request, because caching on the agent removes the need to contact the Policy Server to perform session validation or resource authorizations or both.