内に含まその他のドキュメントサポート リソース |  PDF 文書ファイルをダウンロードする (1531 KB)
Chapter 3 Policy Data Types and FunctionsSun OpenSSO Enterprise contains public data types and functions you can use to communicate with the Policy Service. Reference summaries include a short description, syntax, parameters and returns. The code is contained in the <am_policy.h> header file. The sample source am_policy_test.c demonstrates the basic usage of the policy API. This chapter contains the following sections: The Policy API for COpenSSO Enterprise provides policy API for use by developers to integrate a resource authorization functionality within their external C applications. The policy API for C determines if a user has been given permission by a recognized authority to access a particular protected resource. The result of the policy evaluation is called an action value and may be boolean or binary.
Resources StringsThe Policy API for C mandates that any resource be represented in a string format. Thus, resources on a web server must be represented as URLs. The Policy Service is then able to compare the resource string to the policy string and determine a relative relationship between the two. This relationship will be defined as one of the following:
Resource TraitsThe set of characteristics needed to define a resource is called a resource trait. Resource traits are taken as a parameter during service initialization in the am_resource_traits_t. Using the resource traits, the Policy Service constructs a resource graph for policy evaluation in which the relation between all resources in the system spans out like a tree from the root of the given resource. Thus, the service developer must provide the means to extract the root of the given resource. In a URL, the protocol://resource-host.domain:port portion represents the root. Policy EvaluationThe two typedef structures that are used for information exchange to and from the policy evaluation interfaces are:
Policy Data TypesThe types defined in <am_policy.h> are: am_policy_result_tCarries the evaluation results from the Policy Service. Detailsam_policy_result_t unifies various components of a policy evaluation including information regarding the user attempting to perform an action on the resource, advice messages as recommended during policy evaluation, if any, and attribute response maps providing specific key/values as set in policy definition or user entries. Syntax#include "am_policy.h"
typedef struct am_policy_result {
const char *remote_user;
const char *remote_user_passwd;
const char *remote_IP;
am_map_t advice_map;
am_map_t attr_profile_map;
am_map_t attr_session_map;
am_map_t attr_response_map;
const char *advice_string;
} am_policy_result_t;
Members
Memory ConcernsMemory for am_policy_result_t is allocated by am_policy_evaluate() and freed by am_policy_result_destroy(). am_policy_tDeclares an unsigned integer as a type for a policy object. Syntax#include "am_policy.h" typedef unsigned int am_policy_t; Membersam_policy_t has no members. am_resource_traits_tContains the functions to return resource traits that will be used to compare with a user's defined policy and evaluate the access request. Syntax#include "am_policy.h"
typedef struct am_resource_traits {
am_resource_match_t (*cmp_func_ptr)(const struct am_resource_traits *rsrc_traits,
const char *policy_res_name,
const char *resource_name,
boolean_t use_patterns);
boolean_t (*has_patterns)(const char *resource_name);
boolean_t (*get_resource_root)(const char *resource_name,
char *root_resource_name,
size_t buflength);
boolean_t ignore_case;
char separator;
void (*canonicalize)(const char *resource, char **c_resource);
void (*str_free)(void *resource_str);
} am_resource_traits_t;
Members
Policy FunctionsThe functions defined in <am_policy.h> are: Note – Before invoking any of the policy functions, am_web_init() should be invoked by passing the bootstrap property and the local configuration file as parameters, and am_agent_initialized() should be invoked by passing the address of the boolean variable as a parameter — implying that am_web.h should be included in the file. am_policy_compare_urls()Compares the URLs of two resources, and returns the appropriate result. Syntax#include "am_policy.h"
AM_EXPORT am_resource_match_t
am_policy_compare_urls(const am_resource_traits_t *rsrc_traits,
const char *policy_resource_name,
const char *resource_name,
boolean_t use_patterns);
ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_resource_match_t enumeration as defined: #include "am_policy.h"
typedef enum am_resource_match {
AM_SUB_RESOURCE_MATCH,
AM_EXACT_MATCH,
AM_SUPER_RESOURCE_MATCH,
AM_NO_MATCH,
AM_EXACT_PATTERN_MATCH
} am_resource_match_t;
am_policy_destroy()Destroys an initialized instance of a policy evaluator object. DetailsAn instance is initialized for each policy request. Note – The caller must ensure that the same instance is not destroyed more than once. Syntax#include "am_policy.h" AM_EXPORT am_status_t am_policy_destroy(am_policy_t policy); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_policy_evaluate()Evaluates a policy for a given request and returns a non-boolean result. Note – am_policy_evaluate() has been deprecated. See am_policy_evaluate_ignore_url_notenforced(). Detailsam_policy_evaluate() was used to evaluate policy for URLs on the not-enforced list and those not on the not-enforced list. Since there is not a need to evaluate URLs on the not-enforced list, am_policy_evaluate() has been deprecated. Although it can still be used, the SDK invokes am_policy_evaluate_ignore_url_notenforced(). Syntax#include "am_policy.h"
AM_EXPORT am_status_t
am_policy_evaluate(am_policy_t policy_handle,
const char *sso_token,
const char *resource_name,
const char *action_name,
const am_map_t env_parameter_map,
am_map_t policy_response_map_ptr,
am_policy_result_t *policy_result);
ParametersThis function takes the following parameters:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
Memory ConcernsAfter using the results the caller must call am_policy_result_destroy() on policy_result to cleanup the allocated memory. Also, am_map_destroy() must be called on policy_response_map_ptr and env_parameter_map after their respective usage. am_policy_evaluate_ignore_url_notenforced()Evaluates a policy for a given request and returns a non-boolean result. Detailsam_policy_evaluate_ignore_url_notenforced() will evaluate a policy for the specified URL only if the URL does not appear on the not-enforced list defined in the agent configuration properties. Note – See Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for Web Agents, or Sun Java System Access Manager Policy Agent 2.2 User’s Guide for more information. Syntax#include "am_policy.h"
AM_EXPORT am_status_t
am_policy_evaluate_ignore_url_notenforced(am_policy_t policy_handle,
const char *sso_token,
const char *resource_name,
const char *action_name,
const am_map_t env_parameter_map,
am_map_t policy_response_map_ptr,
am_policy_result_t *policy_result,
am_bool_t ignorePolicyResult),
char **am_revision_number;
ParametersThis function takes the following parameters:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
Memory ConcernsAfter using the results the caller must call am_policy_result_destroy() on policy_result to cleanup the allocated memory. Also, am_map_destroy() must be called on policy_response_map_ptr and env_parameter_map after their respective usage. am_policy_get_url_resource_root()Extracts the root of a given URL. Detailsam_policy_get_url_resource_root() populates the resource_root pointer with the extracted information. For example, http://www.sun.com/index.html will return http://www.sun.com/ and http://www.sun.com:8080/index.html will return http://www.sun.com:8080/. Syntax#include "am_policy.h"
AM_EXPORT boolean_t
am_policy_get_url_resource_root(const char *resource_name,
char *resource_root,
size_t length);
ParametersThis function takes the following parameters:
ReturnsThis function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
am_policy_init()Initializes the OpenSSO Enterprise Policy Service. Syntax#include "am_policy.h" AM_EXPORT am_status_t am_policy_init(am_properties_t policy_config_properties); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
Memory ConcernsThe caller must call am_policy_destroy() to free the memory. am_policy_invalidate_session()Cancels the specified session. Syntax#include "am_policy.h"
AM_EXPORT am_status_t
am_policy_invalidate_session(am_policy_t policy_handle,
const char *ssoTokenId);
ParametersThis function takes the following parameters:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_policy_is_notification_enabled()Checks whether the notification functionality is enabled. Syntax#include "am_policy.h" AM_EXPORT boolean_t am_policy_is_notification_enabled(am_policy_t policy_handle); ParametersThis function takes the following parameter:
ReturnsThis function returns the standard boolean_t with one of the following values:
am_policy_notify()Refreshes the policy cache when a policy notification is received by the client. Syntax#include "am_policy.h"
AM_EXPORT am_status_t
am_policy_notify(am_policy_t policy_handle,
const char *notification_data,
size_t notification_data_len);
ParametersThis function takes the following parameters:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
am_policy_resource_canonicalize()Converts the specified resource name into a standard representation for comparison purposes. Syntax#include "am_policy.h"
AM_EXPORT void
am_policy_resource_canonicalize(const char *resource,
char **c_resource);
ParametersThis function takes the following parameters:
ReturnsThis function does not return a value. am_policy_resource_has_patterns()Checks whether the specified resource name has patterns (such as the wildcard *). Syntax#include "am_policy.h" AM_EXPORT boolean_t am_policy_resource_has_patterns(const char *resource_name); ParametersThis function takes the following parameter:
ReturnsThis function returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):
am_policy_result_destroy()Destroys the specified am_policy_result_t structure type. Note – See am_policy_result_t for more information. Syntax#include "am_policy.h" AM_EXPORT void am_policy_result_destroy(am_policy_result_t *result); ParametersThis function takes the following parameter:
ReturnsThis function does not return a value. am_policy_service_init()Initializes one instance of the OpenSSO Enterprise Policy Service for policy evaluation. Syntax#include "am_policy.h"
AM_EXPORT am_status_t
am_policy_service_init(const char *service_name,
const char *instance_name,
am_resource_traits_t rsrc_traits,
am_properties_t service_config_properties,
am_policy_t *policy_handle_ptr);
ParametersThis function takes the following parameters:
ReturnsThis function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
|
|