Chapter 9 Web Functions

This chapter provides a reference to the functions in the C SDK intended for use by only web agents of Sun Java^TM System Access Manager. Function summaries include a short description, syntax, parameters and returns.

The following functions are contained in the header file am_web.h:

• am_web_clean_post_urls()

• am_web_cleanup()

• am_web_create_post_page()

• am_web_create_post_preserve_urls()

• am_web_free_memory()

• am_web_get_agent_server_host()

• am_web_get_agent_server_port()

• am_web_get_cookie_name()

• am_web_get_notification_url()

• am_web_get_parameter_value()

• am_web_get_redirect_url()

• am_web_get_token_from_assertion()

• am_web_handle_notification()

• am_web_http_decode()

• am_web_init()

• am_web_is_access_allowed()

• am_web_is_cdsso_enabled()

• am_web_is_debug_on()

• am_web_is_in_not_enforced_ip_list()

• am_web_is_in_not_enforced_list()

• am_web_is_max_debug_on()

• am_web_is_notification()

• am_web_is_postpreserve_enabled()

• am_web_is_valid_fqdn_url()

• am_web_log_always()

• am_web_log_auth()

• am_web_log_debug()

• am_web_log_error()

• am_web_log_info()

• am_web_log_max_debug()

• am_web_log_warning()

• am_web_postcache_data_cleanup()

• am_web_postcache_insert()

• am_web_postcache_lookup()

• am_web_postcache_remove()

• am_web_remove_parameter_from_query()

am_web_clean_post_urls()

Cleans up data structure containing dummy post URL, action URL and unique key.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void am_web_clean_post_urls(post_urls_t *posturl_struct);

Parameters

This function takes the following parameter:

posturl_struct

Pointer to POST preservation URL data structure post_urls_t.

Returns

None

am_web_cleanup()

Cleans up any memory called by the am_web_* functions.

This should be called before a web agent exits.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_cleanup();

Parameters

This function does not take any parameters.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_web_create_post_page()

Creates the HTMLform with the Javascript that submits the POST with the invisible name value pairs.

Syntax

#include "am_web.h"
AM_WEB_EXPORT char * am_web_create_post_page(const char *key,
                         const char *postdata,
                         const char *actionurl);

Parameters

This function takes the following parameters:

key

Unique key to identify POST data entry. It is used to remove post data once the page is re-posted.

postdata

POST data entry as a browser encoded string actionurl.

actionurl

POST destination URL.

Returns

This function returns char * with one of the following values:

char *

POST form to be resubmitted.

am_web_create_post_preserve_urls()

Constructs dummy post URL, action URL and unique key.

Syntax

#include "am_web.h"
AM_WEB_EXPORT post_urls_t *
am_web_create_post_preserve_urls(const char *request_url);

Parameters

This function takes the following parameter:

request_url

The request URL for POST in the HTTP request.

Returns

This function returns post_urls_t * with one of the following value:

post_urls_t

Data structure that contains Dummy redirect URL, POST destination URL and POST preservation key.

Details

Dummy redirect URL is filtered by web server SAF to identify POST preservation redirects from general redirects. All three of these variables are required for POST preservation.

am_web_free_memory()

Frees memory previously allocated by a am_web_* routine.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_free_memory(void *memory);

Parameters

This function takes the following parameter:

memory

Memory allocated by an am_web_* routine to be freed.

Returns

None

am_web_get_agent_server_host()

Retrieves the name of the Agent Server Host.

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_get_agent_server_host();

Parameters

This function does not take any parameters.

Returns

This function returns const char * with one of the following value:

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_web_get_agent_server_port()

Retrieves the name of the Agent Server Port.

Syntax

#include "am_web.h"
AM_WEB_EXPORT int
am_web_get_agent_server_port();

Parameters

This function does not take any parameters.

Returns

This function returns int with one of the following value:

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_web_get_cookie_name()

Retrieves the name of the Access Manager cookie.

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_get_cookie_name();

Parameters

This function does not take any parameters.

Returns

This function returns const char * with one of the following values:

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_web_get_notification_url()

Retrieves the name of the Access Manager notification URL.

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_get_notification_url();

Parameters

This function does not take any parameters.

Returns

This function returns const char * with one of the following values:

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_web_get_parameter_value()

Gets the value of the given query parameter from the given URL.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_get_parameter_value(const char *inpQuery, 
                           const char *param_name, char **param_value);

Parameters

This function takes the following parameters:

inpQuery

URL to look for the query parameter.

param_name

Name of the query parameter.

param_value

Pointer to be filled with the value of the param_name query parameter in the given URL if found.

The returned parameter value should be freed by the caller using am_web_free().

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the query parameter was found in the URL.

AM_INVALID_ARGUMENT

If any of the arguments is NULL.

AM_NOT_FOUND

If the query parameter is not found.

AM_NO_MEMORY

If memory could not be allocated for the query parameter value.

AM_FAILURE

If any other error occurred.

am_web_get_redirect_url()

Returns a string representing the Access Manager URL that web agent should redirect to. For example, if the status is AM_INVALID_SESSION and CDSSO is not enabled, the redirect URL would be the Access Manager login URL as configured in the AMAgent.properties file and associated query parameters.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_get_redirect_url(am_status_t status,
                            const am_map_t advice_map,
                            const char *goto_url,
                          const char* function,
                            char ** redirect_url);

Parameters

This function takes the following parameters:

status

The status from am_web_is_access_allowed.

advice_map

Any advice map from policy evaluation results.

goto_url

Original URL accessed by the user, for IS to redirect user to after successful authentication with the Access Manager.

redirect_url

A pointer to contain the resulting Access Manager redirect URL.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

Details

The string may either redirect the user to the login URL or the access denied URL. If the redirection is to the login URL then the URL will include any existing information specified in the URL from the configuration file, like org value etc., followed by the specified goto parameter value, which will be used by Access Manager after the user has successfully authenticated.

If the redirect_url returned is NOT NULL, the caller of this function must call am_web_free_memory(void *) to free the pointer.

am_web_get_token_from_assertion()

Returns the SSO Token from the given SAML assertion.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_get_token_from_assertion(char *assertion, char **token);

Parameters

This function takes the following parameters:

assertion

The SAML assertion as an XML string.

token

Pointer to contain the SSO Token ID.

The returned SSO Token ID should be freed using am_web_free().

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_web_handle_notification()

Handles notification data received by an agent.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_handle_notification(const char *data,
                        size_t data_length);

Parameters

This function takes the following parameters:

data

The notification message as an XML string.

data_length

Length of the notification message.

Returns

None

Details

This code handles generating logging messages for the event and any error that may occur during the processing of the notification.

am_web_http_decode()

URL decodes the given URL encoded string.

Syntax

#include "am_web.h"
AM_WEB_EXPORT char *
am_web_http_decode(const char *string, size_t len);

Parameters

This function takes the following parameters:

string

The URL encoded string.

len

Length of the string.

Returns

This function returns the URL decoded value of the URL encoded string, or NULL if any error occurred.

The returned value should be freed by calling am_web_free().

am_web_init()

Initializes the Agent Toolkit.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_init(const char *config_file);

Parameters

This function takes the following parameter:

config_file

Path to the agent configuration file, for example, /etc/opt/AMAgent.properties .

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.

am_web_is_access_allowed()

Evaluates the access control policies for a specified web-resource and action.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t am_web_is_access_allowed(const char *sso_token,
                                                   const char *url, const char *path_info,
                                                   const char *action_name,
                                                   const char *client_ip,
                                                   const am_map_t env_parameter_map,
                                                   am_policy_result_t *result);

Parameters

This function takes the following parameters:

sso_token

The sso_token from the Access Manager cookie. This parameter may be NULL if there is no cookie present.

url

The URL whose accessibility is being determined. This parameter may not be NULL.

action_name

The action (GET, POST, etc.) being performed on the specified URL. This parameter may not be NULL.

client_ip

The IP address of the client attempting to access the specified URL. If client IP validation is turned on, then this parameter may not be NULL.

env_parameter_map

A map containing additional information about the user attempting to access the specified URL. This parameter ay not be NULL.

advices_map_ptr

An output parameter where an am_map_t can be stored if the policy evaluation produces any advice information. This parameter may not be NULL.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the evaluation was performed successfully and access is to be allowed to the specified resource.

AM_NO_MEMORY

If the evaluation was not successfully completed due to insufficient memory being available.

AM_INVALID_ARGUMENT

If any of the URL, action_name, env_parameter_map, or advices_map_ptr parameters is NULL or if client IP validation is enabled and the client_ip parameter is NULL.

AM_INVALID_SESSION

If the specified sso_token does not refer to a currently valid session

AM_ACCESS_DENIED

If the policy information indicates that the user does not have permission to access the specified resource or any error is detected other than the ones listed above.

am_web_is_cdsso_enabled()

Returns whether CDSSO is enabled in the agent’s configuration file.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_cdsso_enabled();

Parameters

This function takes no parameters.

Returns

This function returns true if CDSSO is enabled and false otherwise.

am_web_is_debug_on()

Returns debug is on, that is, if the log level is set to anything greater than 0.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_debug_on();

Parameters

This function takes no parameters.

Returns

This function returns boolean_t with one of the following values:

true

If the log level is set to anything greater than 0.

false

Otherwise.

am_web_is_in_not_enforced_ip_list()

Returns true if the given IP address is present in the list of not enforced IP addresses.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_in_not_enforced_ip_list(const char *ip);

Parameters

This function takes the following parameters:

ip

The IP address.

Returns

This function returns boolean_t with one of the following values:

true

If the IP is in the not enforced IP address list.

false

Otherwise.

am_web_is_in_not_enforced_list()

Returns true if the URL being accessed by the user is in the not enforced list.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t am_web_is_in_not_enforced_list(const char *url,
                                                       const char *path_info);

Parameters

This function takes the following parameters:

url

The URL being accessed by the user

path_info

Path info of the URL.

Returns

This function returns boolean_t with one of the following values:

true

If the URL is in the not enforced list.

false

Otherwise.

am_web_is_max_debug_on()

Returns true if the log level is set to 5.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_max_debug_on();

Parameters

This function takes no parameters.

Returns

This function returns boolean_t with one of the following values:

true

If the log level is set to 5.

false

Otherwise.

am_web_is_notification()

Returns true if the given URL is the notification URL for the web agent as configured in AMAgent.properties.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_notification(const char *request_url);

Parameters

This function takes the following parameter:

request_url

The request URL

Returns

This function returns am_web_is_notification with one of the following values:

true

If the URL is the notification URL of the agent as set in AMAgent.properties.

false

Otherwise.

am_web_is_postpreserve_enabled()

Finds out if POST data preservation is enabled by clients through AMAgent.Properties.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_postpreserve_enabled();

Parameters

This function takes no parameters

Returns

This function returns boolean_t with one of the following values:

True

If POST preservation is switched on.

False

If POST preservation is switched off.

am_web_is_valid_fqdn_url()

Returns if the requested URL is a Valid FQDN resource, that is if the host is a fully qualified domain name such as myhost.mydomain.com as configured in AMAgent.properties.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t am_web_is_valid_fqdn_url(const char *url);

Parameters

This function takes no parameters.

Returns

This function returns boolean_t with one of the following values:

true

If the URL is using a fully qualified domain name.

false

Otherwise.

am_web_log_always()

Log the given message regardless of the log level set in AMAgent.properties.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void am_web_log_always(const char *fmt, ...);

Parameters

This function takes the following parameters:

fmt

Formatted string as in printf.

Returns

None

am_web_log_auth()

Log the given access allowed or denied message to the Access Manager logs.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_log_auth(am_web_access_t access_type, const char *fmt, ...);

Parameters

This function takes the following parameters:

access_type

AM_ACCESS_ALLOW or AM_ACCESS_DENY.

message

Any message for the log.

Returns

This function returns boolean_t with one of the following values:

true

If the call was successful.

false

Otherwise.

am_web_log_debug()

Log the given message at the debug level.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_log_debug(const char *fmt, ...);

Parameters

This function takes the following parameters:

fmt

A formatted string as in printf.

Returns

None

am_web_log_error()

Log the given message at the debug log level.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_log_error(const char *fmt, ...);

Parameters

This function takes the following parameters:

fmt

A formatted string as in printf to be logged.

Returns

None

am_web_log_info()

Log the given message at the info log level.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_log_info(const char *fmt, ...);

Parameters

This function takes the following parameters:

fmt

Formatted string like in printf to be logged.

Returns

None

am_web_log_max_debug()

Log the given message at maximum debug level.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_log_max_debug(const char *fmt, ...);

Parameters

This function takes the following parameters:

fmt

Formatted string as in printf to be logged.

Returns

None

am_web_log_warning()

Log the given message at the warning log level.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_log_warning(const char *fmt, ...);

Parameters

This function takes the following parameters:

fmt

A formatted string as in printf to be logged.

Returns

None

am_web_postcache_data_cleanup()

Cleans up data structure containing post string value, redirect URL.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_postcache_data_cleanup(am_web_postcache_data_t * const postentry_struct);

Parameters

This function takes the following parameters:

const

am_web_postcache_data_tPointer to POST data entry

Returns

None

am_web_postcache_insert()

Inserts POST data entry in the POST cache.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t am_web_postcache_insert(const char *key,
                        const am_web_postcache_data_t *value);

Parameters

This function takes the following parameters:

key

POST data preservation key for every entry.

value

Structure to store POST data value and redirect URL.

Returns

This function returns boolean_t with one of the following values:

True

If insertion was successful.

False

If insertion was not successful.

am_web_postcache_lookup()

Looks up POST data in the POST cache.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_postcache_lookup(const char *key,
            am_web_postcache_data_t *postdata_entry);

Parameters

This function takes the following parameters:

key

Key to search POST data entry in POST data structure

Returns

This function returns M_WEB_EXPORT boolean_t with one of the following values:

am_web_postcache_data_t

Data structure containing POST data and redirect URL

am_web_postcache_remove()

Removes POST data from the POST cache.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_postcache_remove(const char *key);

Parameters

This function takes the following parameters:

key

Key to remove an entry from POST data structure.

Returns

None

am_web_remove_parameter_from_query()

Removes the given query parameter from the URL, if it is in the URL.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_remove_parameter_from_query(const char* inpString,
                                   const char *remove_str,
                                   char **outString );

Parameters

This function takes the following parameters:

inpString

The original URL

remove_str

The query parameter to be removed

outString

Pointer to location where a new URL with the query parameter removed will be inserted.

The value returned should be freed using am_web_free().

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the call was successful.

AM_*

If any error occurs, the type of error indicated by the status value.