Skip to ContentSun and Oracle Channel Sun How to Buy Log In

Sun OpenSSO Enterprise 8.0 C API Reference for Application and Web Policy Agent Developers

Contained Within

Sun OpenSSO Enterprise 8.0

Find More Documentation

Featured Support Resources

Download this book in PDF (1531 KB)

Chapter 8 Web Agent Data Types and Functions

Sun OpenSSO Enterprise contains public data types and functions intended for use by Sun web agents. They can also be used to develop proprietary web agents. Reference summaries include a short description, syntax, parameters and returns. Prototypes for the types and functions are contained in the <am_web.h> header file. This chapter contains the following sections:

Web Agent API for C

The web agent application programming interface (API) for C are used by web agents to interact with OpenSSO Enterprise services such as the Authentication Service, the Session Service, the Policy Service, and the Logging Service. In order to use the data types and functions described herein, you should be familiar with web agents in general and how they work. The following books provide information for this purpose:

Web Agent Data Types

The web agent data types defined in <am_web.h> are:

`am_web_add_header_in_response_t`

Defines a data type for the am_web_add_header_in_response_func_t function pointer.

Details

Syntax

#include "am_web.h"
typedef struct {
    am_web_add_header_in_response_func_t func;
    void **args;
} am_web_add_header_in_response_t;

Members

The structure has the following components:

func: Pointer to am_web_add_header_in_response_func_t function.
args: Pointer to a pointer to agent defined parameters.

`am_web_free_post_data_t`

Defines a data type for the am_web_free_post_data_t function pointer.

Details

Syntax

#include "am_web.h"
typedef struct {
    am_web_free_post_data_func_t func;
    void **args;
} am_web_free_post_data_t;

Members

am_web_free_post_data_t has the following components:

func: Pointer to am_web_free_post_data_func_t function.
args: Pointer to a pointer to agent defined parameters.

`am_web_get_post_data_t`

Defines a data type for the am_web_get_post_data_t function pointer.

Details

Syntax

#include "am_web.h"
typedef struct {
    am_web_get_post_data_func_t func;
    void **args;
} am_web_get_post_data_t;

Members

am_web_get_post_data_t has the following components:

func: Pointer to am_web_get_post_data_func_t function.
args: Pointer to a pointer to agent defined parameters.

`am_web_postcache_data_t`

Data type for temporarily storing POST data sent by the web agent to the OpenSSO Enterprise Session Service.

Details

Policy agents use the POST method to communicate with the Session Service. For information, see Session Validation in Sun OpenSSO Enterprise 8.0 Technical Overview.

Syntax

#include "am_web.h"
typedef struct am_web_postcache_data {
    char *value;
    char *url;
} am_web_postcache_data_t;

Members

am_web_postcache_data_t has the following components:

value: Pointer to the string value of the POST data.
url: Pointer to the destination URL of the POST.

`am_web_render_result_t`

Defines a data type for the am_web_render_result_func_t function pointer.

Details

Syntax

#include "am_web.h"
typedef struct {
    am_web_render_result_func_t func;
    void **args;
} am_web_render_result_t;

Members

am_web_render_result_t has the following components:

func: Pointer to the am_web_render_result_func_t function.
args: Pointer to a pointer to agent defined parameters.

`am_web_request_func_t`

Defines an all-inclusive data type for the function pointers used by the web agent.

Syntax

#include "am_web.h"
typedef struct {
    am_web_get_post_data_t get_post_data;
    am_web_free_post_data_t free_post_data;
    am_web_set_user_t set_user;
    am_web_set_method_t set_method;
    am_web_set_header_in_request_t set_header_in_request;
    am_web_add_header_in_response_t add_header_in_response;
    am_web_render_result_t render_result;
} am_web_request_func_t;

Members

am_web_request_func_t has the following components:

get_post_data: See am_web_get_post_data_t.
free_post_data: See am_web_free_post_data_t.
set_user: See am_web_set_user_t.
set_method: See am_web_set_method_t.
set_header_in_request: See am_web_set_header_in_request_t.
add_header_in_response: See am_web_add_header_in_response_t.
render_result: See am_web_render_result_t.

`am_web_request_params_t`

Represents the parameters of an HTTP request passed to a web server from a client browser.

Details

This structure represents the parameters of the HTTP request and includes am_web_req_method_t which defines the action to be performed on the resource (GET, POST, DELETE, etc.).

Syntax

#include "am_web.h"
typedef struct {
    char *url;                      /* The full request URL */
    char *query;                    /* query string if any */
    am_web_req_method_t method;     /* request method */
    char *path_info;                /* path info if any */
    char *client_ip;                /* client IP if any */
    char *cookie_header_val;        /* the cookie header value if any */
    void *reserved;                 /* reserved - do not set this */
} am_web_request_params_t;

Members

am_web_request_params_t has the following components:

url

Pointer to the URL of the resource.

query

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.

method

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.

path_info

The path information in the request URL, if any.

client_ip

Pointer to the IP address from which the request was sent.

cookie_header_val

Pointer to the cookie header.

reserved

Do not set this.

`am_web_set_header_in_request_t`

Defines a data type for the am_web_render_result_func_t function pointer.

Details

Syntax

#include "am_web.h"
typedef struct {
    am_web_set_header_in_request_func_t func;
    void **args;
} am_web_set_header_in_request_t;

Members

am_web_set_header_in_request_t has the following components:

func: Pointer to am_web_set_header_in_request_func_t function.
args: Pointer to a pointer to agent defined parameters.

`am_web_set_method_t`

Defines a data type for the am_web_set_method_func_t function pointer.

Details

Syntax

#include "am_web.h"
typedef struct {
    am_web_set_method_func_t func;
    void **args;
} am_web_set_method_t;

Members

am_web_set_method_t has the following components:

func: Pointer to the am_web_set_method_func_t function.
args: Pointer to a pointer to agent defined parameters.

`am_web_set_user_t`

Defines a data type for the am_web_set_user_func_t function pointer.

Details

Syntax

#include "am_web.h"
typedef struct {
    am_web_set_user_func_t func;
    void **args;
} am_web_set_user_t;

Members

am_web_set_user_t has the following components:

func: Pointer to am_web_set_user_func_t function.
args: Pointer to a pointer to agent defined parameters.

`post_urls_t`

A session information object defining the URLs used by the web agent to communicate with OpenSSO Enterprise.

Syntax

#include "am_web.h"
typedef struct post_urls {
    char *dummy_url;
    char *action_url;
    char *post_time_key;
} post_urls_t;

Members

post_urls_t has the following components:

dummy_url

Pointer to a dummy URL to redirect for POST data preservation.

Note –

POST data preservation is supported only on Policy Agent 2.2 for Sun Java System Web Server 6.1. The feature allows for submitted POST data to be preserved. See Preserving POST Data on Sun Java System Web Server 7.0 Only in Sun Java System Access Manager Policy Agent 2.2 Guide for Sun Java System Web Server 6.1 for more information.

action_url

Pointer to destination URL for a POST request.

post_time_key

Pointer to a unique key used to tag a POST data entry.

Web Agent Function Pointers

The web agent function pointers must be written before calling the am_web_process_request() function to process a request. The function pointers defined in <am_web.h> are:

`am_web_add_header_in_response_func_t`

Adds (or sets) an HTTP header in a response.

Details

If a header of the same name already exists, it should be replaced with this header.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_add_header_in_response_func_t)
                               (void **args,
                                const char *name,
                                const char *val);

Parameters

This function takes the following parameter:

args: Pointer to a pointer to agent defined parameters.
name: Pointer to the name of the header.
val: Pointer to the value of the header.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the header was successfully added.
Appropriate am_status_t code: Otherwise.

`am_web_free_post_data_func_t`

Frees the data retrieved by am_web_get_post_data_func_t.

Details

The POST data can be NULL if it is not needed.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_free_post_data_func_t)
                               (void **args,
                                char *data);

Parameters

This function takes the following parameter:

args: Pointer to a pointer to agent defined parameters.
data: Pointer to the data.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the data was successfully freed.
Warning: If not successfully freed, the status will be logged as a warning but ignored.

`am_web_get_cookie_sync_func_t`

Synchronizes two cookies.

Details

Currently, this is a dummy function. Do not use.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_get_cookie_sync_func_t)(
                                const char *cookieName,
                                char **dproCookie,
                                void **args);

Parameters

This function takes the following parameter:

cookieName: Pointer to the cookie with which the OpenSSO Enterprise cookie will be synchronized.
dproCookie: Pointer to a pointer to the OpenSSO Enterprise cookie.
args: Pointer to a pointer to agent defined parameters.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the data was successfully freed.
Warning: If not successfully freed, the status will be logged as a warning but ignored.

`am_web_get_post_data_func_t`

Retrieves post data.

Details

The returned POST data must be NULL terminated and will be freed by calling am_web_free_post_data_func_t.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_get_post_data_func_t)
                               (void **args,
                                char **data);

Parameters

This function takes the following parameter:

args: Pointer to a pointer to agent defined parameters.
data: Pointer to a pointer to the data.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the data was successfully retrieved.
HTTP internal error: Otherwise

`am_web_render_result_func_t`

Renders an HTML page based on the result of a web agent's enforcement.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_render_result_func_t)
                               (void **args,
                                am_web_result_t http_result,
                                char *data);

Parameters

This function takes the following parameter:

args

Pointer to a pointer to agent defined parameters.

http_result

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;

For AM_WEB_RESULT_OK_DONE, the web agent should return an HTTP status code 200 OK and the body of the HTTP response should be set to the string in the data parameter. For AM_WEB_RESULT_REDIRECT, the web agent should return an HTTP status code 302 and the Location header should be set to the redirect URL in the data argument. More information on these request methods can be found in http://www.faqs.org/rfcs/rfc2068.html.

data

Pointer to a string defining user data, a URL, or other data.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If page was successfully rendered.
Warning: If not successfully freed, the status will be logged as a warning but ignored.

`am_web_result_set_header_func_t`

Sets LDAP attributes in an HTTP header.

Details

This function will be called when com.sun.am.policy.agents.config.profile.attribute.fetch.mode in the agent configuration properties is set to HTTP_HEADER. This property specifies if additional user profile attributes should be introduced into the request. Possible values are:

NONE
HTTP_HEADER
HTTP_COOKIE

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_result_set_header_func_t)(
                                 const char *key,
                                 const char *attrValues, 
                                 void **args);

Parameters

This function takes the following parameter:

key: Pointer to the key to which the value will be set.
attrValues: Pointer to a string representing the values to be set.
args: Pointer to a pointer to agent defined parameters.

Returns

This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file) including:

AM_SUCCESS: If the header was successfully set.

`am_web_result_set_header_attr_in_request_func_t`

Sets LDAP attributes defined in the request's HTTP cookie header.

Details

This function will be called when com.sun.am.policy.agents.config.profile.attribute.fetch.mode in the agent configuration properties is set to HTTP_COOKIE. This property specifies if additional user profile attributes should be introduced into the request. Possible values are:

NONE
HTTP_HEADER
HTTP_COOKIE

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_result_set_header_attr_in_request_func_t)(
                                const char *cookieValues,
                                void **args);

Parameters

This function takes the following parameter:

cookieValues: Pointer to string representing the values in the cookie.
args: Pointer to a pointer to agent defined parameters.

Returns

This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file) including:

AM_SUCCESS: If the header was successfully set.

`am_web_result_set_header_attr_in_response_func_t`

Sets LDAP attributes defined in the response's HTTP cookie header.

Details

NONE
HTTP_HEADER
HTTP_COOKIE

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_result_set_header_attr_in_response_func_t)(
                     const char *cookieValues,
                     void **args);

Parameters

This function takes the following parameter:

cookieValues: Pointer to string representing the values in the cookie.
args: Pointer to a pointer to agent defined parameters.

Returns

This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file) including:

AM_SUCCESS: If the header was successfully set.

`am_web_set_header_in_request_func_t`

Sets an HTTP header in a request.

Details

If a header of the same name already exists it should be replaced with this header.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_set_header_in_request_func_t)(
                     void **args, 
                     const char *name, 
                     const char *val);

Parameters

This function takes the following parameter:

args: Pointer to a pointer to agent defined parameters.
name: Pointer to the name of the header.
val: Pointer to the value of the header.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If header was successfully added.
Warning: If not successfully freed, the status will be logged as a warning but ignored.

`am_web_set_method_func_t`

Sets the request method to be used by a web agent during cross domain single sign-on (CDSSO).

Details

In cases of CDSSO actions between OpenSSO Enterprise and web agents, the POST request method is used by the web agent. am_web_set_method_func_t is required to change the request method to POST, if necessary, from the method defined in the original HTTP request. See Cross-Domain Single Sign-On Session in Sun OpenSSO Enterprise 8.0 Technical Overview for additional information.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_set_method_func_t)(
                                void **args, 
                                am_web_req_method_t method);

Parameters

This function takes the following parameter:

args

Pointer to a pointer to agent defined parameters.

method

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.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the method was successfully set.
HTTP forbidden result: Otherwise.

`am_web_set_user_func_t`

Sets the user.

Details

The implementation code sets the user.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_set_user_func_t)(
                     void **args, 
                     const char *user);

Parameters

This function takes the following parameter:

args: Pointer to a pointer to agent defined parameters.
user: Pointer to the user login.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If user was successfully set.
HTTP forbidden result: Otherwise.

Web Agent Functions

The web agent functions defined in <am_web.h> are:

`am_web_init()` for Agents 3.0

Initializes the 3.0 web agent by loading the bootstrap properties file.

Syntax

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

Parameters

This function takes the following parameter:

agent_bootstrap_file: Pointer to the agent bootstrap file which resides on the machine local to the agent.
agent_config_file: Pointer to the agent configuration file which resides on the same machine as OpenSSO Enterprise.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the call was successful.
AM_*: If any error occurs, the type of error indicated by the status value.

`am_agent_init()`

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.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_agent_init(boolean_t *pAgentAuthenticated);

Parameters

This function takes the following parameter:

pAgentAuthenticated: is the agent authenticated.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the query parameter was found in the URL.
AM_*: If any other error occurred.

`am_web_build_advice_response()`

Builds an advice response.

Syntax

#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);

Parameters

This function takes the following parameter:

policy_result

Pointer to an am_policy_result_t data type.

Note –

See am_policy_result_t for information.

redirect_url

Pointer to a redirect URL.

advice_response

Pointer to a pointer to the location of the advice response.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the query parameter was found in the URL.
AM_*: If any other error occurred.

`am_web_check_cookie_in_post()`

Retrieves a user's SSOToken.

Details

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.

Syntax

#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
);

Parameters

This function takes the following parameter:

args

Pointer to a pointer to agent defined parameters.

dpro_cookie

Pointer to a pointer to the OpenSSO Enterprise cookie.

request_url

Pointer to a pointer to the CDSSO URL.

orig_req

Pointer to a pointer to the original request method.

method

Pointer to the changed method name.

response

Pointer to the response which will hold the POST data.

responseIsCookie

Returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If using Liberty Alliance Project specifications.
B_FALSE: If OpenSSO Enterprise POST data.

set_cookie

Function pointer used to set the cookie in the foreign domain.

set_method

Function pointer used to reset the original method in the request.

agent_config

An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the query parameter was found in the URL.
AM_*: If any other error occurred.

`am_web_check_cookie_in_query()`

Retrieves the cookie from a query string.

Details

In older versions of this product, when performing CDSSO, the cookie was part of the query string.

Syntax

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
);

Parameters

This function takes the following parameter:

args: Pointer to a pointer to agent defined parameters.
dpro_cookie: Pointer to a pointer to the OpenSSO Enterprise cookie.
query: Pointer to the query.
request_url: Pointer to a pointer to the CDSSO URL.
orig_req: Pointer to a pointer to the original request method.
method: Pointer to a pointer to the changed method name.
set_cookie: Function pointer used to set the cookie in the foreign domain.
set_method: Function pointer used to reset the original method in the request.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the query parameter was found in the URL.
AM_*: If any other error occurred.

`am_web_clean_post_urls()`

Cleans up a post_urls_t data type.

Details

See post_urls_t for more information.

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_urls_t data type.

Returns

This function returns no values.

`am_web_cleanup()`

Cleans up any memory called by the am_web_* functions.

Details

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 one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the cleanup was successful.
AM_*: If any error occurs, the type of error indicated by the status value.

`am_web_clear_attributes_map()`

Clears the profile, session and response attributes maps.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void am_web_clear_attributes_map(am_policy_result_t *result);

Parameters

This function takes the following parameter:

result: Pointer to the am_policy_result_t

Returns

This function returns no values.

`am_web_create_post_page()`

Creates an HTML form that submits the POST data with 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,
                        void* agent_config);

Parameters

This function takes the following parameters:

key: Pointer to the unique key identifying a POST data entry. It is used to remove post data once the page is re-posted.
postdata: Pointer to a browser encoded string representing the POST data entry.
actionurl: Pointer to the POST destination URL.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns char * as the POST form to be submitted.

`am_web_create_post_preserve_urls()`

Constructs a post_urls_t data type during preservation of POST data.

Details

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.

Syntax

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

Parameters

This function takes the following parameter:

request_url: Pointer to the request URL for POST in the HTTP request.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns a post_urls_t data type. See post_urls_t for information.

`am_web_delete_agent_configuration()`

Deletes the referenced object from the agent configuration data stored in the agent configuration cache.

Syntax

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

Parameters

This function takes no parameters.

Returns

This function deletes the latest configuration data, referenced by an object for a particular agent, from the agent configuration cache.

`am_web_do_cookie_domain_set()`

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.

Details

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.

Syntax

#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);

Parameters

This function takes the following parameters:

setFunc: Function pointer with which the user can define their own function for setting the cookie in the foreign domain. The implementation defines the parameters.
args: Pointer to a pointer to agent defined parameters.
cookie: Pointer to the cookie.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns a value of the am_status_t enumeration (defined in the <am_types.h> header file).

`am_web_do_cookies_reset()`

Resets the cookies in a response before redirecting it for authentication to the OpenSSO Enterprise login page.

Details

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.

Syntax

#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);

Parameters

This function takes the following parameters:

setFunc: Function pointer with which the user can define their own function for setting the cookie in the foreign domain. The implementation defines the parameters.
args: Pointer to a pointer to agent defined parameters.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns a value of the am_status_t enumeration (defined in the <am_types.h> header file).

`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: Pointer to the memory.

Returns

This function returns no value.

`am_web_get_agent_server_host()`

Retrieves the name of the server host for the agent.

Syntax

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

Parameters

agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns then name of the server host.

`am_web_get_agent_configuration()`

Retrieves the latest configuration data from the agent configuration cache. The returned instance gets used to serve requests.

Syntax

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

Parameters

This function takes no parameters.

Returns

This function returns the latest configuration data, for a particular agent, from the agent configuration cache.

`am_web_get_agent_server_port()`

Retrieves the port used by the agent on the server host.

Syntax

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

Parameters

agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns a port number.

`am_web_get_authType()`

Determines if the auth-type value DSAME should be replaced by Basic in the Policy Agent 2.2 for Microsoft IIS 6.0.

Details

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.

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_get_authType(void* agent_config);

Parameters

agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns either DSAME or Basic.

`am_web_get_cookie_name()`

Retrieves the name of the OpenSSO Enterprise cookie.

Syntax

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

Parameters

agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns the name of the OpenSSO Enterprise cookie.

`am_web_get_notification_url()`

Retrieves the URL of the OpenSSO Enterprise Notification Service.

Syntax

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

Parameters

agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns the URL of the OpenSSO Enterprise Notification Service.

`am_web_get_parameter_value()`

Gets the value of the specified parameter from the specified request 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: Pointer to the request URL that holds the parameter.
param_name: Pointer to the name of the parameter.
param_value: Pointer to a pointer to be filled with the value of the param_name parameter, if found.

Returns

This function also returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the query parameter was found in the URL.
AM_*: If any other error occurred.

Memory Concerns

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

`am_web_get_request_url()`

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.

Syntax

#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);

Parameters

This function takes the following parameters:

host_hdr

Pointer to the host header string of the HTTP request as passed from the browser.

protocol

Pointer to the protocol used by the web container of the resource being requested.

hostname

Pointer to the name of the host on which the resource being requested.

port

Value based on the size_t defined in the standard <stddef.h> header file that reflects the port number of the resource being requested.

uri

Pointer to the URI of the HTTP request.

Note –

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.

query

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.

req_url

Pointer to a pointer to the OUT parameter to be populated with the value of the URL string to be used by the agent.

agent_config

An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the query parameter was found in the URL.
AM_*: If any other error occurred.

`am_web_get_token_from_assertion()`

Returns the single sign-on token from the specified Security Assertion Markup Language (SAML) assertion.

Details

am_web_get_token_from_assertion() is used to retrieve the cookie sent by OpenSSO Enterprise in a SAML assertion.

Syntax

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

Parameters

This function takes the following parameters:

assertion: Pointer to the SAML assertion as an XML string.
token: Pointer to a pointer containing the single sign-on token identifier.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If successful.
AM_*: Otherwise.

Memory Concerns

The returned identifier should be freed using am_web_free().

`am_web_get_url_to_redirect()`

Returns a string representing a login URL or access denied URL to which the web agent should redirect.

Caution –

am_web_get_redirect_url() has been deprecated and must not be used. It is supported for backward compatibility only.

Details

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.

Note –

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

Syntax

#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);

Parameters

This function takes the following parameters:

status

The status from am_web_is_access_allowed().

Note –

See am_web_is_access_allowed().

advice_map

Any advice map from policy evaluation results.

goto_url

Pointer to the original URL which the user attempted to access.

method

Pointer to the original HTTP method: GET or POST.

reserved

This parameter is not currently used.

redirect_url

Pointer to a pointer containing the resulting OpenSSO Enterprise redirect URL.

agent_config

An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If successful.
AM_*: Otherwise.

`am_web_get_user_id_param()`

Returns the value of the logged-in user.

Syntax

#include "am_web.h"
AM_WEB_EXPORT char * am_web_get_user_id_param(void* agent_config);

Parameters

This function takes the following parameters:

agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns the value of the logged-in user.

`am_web_handle_notification()`

Handles notification data received by a web agent.

Details

am_web_handle_notification() generates logging messages for the event and any error that may occur during the processing of the notification.

Syntax

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

Parameters

This function takes the following parameters:

data: Pointer to the notification message as an XML string.
data_length: Value based on the size_t defined in the standard <stddef.h> header file that reflects the length of the notification message.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns no value.

`am_web_http_decode()`

URL decodes the specified 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: Pointer to the URL encoded string.
len: Value based on the size_t defined in the standard <stddef.h> header file that reflects the length of the string.

Returns

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

Memory Concerns

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

`am_web_is_access_allowed()`

Evaluates the access control policies for a specified web resource and action against those for a specified user.

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,
                         void* agent_config);

Parameters

This function takes the following parameters:

sso_token: Pointer to the session token from the OpenSSO Enterprise cookie. This parameter may be NULL if there is no cookie present.
url: Pointer to the web resource URL. This parameter may not be NULL.
path_info: Pointer to the path information in the web resource URL, if any.
action_name: Pointer to the action (GET, POST, etc.) being performed on the specified resource URL. This parameter may not be NULL.
client_ip: 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.
env_parameter_map: A map object containing additional information about the user attempting to access the specified resource URL. This parameter may not be NULL.
advices_map_ptr: 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.
result: Pointer to a policy result object.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the evaluation was performed successfully and access is allowed.
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 session 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 a boolean specifying whether cross domain single sign-on is enabled in the agent’s configuration file.

Syntax

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

Parameters

agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If cross domain single sign-on is enabled.
B_FALSE: Otherwise.

`am_web_is_cookie_present()`

Detects whether a cookie is present.

Details

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.

Syntax

#include "am_web.h"
AM_WEB_EXPORT int 
am_web_is_cookie_present(const char *cookie,
                         const char *value,
                         char **new_cookie);

Parameters

This function takes the following parameters:

cookie: Pointer to a cookie.
value: Pointer to a value.
new_cookie: Pointer to a pointer to the location of the new cookie.

Returns

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

`am_web_is_debug_on()`

Returns a boolean specifying whether debug is enabled.

Details

am_web_is_debug_on() specifies whether 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 one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the log level is set to anything greater than 0.
B_FALSE: Otherwise.

`am_web_is_in_not_enforced_ip_list()`

Returns a boolean specifying whether the given IP address is defined as one where no authentication or authorization is required.

Details

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.

Syntax

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

Parameters

This function takes the following parameter:

ip: Pointer to the IP address.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the IP is in the not enforced IP address list.
B_FALSE: Otherwise.

`am_web_is_in_not_enforced_list()`

Returns a boolean specifying whether the URL being accessed by the user is in the not enforced list.

Details

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.

Syntax

#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);

Parameters

This function takes the following parameters:

url: Pointer to the URL being accessed.
path_info: Pointer to the path information in the URL being accessed, if any.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the URL is in the not enforced list.
B_FALSE: Otherwise.

`am_web_is_logout_url()`

Returns a boolean specifying whether the specified URL is a logout URL.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_logout_url(const char *url,
                     void* agent_config);

Parameters

This function takes the following parameter:

url: Pointer to a URL.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the specified URL is a logout URL.
B_FALSE: Otherwise.

`am_web_is_max_debug_on()`

Returns a boolean specifying whether 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 one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the log level is set to 5.
B_FALSE: Otherwise.

`am_web_is_notification()`

Returns a boolean specifying whether the given URL is the Notification Service URL for the web agent as configured in the agent configuration properties.

Syntax

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

Parameters

This function takes the following parameter:

request_url: Pointer to the Notification Service URL
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the URL is the Notification Service URL of the agent as set in the agent configuration proeprties.
B_FALSE: Otherwise.

`am_web_is_owa_enabled()`

Returns the value of the com.sun.identity.agents.config.iis.owa.enable property.

Note –

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.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_owa_enabled(void* agent_config);

Parameters

agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If OWA is enabled.
B_FALSE: Otherwise.

`am_web_is_owa_enabled_change_protocol()`

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.

Note –

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.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_owa_enabled_change_protocol(void* agent_config);

Parameters

agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the protocol was changed.
B_FALSE: Otherwise.

`am_web_is_owa_enabled_session_timeout_url()`

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

Note –

Syntax

#include "am_web.h"
AM_WEB_EXPORT char *
am_web_is_owa_enabled_session_timeout_url(void* agent_config);

Parameters

agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns the URL of the custom session timeout page.

`am_web_is_postpreserve_enabled()`

Returns a boolean specifying whether POST data preservation is enabled for clients in the agent configuration properties.

Syntax

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

Parameters

agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If POST data preservation is on.
B_FALSE: If POST data preservation is off.

`am_web_is_proxy_override_host_port_set()`

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.

Details

These properties are defined in the agent configuration properties.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t am_web_is_proxy_override_host_port_set(void* agent_config);

Parameters

agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If set.
B_FALSE: Otherwise.

`am_web_is_valid_fqdn_url()`

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.

Syntax

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

Parameters

url: Pointer to a URL.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the URL is using a fully qualified domain name.
B_FALSE: Otherwise.

`am_web_log_always()`

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

Syntax

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

Parameters

This function takes the following parameter:

fmt: Pointer to a formatted string message as in printf.

Returns

This function returns no values.

`am_web_log_auth()`

Log the given access allowed or denied message to the OpenSSO Enterprise logs.

Syntax

#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);

Parameters

This function takes the following parameters:

access_type

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;

fmt

Pointer to a formatted string message as in printf.

agent_config

An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the call was successful.
B_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 parameter:

fmt: Pointer to a formatted string message as in printf.

Returns

This function returns no values.

`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 parameter:

fmt: Pointer to a formatted string message as in printf.

Returns

This function returns no values.

`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 parameter:

fmt: Pointer to a formatted string message as in printf.

Returns

This function returns no values.

`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: Pointer to a formatted string message as in printf.

Returns

This function returns no values.

`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: Pointer to a formatted string message as in printf.

Returns

This function returns no values.

`am_web_logout_cookies_reset()`

Resets cookie configured for reset on user logout.

Details

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.

Syntax

#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);

Parameters

This function takes the following parameters:

setFunc: Function pointer with which the user can define their own function for setting the cookie in the foreign domain. The implementation defines the parameters.
args: Pointer to a pointer to agent defined parameters.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns no values.

`am_web_method_num_to_str()`

Converts a am_web_req_method_t number to a string.

Details

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).

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_method_num_to_str(am_web_req_method_t method);

Parameters

This function takes the following parameter:

method

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.

Returns

This function returns a pointer to the string. If the number passed is not recognized, UNKNOWN is returned.

`am_web_method_str_to_num()`

Converts a am_web_req_method_t string to a number.

Details

This function does the opposite of the previously defined am_web_method_num_to_str(). See am_web_method_num_to_str() for details.

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_method_num_to_str(am_web_req_method_t method);

Parameters

This function takes the following parameter:

method

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.

Returns

This function returns a pointer to the number If the string is not recognized, AM_WEB_REQUEST_UNKNOWN is returned.

`am_web_postcache_data_cleanup()`

Cleans up am_web_postcache_data_t data type.

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 parameter:

postentry_struct: Pointer to am_web_postcache_data_t data type.

Returns

This function returns no value.

`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,
                        void* agent_config);

Parameters

This function takes the following parameters:

key: Pointer to the POST data preservation key for every entry.
value: Pointer to the am_web_postcache_data_t data type.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the insertion was successful.
B_FALSE: Otherwise.

`am_web_postcache_lookup()`

Looks up 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,
                        void* agent_config);

Parameters

This function takes the following parameters:

key: Pointer to the key to search POST data entry in POST data structure.
postdata_entry: Pointer to the am_web_postcache_data_t data type storing the POST data.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If the search was successful.
B_FALSE: Otherwise.

`am_web_postcache_remove()`

Removes data from the POST cache.

Syntax

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

Parameters

This function takes the following parameter:

key: Pointer to the key of the entry to be removed.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns no value.

`am_web_process_request()`

Processes a request access check and returns a HTTP result to be rendered by the agent.

Details

The render status is returned in the render_sts argument.

Syntax

#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);

Parameters

This function takes the following parameters:

req_params: Pointer to a am_web_request_params_t data type.
req_func: Pointer to a am_web_request_func_t data type.
render_sts: Pointer to one of the values of the am_status_t enumeration as defined in the <am_types.h> header file.
agent_config: An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

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;

`am_web_remove_authnrequest()`

Removes those extra parameters from an authenticated request.

Details

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.

Syntax

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

Parameters

This function takes the following parameters:

inpString: Pointer to the URL received after CDSSO authentication.
outString: Pointer to a pointer to the location of the new URL without the parameters.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If successful.
AM_*: The type of error indicated by the status value.

Memory Concerns

The value returned should be freed using am_web_free().

`am_web_remove_parameter_from_query()`

Removes the given query parameter from the URL, if present.

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: Pointer to the original URL.
remove_str: Pointer to the query parameter to be removed
outString: Pointer to a pointer to the location of the new URL without the query parameter.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the call was successful.
AM_*: If any error occurs, the type of error indicated by the status value.

Memory Concerns

The value returned should be freed using am_web_free().

`am_web_result_attr_map_set()`

Processes attr_response_map from a am_policy_result_t data type and performs the set action.

Details

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.

Syntax

#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);

Parameters

This function takes the following parameters:

result

Pointer to the am_policy_result_t.

Note –

See am_policy_result_t for more information.

setHeaderFunc

Pointer to the am_web_result_set_header_func_t.

setCookieRespFunc

Pointer to the am_web_result_set_header_attr_in_response_func_t.

setCookieReqFunc

Pointer to the am_web_result_set_header_attr_in_request_func_t.

getCookieSyncFunc

Pointer to the am_web_get_cookie_sync_func_t.

args

Pointer to a pointer to agent defined parameters.

agent_config

An agent configuration instance returned by am_web_get_agent_configuration(). This parameter should not be NULL.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If the call was successful.
AM_*: If any error occurs, the type of error indicated by the status value.

Memory Concerns

The value returned should be freed using am_web_free().

`am_web_result_num_to_str()`

Returns the name of a am_web_result_t as a string.

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_result_num_to_str(am_web_result_t result);

Parameters

This function takes the following parameter:

result

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;

Returns

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.

`am_web_set_cookie()`

Sets the specified cookie in the cookie header of the request.

Syntax

#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);

Parameters

This function takes the following parameters:

cookie_header: Pointer to the cookie header.
set_cookie_value: 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.
new_cookie_header: 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.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS: If successful.
AM_*: The type of error indicated by the status value.