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

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

See also am_web_add_header_in_response_func_t.

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

See also am_web_free_post_data_func_t.

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

See also am_web_get_post_data_func_t.

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

See also am_web_render_result_func_t.

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

See also am_web_render_result_func_t.

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

See also am_web_set_method_func_t.

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

See also am_web_set_user_func_t.

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:

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:

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

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:

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:

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 – 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 –

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