The web agent functions defined in <am_web.h> are:
Initializes the 3.0 web agent by loading the bootstrap properties file.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_init(const char *agent_bootstrap_file const char *agent_config_file);
This function takes the following parameter:
Pointer to the agent bootstrap file which resides on the machine local to the agent.
Pointer to the agent configuration file which resides on the same machine as OpenSSO Enterprise.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the call was successful.
If any error occurs, the type of error indicated by the status value.
Initializes an agent by creating the agent profile object and performing agent authentication to receive the initial agent configuration data from either OpenSSO Enterprise or the local configuration file.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_agent_init(boolean_t *pAgentAuthenticated);
This function takes the following parameter:
is the agent authenticated.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the query parameter was found in the URL.
If any other error occurred.
Builds an advice response.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_build_advice_response(const am_policy_result_t *policy_result, const char *redirect_url, char **advice_response);
This function takes the following parameter:
Pointer to an am_policy_result_t data type.
See am_policy_result_t for information.
Pointer to a redirect URL.
Pointer to a pointer to the location of the advice response.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the query parameter was found in the URL.
If any other error occurred.
Retrieves a user's SSOToken.
In cases of cross domain single sign-on, OpenSSO Enterprise sends out a user's SSOToken using POST. This method uses POST to retrieve the SSOToken and set it in the foreign domain.
#include "am_web.h" M_WEB_EXPORT am_status_t am_web_check_cookie_in_post(void ** args, char ** dpro_cookie, char ** request_url, char **orig_req, char *method, char *response, boolean_t responseIsCookie, am_status_t (*set_cookie)(const char *, void **), void (*set_method)(void **, char *), void* agent_config );
This function takes the following parameter:
Pointer to a pointer to agent defined parameters.
Pointer to a pointer to the OpenSSO Enterprise cookie.
Pointer to a pointer to the CDSSO URL.
Pointer to a pointer to the original request method.
Pointer to the changed method name.
Pointer to the response which will hold the POST data.
Returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If using Liberty Alliance Project specifications.
If OpenSSO Enterprise POST data.
Function pointer used to set the cookie in the foreign domain.
Function pointer used to reset the original method in the request.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the query parameter was found in the URL.
If any other error occurred.
Retrieves the cookie from a query string.
In older versions of this product, when performing CDSSO, the cookie was part of the query string.
AM_WEB_EXPORT am_status_t am_web_check_cookie_in_query(void **args, char **dpro_cookie, const char *query, char **request_url, char ** orig_req, char *method, am_status_t (*set_cookie)(const char *, void **), void (*set_method)(void **, char *), void* agent_config );
This function takes the following parameter:
Pointer to a pointer to agent defined parameters.
Pointer to a pointer to the OpenSSO Enterprise cookie.
Pointer to the query.
Pointer to a pointer to the CDSSO URL.
Pointer to a pointer to the original request method.
Pointer to a pointer to the changed method name.
Function pointer used to set the cookie in the foreign domain.
Function pointer used to reset the original method in the request.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the query parameter was found in the URL.
If any other error occurred.
Cleans up a post_urls_t data type.
See post_urls_t for more information.
#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_urls_t data type.
This function returns no values.
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 one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the cleanup was successful.
If any error occurs, the type of error indicated by the status value.
Clears the profile, session and response attributes maps.
#include "am_web.h" AM_WEB_EXPORT void am_web_clear_attributes_map(am_policy_result_t *result);
This function takes the following parameter:
Pointer to the am_policy_result_t
This function returns no values.
Creates an HTML form that submits the POST data with 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, void* agent_config);
This function takes the following parameters:
Pointer to the unique key identifying a POST data entry. It is used to remove post data once the page is re-posted.
Pointer to a browser encoded string representing the POST data entry.
Pointer to the POST destination URL.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns char * as the POST form to be submitted.
Constructs a post_urls_t data type during preservation of POST data.
A post_urls_t data type contains a dummy POST URL, an action URL and a unique key. The dummy URL is filtered by the Server Application Function (SAF) to identify POST preservation redirects from general redirects. All three of these variables are required for POST preservation.
#include "am_web.h" AM_WEB_EXPORT post_urls_t * am_web_create_post_preserve_urls(const char *request_url, void* agent_config);
This function takes the following parameter:
Pointer to the request URL for POST in the HTTP request.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns a post_urls_t data type. See post_urls_t for information.
Deletes the referenced object from the agent configuration data stored in the agent configuration cache.
#include "am_web.h" AM_WEB_EXPORT void am_web_delete_agent_configuration(void*);
This function takes no parameters.
This function deletes the latest configuration data, referenced by an object for a particular agent, from the agent configuration cache.
Sets the OpenSSO Enterprise cookie (called iPlanetDirectoryPro) for each domain configured in the com.sun.am.policy.agents.config.cookie.domain.list property in the agent configuration properties.
am_web_do_cookie_domain_set() builds the set-cookie header for each domain, and calls the callback function declared in setFunc to set the cookie. In CDSSO, the callback function is called by am_web_check_cookie_in_query() and am_web_check_cookie_in_post() to set the cookie in the response.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_do_cookie_domain_set(am_status_t (*setFunc)( const char *, void **), void **args, const char *cookie void* agent_config);
This function takes the following parameters:
Function pointer with which the user can define their own function for setting the cookie in the foreign domain. The implementation defines the parameters.
Pointer to a pointer to agent defined parameters.
Pointer to the cookie.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns a value of the am_status_t enumeration (defined in the <am_types.h> header file).
Resets the cookies in a response before redirecting it for authentication to the OpenSSO Enterprise login page.
This function resets the cookies specified in the agent configuration properties and invokes the set action that the agent passes in for each of them. It is enabled by setting the following properties:
com.sun.am.policy.agents.config.cookie.reset.enable: This property must be set to true if the web agent needs to reset cookies in the response before redirecting them to OpenSSO Enterprise for authentication. By default it is set to false.
com.sun.am.policy.agents.config.cookie.reset.list: This property (used only if com.sun.am.policy.agents.config.cookie.reset.enable is enabled) contains a comma-separated list of cookies that need to be included in the response redirected to OpenSSO Enterprise.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_do_cookies_reset(am_status_t (*setFunc)( const char *, void **), void **args, void* agent_config);
This function takes the following parameters:
Function pointer with which the user can define their own function for setting the cookie in the foreign domain. The implementation defines the parameters.
Pointer to a pointer to agent defined parameters.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns a value of the am_status_t enumeration (defined in the <am_types.h> header file).
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:
Pointer to the memory.
This function returns no value.
Retrieves the name of the server host for the agent.
#include "am_web.h" AM_WEB_EXPORT const char * am_web_get_agent_server_host(void* agent_config);
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns then name of the server host.
Retrieves the latest configuration data from the agent configuration cache. The returned instance gets used to serve requests.
#include "am_web.h" AM_WEB_EXPORT void* am_web_get_agent_configuration();
This function takes no parameters.
This function returns the latest configuration data, for a particular agent, from the agent configuration cache.
Retrieves the port used by the agent on the server host.
#include "am_web.h" AM_WEB_EXPORT int am_web_get_agent_server_port(void* agent_config);
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns a port number.
Determines if the auth-type value DSAME should be replaced by Basic in the Policy Agent 2.2 for Microsoft IIS 6.0.
The Policy Agent 2.2 for Microsoft IIS 6.0 is defined in <am_web.h> as having auth-type value equal to DSAME.
#define AM_WEB_AUTH_TYPE_VALUE "DSAME"
DSAME is a hard-coded value representing all OpenSSO Enterprise authentication types other than Basic.
#include "am_web.h" AM_WEB_EXPORT const char * am_web_get_authType(void* agent_config);
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns either DSAME or Basic.
Retrieves the name of the OpenSSO Enterprise cookie.
#include "am_web.h" AM_WEB_EXPORT const char * am_web_get_cookie_name(void* agent_config);
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns the name of the OpenSSO Enterprise cookie.
Retrieves the URL of the OpenSSO Enterprise Notification Service.
#include "am_web.h" AM_WEB_EXPORT const char * am_web_get_notification_url(void* agent_config);
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns the URL of the OpenSSO Enterprise Notification Service.
Gets the value of the specified parameter from the specified request 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:
Pointer to the request URL that holds the parameter.
Pointer to the name of the parameter.
Pointer to a pointer to be filled with the value of the param_name parameter, if found.
This function also returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the query parameter was found in the URL.
If any other error occurred.
The returned parameter value should be freed by the caller using am_web_free().
Parses the host request header field for a server host name, port, protocol, query parameter, and URI to return the requested URL to the web agent.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_get_request_url(const char *host_hdr, const char *protocol, const char *hostname, size_t port, const char *uri, const char *query, char **req_url, void* agent_config);
This function takes the following parameters:
Pointer to the host header string of the HTTP request as passed from the browser.
Pointer to the protocol used by the web container of the resource being requested.
Pointer to the name of the host on which the resource being requested.
Value based on the size_t defined in the standard <stddef.h> header file that reflects the port number of the resource being requested.
Pointer to the URI of the HTTP request.
Most URLs have this basic form: protocol://server:port/request-URI. The request-URI portion of the URL is used by the web server to identify the document.
The query string appended to the request URL, if any. For example, if the URL is http://www.example.com?a=b&c=d, the value of this parameter would be a=b&c=d.
Pointer to a pointer to the OUT parameter to be populated with the value of the URL string to be used by the agent.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the query parameter was found in the URL.
If any other error occurred.
Returns the single sign-on token from the specified Security Assertion Markup Language (SAML) assertion.
am_web_get_token_from_assertion() is used to retrieve the cookie sent by OpenSSO Enterprise in a SAML assertion.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_get_token_from_assertion(char *assertion, char **token, void* agent_config);
This function takes the following parameters:
Pointer to the SAML assertion as an XML string.
Pointer to a pointer containing the single sign-on token identifier.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If successful.
Otherwise.
The returned identifier should be freed using am_web_free().
Returns a string representing a login URL or access denied URL to which the web agent should redirect.
am_web_get_redirect_url() has been deprecated and must not be used. It is supported for backward compatibility only.
am_web_get_url_to_redirect() may redirect the user to the login URL or the access denied URL. The URL is appropriate to the provided status code and advice map returned by the Policy SDK. If redirecting to the login URL, the URL will include existing information specified in the URL from the configuration file (for example, the organization name) as well as the specified goto parameter value which will be used by OpenSSO Enterprise after the user has successfully authenticated. The last parameter reserved must be passed with NULL.
If the URL returned is not NULL, the caller of this function must call am_web_free_memory(void *) to free the pointer.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_get_url_to_redirect(am_status_t status, const am_map_t advice_map, const char *goto_url, const char* method, void *reserved, char ** redirect_url, void* agent_config);
This function takes the following parameters:
The status from am_web_is_access_allowed().
See am_web_is_access_allowed().
Any advice map from policy evaluation results.
Pointer to the original URL which the user attempted to access.
Pointer to the original HTTP method: GET or POST.
This parameter is not currently used.
Pointer to a pointer containing the resulting OpenSSO Enterprise redirect URL.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If successful.
Otherwise.
Returns the value of the logged-in user.
#include "am_web.h" AM_WEB_EXPORT char * am_web_get_user_id_param(void* agent_config);
This function takes the following parameters:
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns the value of the logged-in user.
Handles notification data received by a web agent.
am_web_handle_notification() generates logging messages for the event and any error that may occur during the processing of the notification.
#include "am_web.h" AM_WEB_EXPORT void am_web_handle_notification(const char *data, size_t data_length, void* agent_config);
This function takes the following parameters:
Pointer to the notification message as an XML string.
Value based on the size_t defined in the standard <stddef.h> header file that reflects the length of the notification message.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns no value.
URL decodes the specified 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:
Pointer to the URL encoded string.
Value based on the size_t defined in the standard <stddef.h> header file that reflects the length of the string.
This function returns the URL decoded value of the URL encoded string, or NULL if an error occurred.
The returned value should be freed by calling am_web_free().
Evaluates the access control policies for a specified web resource and action against those for a specified user.
#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, void* agent_config);
This function takes the following parameters:
Pointer to the session token from the OpenSSO Enterprise cookie. This parameter may be NULL if there is no cookie present.
Pointer to the web resource URL. This parameter may not be NULL.
Pointer to the path information in the web resource URL, if any.
Pointer to the action (GET, POST, etc.) being performed on the specified resource URL. This parameter may not be NULL.
Pointer to the IP address of the client attempting to access the specified resource URL. If client IP validation is turned on, this parameter may not be NULL.
A map object containing additional information about the user attempting to access the specified resource URL. This parameter may not be NULL.
An output parameter where the am_map_t can be stored if the policy evaluation produces any advice information. This parameter may not be NULL. See am_map_t for more information.
Pointer to a policy result object.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the evaluation was performed successfully and access is allowed.
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 session 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 a boolean specifying whether cross domain single sign-on is enabled in the agent’s configuration file.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_cdsso_enabled(void* agent_config);
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If cross domain single sign-on is enabled.
Otherwise.
Detects whether a cookie is present.
This function will most probably be invoked in a loop. A cookie name and value is passed and the implementation checks whether the cookie is already listed. If not, the new cookie name and value are appended. If present, the value of the cookie name is updated.
#include "am_web.h" AM_WEB_EXPORT int am_web_is_cookie_present(const char *cookie, const char *value, char **new_cookie);
This function takes the following parameters:
Pointer to a cookie.
Pointer to a value.
Pointer to a pointer to the location of the new cookie.
This function returns one of the following integers as defined in <am_web.h>:
#define AM_WEB_COOKIE_EXIST 2 #define AM_WEB_COOKIE_MODIFIED 1 #define AM_WEB_COOKIE_ABSENT 0 #define AM_WEB_COOKIE_ERROR -1
Returns a boolean specifying whether debug is enabled.
am_web_is_debug_on() specifies whether 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 one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If the log level is set to anything greater than 0.
Otherwise.
Returns a boolean specifying whether the given IP address is defined as one where no authentication or authorization is required.
IP addresses that are not enforced are defined in the com.sun.am.policy.agents.config.notenforced_client_ip_list property in the agent configuration properties. If the IP address from where the request was issued is not enforced, the request goes through without authentication or authorization.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_in_not_enforced_ip_list(const char *ip, void* agent_config);
This function takes the following parameter:
Pointer to the IP address.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If the IP is in the not enforced IP address list.
Otherwise.
Returns a boolean specifying whether the URL being accessed by the user is in the not enforced list.
URLs that are not enforced are defined in the com.sun.am.policy.agents.config.notenforced_list property in the agent configuration properties. If the URL is not enforced, the request goes through without authentication or authorization.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_in_not_enforced_list(const char *url, const char *path_info, void* agent_config);
This function takes the following parameters:
Pointer to the URL being accessed.
Pointer to the path information in the URL being accessed, if any.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If the URL is in the not enforced list.
Otherwise.
Returns a boolean specifying whether the specified URL is a logout URL.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_logout_url(const char *url, void* agent_config);
This function takes the following parameter:
Pointer to a URL.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If the specified URL is a logout URL.
Otherwise.
Returns a boolean specifying whether 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 one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If the log level is set to 5.
Otherwise.
Returns a boolean specifying whether the given URL is the Notification Service URL for the web agent as configured in the agent configuration properties.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_notification(const char *request_url void* agent_config);
This function takes the following parameter:
Pointer to the Notification Service URL
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If the URL is the Notification Service URL of the agent as set in the agent configuration proeprties.
Otherwise.
Returns the value of the com.sun.identity.agents.config.iis.owa.enable property.
Outlook Web Access (OWA) is a web mail service installed on Microsoft Internet Information Services 6.0. OWA interacts with the Exchange server to retrieve e-mail, calender contacts, and the like. A policy agent can be used to provide SSO for OWA.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_owa_enabled(void* agent_config);
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If OWA is enabled.
Otherwise.
Used to convert incoming http and https protocol to https. Returns the value of the com.sun.identity.agents.config.iis.owa.enable.change.protocol property. The property can have a value of either true or false; the default value is false.
Outlook Web Access (OWA) is a web mail service installed on Microsoft Internet Information Services 6.0. OWA interacts with the Exchange server to retrieve email, calender contacts, and the like. A policy agent can be used to provide SSO for OWA.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_owa_enabled_change_protocol(void* agent_config);
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If the protocol was changed.
Otherwise.
Returns the value of the com.sun.identity.agents.config.iis.owa.enable.session_timeout_url property, used to redirect to a custom session timeout page
Outlook Web Access (OWA) is a web mail service installed on Microsoft Internet Information Services 6.0. OWA interacts with the Exchange server to retrieve email, calender contacts, and the like. A policy agent can be used to provide SSO for OWA.
#include "am_web.h" AM_WEB_EXPORT char * am_web_is_owa_enabled_session_timeout_url(void* agent_config);
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns the URL of the custom session timeout page.
Returns a boolean specifying whether POST data preservation is enabled for clients in the agent configuration properties.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_postpreserve_enabled(void* agent_config);
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If POST data preservation is on.
If POST data preservation is off.
Determines if the com.sun.am.policy.agents.config.override_host and the com.sun.am.policy.agents.config.override_port properties are set for the proxy agent.
These properties are defined in the agent configuration properties.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_proxy_override_host_port_set(void* agent_config);
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If set.
Otherwise.
Returns a boolean specifying whether the requested URL is a valid fully qualified domain name (FQDN) resource as configured in the agent configuration properties. For example, myhost.mydomain.com.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_is_valid_fqdn_url(const char *url, void* agent_config);
Pointer to a URL.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If the URL is using a fully qualified domain name.
Otherwise.
Log the given message regardless of the log level set in the agent configuration properties.
#include "am_web.h" AM_WEB_EXPORT void am_web_log_always(const char *fmt, ...);
This function takes the following parameter:
Pointer to a formatted string message as in printf.
This function returns no values.
Log the given access allowed or denied message to the OpenSSO Enterprise logs.
#include "am_web.h" AM_WEB_EXPORT boolean_t am_web_log_auth(am_web_access_t access_type, const char *fmt, ... void* agent_config);
This function takes the following parameters:
One of the following values of the am_web_access_t enumeration as defined:
#include "am_web.h" typedef enum { AM_ACCESS_DENY = 0, AM_ACCESS_ALLOW } am_web_access_t;
Pointer to a formatted string message as in printf.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
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 parameter:
Pointer to a formatted string message as in printf.
This function returns no values.
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 parameter:
Pointer to a formatted string message as in printf.
This function returns no values.
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 parameter:
Pointer to a formatted string message as in printf.
This function returns no values.
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:
Pointer to a formatted string message as in printf.
This function returns no values.
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:
Pointer to a formatted string message as in printf.
This function returns no values.
Resets cookie configured for reset on user logout.
The reset function passed in is called for each cookie configured for reset. If the function failed for any cookie, the last failed status is returned.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_logout_cookies_reset(am_status_t (*setFunc)( const char *, void **), void **args, void* agent_config);
This function takes the following parameters:
Function pointer with which the user can define their own function for setting the cookie in the foreign domain. The implementation defines the parameters.
Pointer to a pointer to agent defined parameters.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns no values.
Converts a am_web_req_method_t number to a string.
This function is used for logging the method in the local debug logs. It takes in a method name and returns a string value (such as GET, or POST).
#include "am_web.h" AM_WEB_EXPORT const char * am_web_method_num_to_str(am_web_req_method_t method);
This function takes the following parameter:
One of the following values of the am_web_req_method_t enumeration as defined:
#include "am_web.h" typedef enum { AM_WEB_REQUEST_UNKNOWN, AM_WEB_REQUEST_GET, AM_WEB_REQUEST_POST, AM_WEB_REQUEST_HEAD, AM_WEB_REQUEST_PUT, AM_WEB_REQUEST_DELETE, AM_WEB_REQUEST_TRACE, AM_WEB_REQUEST_OPTIONS } am_web_req_method_t;
More information on these request methods can be found in http://www.faqs.org/rfcs/rfc2068.html.
This function returns a pointer to the string. If the number passed is not recognized, UNKNOWN is returned.
Converts a am_web_req_method_t string to a number.
This function does the opposite of the previously defined am_web_method_num_to_str(). See am_web_method_num_to_str() for details.
#include "am_web.h" AM_WEB_EXPORT const char * am_web_method_num_to_str(am_web_req_method_t method);
This function takes the following parameter:
One of the following values of the am_web_req_method_t enumeration as defined:
#include "am_web.h" typedef enum { AM_WEB_REQUEST_UNKNOWN, AM_WEB_REQUEST_GET, AM_WEB_REQUEST_POST, AM_WEB_REQUEST_HEAD, AM_WEB_REQUEST_PUT, AM_WEB_REQUEST_DELETE, AM_WEB_REQUEST_TRACE, AM_WEB_REQUEST_OPTIONS } am_web_req_method_t;
More information on these request methods can be found in http://www.faqs.org/rfcs/rfc2068.html.
This function returns a pointer to the number If the string is not recognized, AM_WEB_REQUEST_UNKNOWN is returned.
Cleans up am_web_postcache_data_t data type.
#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 parameter:
Pointer to am_web_postcache_data_t data type.
This function returns no value.
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, void* agent_config);
This function takes the following parameters:
Pointer to the POST data preservation key for every entry.
Pointer to the am_web_postcache_data_t data type.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If the insertion was successful.
Otherwise.
Looks up 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, void* agent_config);
This function takes the following parameters:
Pointer to the key to search POST data entry in POST data structure.
Pointer to the am_web_postcache_data_t data type storing the POST data.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
If the search was successful.
Otherwise.
Removes data from the POST cache.
#include "am_web.h" AM_WEB_EXPORT void am_web_postcache_remove(const char *key, void* agent_config);
This function takes the following parameter:
Pointer to the key of the entry to be removed.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns no value.
Processes a request access check and returns a HTTP result to be rendered by the agent.
The render status is returned in the render_sts argument.
#include "am_web.h" AM_WEB_EXPORT am_web_result_t am_web_process_request(am_web_request_params_t *req_params, am_web_request_func_t *req_func, am_status_t *render_sts, void* agent_config);
This function takes the following parameters:
Pointer to a am_web_request_params_t data type.
Pointer to a am_web_request_func_t data type.
Pointer to one of the values of the am_status_t enumeration as defined in the <am_types.h> header file.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
One of the following values of the am_web_result_t enumeration as defined:
#include "am_web.h" typedef enum { AM_WEB_RESULT_OK, /* access check was OK */ AM_WEB_RESULT_OK_DONE, /* OK and handled (for ex. notification) */ AM_WEB_RESULT_FORBIDDEN, /* access forbidden */ AM_WEB_RESULT_REDIRECT, /* redirected */ AM_WEB_RESULT_ERROR /* internal error */ } am_web_result_t;
Removes those extra parameters from an authenticated request.
When a user returns from CDSSO authentication, the request contains a list of parameters that were added when the user was authenticated. am_web_remove_authnrequest() removes these extra parameters so the request is forwarded to applications as it originally came from the browser.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_remove_authnrequest(char* inpString, char **outString );
This function takes the following parameters:
Pointer to the URL received after CDSSO authentication.
Pointer to a pointer to the location of the new URL without the parameters.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If successful.
The type of error indicated by the status value.
The value returned should be freed using am_web_free().
Removes the given query parameter from the URL, if present.
#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:
Pointer to the original URL.
Pointer to the query parameter to be removed
Pointer to a pointer to the location of the new URL without the query parameter.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the call was successful.
If any error occurs, the type of error indicated by the status value.
The value returned should be freed using am_web_free().
Processes attr_response_map from a am_policy_result_t data type and performs the set action.
This function replaces am_web_do_result_attr_map_set() which is deprecated. It needs to be explicitly declare to use it. See <am_web.h> for more information.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_result_attr_map_set(am_policy_result_t *result, am_web_result_set_header_func_t setHeaderFunc, am_web_result_set_header_attr_in_response_func_t setCookieRespFunc, am_web_result_set_header_attr_in_request_func_t setCookieReqFunc, am_web_get_cookie_sync_func_t getCookieSyncFunc, void **args, void* agent_config);
This function takes the following parameters:
Pointer to the am_policy_result_t.
See am_policy_result_t for more information.
Pointer to the am_web_result_set_header_func_t.
Pointer to the am_web_result_set_header_attr_in_response_func_t.
Pointer to the am_web_result_set_header_attr_in_request_func_t.
Pointer to the am_web_get_cookie_sync_func_t.
Pointer to a pointer to agent defined parameters.
An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the call was successful.
If any error occurs, the type of error indicated by the status value.
The value returned should be freed using am_web_free().
Returns the name of a am_web_result_t as a string.
#include "am_web.h" AM_WEB_EXPORT const char * am_web_result_num_to_str(am_web_result_t result);
This function takes the following parameter:
One of the following values of the am_web_result_t enumeration as defined:
#include "am_web.h" typedef enum { AM_WEB_RESULT_OK, /* access check was OK */ AM_WEB_RESULT_OK_DONE, /* OK and handled (for ex. notification) */ AM_WEB_RESULT_FORBIDDEN, /* access forbidden */ AM_WEB_RESULT_REDIRECT, /* redirected */ AM_WEB_RESULT_ERROR /* internal error */ } am_web_result_t;
This function returns a pointer to the string. For example, AM_WEB_RESULT_OK returns AM_WEB_RESULT_OK. If the result code passed is not recognized, Unknown result code is returned.
Sets the specified cookie in the cookie header of the request.
#include "am_web.h" AM_WEB_EXPORT am_status_t am_web_set_cookie(char *cookie_header, const char *set_cookie_value, char **new_cookie_header);
This function takes the following parameters:
Pointer to the cookie header.
Pointer to the cookie name and value in the set-cookie response header form. This value should be the same as that of the cookieValues parameter of the am_web_result_set_header_attr_in_request_func_t function.
Pointer to a pointer to the original cookie header, or a new cookie header value which needs to be freed by the caller. This value can be NULL.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If successful.
The type of error indicated by the status value.