Sun Java System Identity Server 2004Q2 Developer's Reference |
Chapter 8
Web FunctionsThis chapter provides a reference to the functions in the C SDK intended for use by only web agents of Sun Java System Identity Server. 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()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 parameters:
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:
Value
Description
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:
Returns
This function returns char * with one of the following values:
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 parameters:
Returns
This function returns post_urls_t * with one of the following values:
Value
Description
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 parameters:
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 values:
Value
Description
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 values:
Parameter
Description
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 Identity Server 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:
Value
Description
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 Identity Server 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:
Value
Description
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:
Returns
This function returns am_status_t with one of the following values:
am_web_get_redirect_url()Returns a string representing the Identity Server 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 Identity Server 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:
Returns
This function returns am_status_t with one of the following values:
Value
Description
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 Identity Server 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:
Parameter
Description
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:
Value
Description
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:
Parameter
Description
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:
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 parameters:
Parameter
Description
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:
Value
Description
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:
Returns
This function returns am_status_t with one of the following values:
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:
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:
Returns
This function returns boolean_t with one of the following values:
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:
Returns
This function returns boolean_t with one of the following values:
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:
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:
Returns
This function returns am_web_is_notification with one of the following values:
Value
Description
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:
Value
Description
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:
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:
Returns
None
am_web_log_auth()Log the given access allowed or denied message to the Identity Server's 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:
Parameter
Description
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:
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:
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:
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:
Returns
None
am_web_log_max_debug()Log the given message at max 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:
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:
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:
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:
Parameter
Description
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:
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:
Returns
This function returns M_WEB_EXPORT boolean_t with one of the following values:
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:
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:
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If the call was successful.
AM_*
If any error occurs, the type of error indicated by the status value.