This chapter provides a reference to the functions in the C SDK intended for use by only web agents of Sun JavaTM 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:
Cleans up data structure containing dummy post URL, action URL and unique key.
#include "am_web.h" AM_WEB_EXPORT void am_web_clean_post_urls(post_urls_t *posturl_struct);
This function takes the following parameter:
Pointer to POST preservation URL data structure post_urls_t.
None
Cleans up any memory called by the am_web_* functions.
This should be called before a web agent exits.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_cleanup();
This function does not take any parameters.
This function returns am_status_t with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
Creates the HTMLform with the Javascript that submits the POST with the invisible name value pairs.
#include "am_web.h" AM_WEB_EXPORT char * am_web_create_post_page(const char *key, const char *postdata, const char *actionurl);
This function takes the following parameters:
Unique key to identify POST data entry. It is used to remove post data once the page is re-posted.
POST data entry as a browser encoded string actionurl.
POST destination URL.
This function returns char * with one of the following values:
POST form to be resubmitted.
Constructs dummy post URL, action URL and unique key.
#include "am_web.h" AM_WEB_EXPORT post_urls_t * am_web_create_post_preserve_urls(const char *request_url);
This function takes the following parameter:
The request URL for POST in the HTTP request.
This function returns post_urls_t * with one of the following value:
Data structure that contains Dummy redirect URL, POST destination URL and POST preservation key.
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.
Frees memory previously allocated by a am_web_* routine.
#include "am_web.h" AM_WEB_EXPORT void am_web_free_memory(void *memory);
This function takes the following parameter:
Memory allocated by an am_web_* routine to be freed.
None
Retrieves the name of the Agent Server Host.
#include "am_web.h" AM_WEB_EXPORT const char * am_web_get_agent_server_host();
This function does not take any parameters.
This function returns const char * with one of the following value:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
Retrieves the name of the Agent Server Port.
#include "am_web.h" AM_WEB_EXPORT int am_web_get_agent_server_port();
This function does not take any parameters.
This function returns int with one of the following value:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
Retrieves the name of the Access Manager cookie.
#include "am_web.h" AM_WEB_EXPORT const char * am_web_get_cookie_name();
This function does not take any parameters.
This function returns const char * with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
Retrieves the name of the Access Manager notification URL.
#include "am_web.h" AM_WEB_EXPORT const char * am_web_get_notification_url();
This function does not take any parameters.
This function returns const char * with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
Gets the value of the given query parameter from the given URL.
#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);
This function takes the following parameters:
URL to look for the query parameter.
Name of the query parameter.
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().
This function returns am_status_t with one of the following values:
If the query parameter was found in the URL.
If any of the arguments is NULL.
If the query parameter is not found.
If memory could not be allocated for the query parameter value.
If any other error occurred.
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.
#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);
This function takes the following parameters:
The status from am_web_is_access_allowed.
Any advice map from policy evaluation results.
Original URL accessed by the user, for IS to redirect user to after successful authentication with the Access Manager.
A pointer to contain the resulting Access Manager redirect URL.
This function returns am_status_t with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
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.
Returns the SSO Token from the given SAML assertion.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_get_token_from_assertion(char *assertion, char **token);
This function takes the following parameters:
The SAML assertion as an XML string.
Pointer to contain the SSO Token ID.
The returned SSO Token ID should be freed using am_web_free().
This function returns am_status_t with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
Handles notification data received by an agent.
#include "am_web.h" AM_WEB_EXPORT void am_web_handle_notification(const char *data, size_t data_length);
This function takes the following parameters:
The notification message as an XML string.
Length of the notification message.
None
This code handles generating logging messages for the event and any error that may occur during the processing of the notification.
URL decodes the given URL encoded string.
#include "am_web.h" AM_WEB_EXPORT char * am_web_http_decode(const char *string, size_t len);
This function takes the following parameters:
The URL encoded string.
Length of the string.
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().
Initializes the Agent Toolkit.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_init(const char *config_file);
This function takes the following parameter:
Path to the agent configuration file, for example, /etc/opt/AMAgent.properties .
This function returns am_status_t with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.
Evaluates the access control policies for a specified web-resource and action.
#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);
This function takes the following parameters:
The sso_token from the Access Manager cookie. This parameter may be NULL if there is no cookie present.
The URL whose accessibility is being determined. This parameter may not be NULL.
The action (GET, POST, etc.) being performed on the specified URL. This parameter may not be NULL.
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.
A map containing additional information about the user attempting to access the specified URL. This parameter ay not be NULL.
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.
This function returns am_status_t with one of the following values:
If the evaluation was performed successfully and access is to be allowed to the specified resource.
If the evaluation was not successfully completed due to insufficient memory being available.
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.
If the specified sso_token does not refer to a currently valid session
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.
Returns whether CDSSO is enabled in the agent’s configuration file.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_cdsso_enabled();
This function takes no parameters.
This function returns true if CDSSO is enabled and false otherwise.
Returns debug is on, that is, if the log level is set to anything greater than 0.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_debug_on();
This function takes no parameters.
This function returns boolean_t with one of the following values:
If the log level is set to anything greater than 0.
Otherwise.
Returns true if the given IP address is present in the list of not enforced IP addresses.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_in_not_enforced_ip_list(const char *ip);
This function takes the following parameters:
The IP address.
This function returns boolean_t with one of the following values:
If the IP is in the not enforced IP address list.
Otherwise.
Returns true if the URL being accessed by the user is in the not enforced list.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_in_not_enforced_list(const char *url, const char *path_info);
This function takes the following parameters:
The URL being accessed by the user
Path info of the URL.
This function returns boolean_t with one of the following values:
If the URL is in the not enforced list.
Otherwise.
Returns true if the log level is set to 5.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_max_debug_on();
This function takes no parameters.
This function returns boolean_t with one of the following values:
If the log level is set to 5.
Otherwise.
Returns true if the given URL is the notification URL for the web agent as configured in AMAgent.properties.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_notification(const char *request_url);
This function takes the following parameter:
The request URL
This function returns am_web_is_notification with one of the following values:
If the URL is the notification URL of the agent as set in AMAgent.properties.
Otherwise.
Finds out if POST data preservation is enabled by clients through AMAgent.Properties.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_postpreserve_enabled();
This function takes no parameters
This function returns boolean_t with one of the following values:
If POST preservation is switched on.
If POST preservation is switched off.
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.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_valid_fqdn_url(const char *url);
This function takes no parameters.
This function returns boolean_t with one of the following values:
If the URL is using a fully qualified domain name.
Otherwise.
Log the given message regardless of the log level set in AMAgent.properties.
#include "am_web.h" AM_WEB_EXPORT void am_web_log_always(const char *fmt, ...);
This function takes the following parameters:
Formatted string as in printf.
None
Log the given access allowed or denied message to the Access Manager logs.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_log_auth(am_web_access_t access_type, const char *fmt, ...);
This function takes the following parameters:
AM_ACCESS_ALLOW or AM_ACCESS_DENY.
Any message for the log.
This function returns boolean_t with one of the following values:
If the call was successful.
Otherwise.
Log the given message at the debug level.
#include "am_web.h" AM_WEB_EXPORT void am_web_log_debug(const char *fmt, ...);
This function takes the following parameters:
A formatted string as in printf.
None
Log the given message at the debug log level.
#include "am_web.h" AM_WEB_EXPORT void am_web_log_error(const char *fmt, ...);
This function takes the following parameters:
A formatted string as in printf to be logged.
None
Log the given message at the info log level.
#include "am_web.h" AM_WEB_EXPORT void am_web_log_info(const char *fmt, ...);
This function takes the following parameters:
Formatted string like in printf to be logged.
None
Log the given message at maximum debug level.
#include "am_web.h" AM_WEB_EXPORT void am_web_log_max_debug(const char *fmt, ...);
This function takes the following parameters:
Formatted string as in printf to be logged.
None
Log the given message at the warning log level.
#include "am_web.h" AM_WEB_EXPORT void am_web_log_warning(const char *fmt, ...);
This function takes the following parameters:
A formatted string as in printf to be logged.
None
Cleans up data structure containing post string value, redirect URL.
#include "am_web.h" AM_WEB_EXPORT void am_web_postcache_data_cleanup(am_web_postcache_data_t * const postentry_struct);
This function takes the following parameters:
am_web_postcache_data_tPointer to POST data entry
None
Inserts POST data entry in the POST cache.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_postcache_insert(const char *key, const am_web_postcache_data_t *value);
This function takes the following parameters:
POST data preservation key for every entry.
Structure to store POST data value and redirect URL.
This function returns boolean_t with one of the following values:
If insertion was successful.
If insertion was not successful.
Looks up POST data in the POST cache.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_postcache_lookup(const char *key, am_web_postcache_data_t *postdata_entry);
This function takes the following parameters:
Key to search POST data entry in POST data structure
This function returns M_WEB_EXPORT boolean_t with one of the following values:
Data structure containing POST data and redirect URL
Removes POST data from the POST cache.
#include "am_web.h" AM_WEB_EXPORT void am_web_postcache_remove(const char *key);
This function takes the following parameters:
Key to remove an entry from POST data structure.
None
Removes the given query parameter from the URL, if it is in the URL.
#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 );
This function takes the following parameters:
The original URL
The query parameter to be removed
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().
This function returns am_status_t with one of the following values:
If the call was successful.
If any error occurs, the type of error indicated by the status value.