| Sun ONE Identity Server Customization and API Guide |
Chapter 7
Policy ServiceSun™ ONE Identity Server includes a Policy Service that allows for the defintion, management and enforcement of policies that control access to protected resources. It allows administrators to configure and administer these conditions for applications, resources, and identities managed within the Identity Server deployment. This chapter explains the Policy Service and its architecture. It contains the following sections:
OverviewA policy defines rules that specify authorization privileges to an organization’s protected resources. To elaborate, every business has resources, applications and services to protect, manage and monitor. Policies control the usage of, and access to, these resources by defining who can do what to which resource, when and how. A policy, when applied to an object, defines the resources said object can access.
Note
Programmatically, an object is a principal. A principal can be an individual, a corporation, a role, or a group; anything that can have an identity. for more information, see the Java™ 2 Platform Standard Edition Javadocs.
A single policy can define either binary or non-binary decisions. A binary decision is yes/no, true/false or allow/deny; most policies are of this type. A binary decision might answer such questions as “Can Mark execute the changeSalary method in the PayCheck class?” or “Can Sally have access to the PayCheck application at all?” A non-binary decision represents the value of an attribute; for example, a mail service might include a mailboxQuota attribute with a maximum storage value set for each user. In general, a policy is configured to define what an object can do to which resource and under what conditions.
Policy Service
Identity Server provides a Policy Service for the creation and administration of policies. It allows administrators to define, modify, grant, revoke and delete permissions to protect resources within the Identity Server deployment. Typically, a policy service includes a data store, a library of interfaces that allows for the creation, administration and evaluation of policies, and a policy enforcer or policy agent. Identity Server uses Sun ONE Directory Server for data storage, and provides Java and C APIs for policy evaluation and the Identity Server console for policy administration. A selection of downloadable policy agents are used to enforce the policies.
Policy Configuration Service
A Policy Configuration Service is provided to allow the configuration of policy-related attributes for each organization via the Identity Server console. Resource name implementations and Directory Server data stores for use with the Authentication Service can be defined in this service. For additional information, see the Policy Configuration Service Attributes chapter of the Sun ONE Identity Server Administration Guide.
Caching Subject Evaluations
To improve policy evaluation performance, subject evaluations are cached for a period of minutes as defined by the Subjects Result Time To Live attribute in the Policy Configuration service. These cached policy decisions are referred to until the time defined in the Subjects Result Time To Live attribute has elapsed. Once this time has been reached, the next time the policy is evaluated its decision would reflect the user’s changed state, if applicable. (For example, if the user has logged out.)
amldapuser Definition
amldapuser is a user created during installation that is used to bind to, and search, Directory Server during LDAP and Membership authentication. It is also used in the Policy Configuration service. Once the LDAP, Membership or Policy Configuration services are registered to an organization, the password for this user (configured during installation) must be entered. For more information, see the Sun ONE Identity Server Migration Guide .
Policy Agents
The Policy Agent is the Policy Enforcement Point (PEP) for a server on which an enterprise’s resources are stored. Policy agents are provided under separate cover from Identity Server. The most current Sun ONE Identity Server Policy Agents can be downloaded from the the Sun Microsystems Download Center.
In one scenario, a Human Resources web server protected by a remotely-installed Identity Server might have an agent installed on it. This agent would prevent personnel without the proper policy from viewing confidential salary information and other sensitive data. The policies are defined by the Identity Server administrator, stored within the Identity Server deployment and used by the policy agent to allow or deny users access to the remote web server’s content. More information on installing and administrating the policy agents can be found in the Sun ONE Identity Server J2EE Policy Agents Guide or Web Policy Agents Guide.
Note
Policy is evaluated in no particular order although as they are evaluated, if one action value evaluates to deny, subsequent policies are not evaluated. Deny decisions override allow decisions.
Policy agents enforce decisions only on web URLs (http://...). However, agents can be written using the Java and C Policy Evaluation APIs to enforce policy on other resources.
Note
A portion of the "Policy Samples" illustrates how to use the Policy Evaluation class.
In addition, the Resource Comparator attribute in the Policy Configuration Service would also need to be changed from its default configuration to:
serviceType=Name_of_LDAPService|class=com.sun.identity.policy.plugins.SuffixResourceName|wildcard=*|delimiter=,|caseSensitive=false
Alternately, providing an implementation such as LDAPResourceName to implement com.sun.identity.policy.interfaces.ResourceName and configuring the Resource Comparator appropriately would also work.
Note
The fields for the Resource Comparator attribute are explained in detail in “Chapter 34, Policy Configuration Attributes” of the Sun ONE Identity Server Administration Guide.
Architecture
The Policy Service allows for the protection of all types of applications and resources. Figure 7-1 illustrates the architecture of the Policy Service. As shown, custom agents or applications can be written to protect other types of resources including services or other applications.
Figure 7-1 Policy Service Architecture
Policy Agent ProcessThe process for protected web resources begins when a web browser requests a URL that resides on a server protected by the policy agent. The server’s installed policy agent intercepts the request and checks for existing authentication credentials (a session token).
Note
This complete authentication process is detailed in Chapter 3, "Authentication Service," of this manual.
Assuming the agent has intercepted a request and validated the existing session token, the following process is followed.
- Although the session token is valid, the user’s existing authentication level might still be insufficient. If so, the Identity Server Authentication Service will present the appropriate login page, prompting the user for additional credentials.
- The Authentication Service verifies that the new credentials are also valid. For example, if the resource is protected by the LDAP authentication module, the username and password are verified with information stored in Directory Server. In cases where other authentication modules are being used, credentials are verified by the appropriate data store.
- Once the user’s credentials are properly authenticated, the agent issues a request to the Naming Service which defines the URLs used to access Identity Server’s internal services.
- The Naming Service returns locators for the Policy Service, and the agent sends a request to the Policy Service to get policy decisions applicable to the user.
- Based on the policy decisions for the resource being accessed, the user is either allowed or denied access.
Assuming the agent has intercepted a request for which there is no existing session token, the agent redirects the user to their default login page even if the resource is protected using a different authentication method. The user must pass both their default authentication method and the configured resource authentication method before access can be granted.
Note
Policy-based resource authentication and user authentication are separate types of authentication. More information on this can be found in "Policy-Based Resource Management".
Policy TypesThere are two types of policy that can be configured using Identity Server: a Normal Policy or a Referral Policy. A normal policy consists of rules, subjects and conditions. A referral policy consists of rules and referrals to organizations. These policy types are introduced in this section. "Policy Definition Type Document" expands on these definitions.
Normal Policy
A policy that defines access permissions is referred to as a normal policy. A normal policy consists of Rules, Subjects and Conditions.
Rules
A rule contains a resource, one or more sets of an action, and a value. It defines the policy.
- A resource defines the specific object that is being protected; for instance, an HTML page or a user’s salary information accessed using a human resources service.
- An action is the name of an operation that can be performed on the resource; examples of web server actions are POST or GET. An allowable action for a human resources service might be canChangeHomeTelephone.
- A value defines the permission for the action, i.e: allow or deny.
Subjects
A subject defines the user or collection of users (for instance, a group or those who possess a specific role) that the policy affects. Subjects are assigned to policies. The general rule for subjects is that the policy would apply only if the user is a member of at least one subject in the policy. The default subjects are:
Identity Server Roles Versus LDAP Roles
An Identity Server role is created using Identity Server. These roles have object classes mandated by Identity Server. An LDAP Role is any role definition that uses the Directory Server role capability. These roles have object classes mandated by Directory Server role definition. All Identity Server roles can be used as Directory Server roles. All Directory Server roles are not necessarily Identity Server roles. LDAP roles can be leveraged from an existing directory by configuring the Policy Configuration Service. Identity Server roles can only be accessed via the hosting Identity Server Policy Service. Evaluating membership in Identity Server roles will be faster as it accesses the Identity Server SDK and cache. The LDAP Role Search filter can be modified in the Policy Configuration Service to narrow the scope and improve performance.
Nested Roles
Nested roles can be evaluated correctly as LDAP Roles in the subject of a policy definition. However, the LDAP entry representing the nested role must be created using the Directory Server console. Identity Server console or SDK does not support creating nested roles.
Conditions
A condition defines the situations in which a policy is applicable; for instance, a 7 am to 10 am condition defined in a policy restrains the subject(s) to access between 7 am to 10 am. Multiple conditions can be configured. The rule for conditions is that the policy would apply to the subject only if at least one condition for each condition type defined in the policy is satisfied.
Note
The terms referral, rule, resource, subject, condition, action and value correspond to the elements Referral, Rule, ResourceName, Subject, Condition, Attribute and Value in the policy.dtd and are explained further in "Policy Definition Type Document".
Referral Policy
A policy used for delegation is a referral policy. Envision a top-level organization with a sub-organization; in order for the sub-organization administrator to create normal policies, a referral policy must be configured at the top-level organization pointing to the sub-organization. This referral allows the sub-organization to create normal policies that will only affect those in the sub-organization. A referral policy controls delegation for both policy creation and policy evaluation. It consists of one or more rules and one or more referrals.
For example, consider a deployment whose root level organization is dc=example,dc=com with sub-organizations dc=sunone,dc=example,dc=com and dc=suntwo,dc=example,dc=com. In order to define or evaluate policies at dc=sunone,dc=example,dc=com or dc=suntwo,dc=example,dc=com, two referral policies must be created that point from dc=example,dc=com to dc=sunone,dc=example,dc=com and dc=suntwo,dc=example,dc=com, respectively. Each referral policy contains only the resource (or resource prefix) being managed. In this example, if dc=sunone,dc=example,dc=com manages http://www.sunone.com/, the referral policy at dc=example,dc=com contains http://www.sunone.com/ in its rule and refers policy creation to the dc=sunone,dc=example,dc=com sub-organization. (Policies for any resource besides http://www.sunone.com/ can not be created or evaluated until the resource itself is defined in a referral policy.) Only after creating root level referral policies can policies at the sub-organization level be created. There are two types of referral policies: peer organization and sub-organization. They delegate to an organization on the same tree level and an organization on a sub-level, respectively.
Policy-Based Resource ManagementSome organizations require an advanced authentication scenario where a user authenticates against a particular module based on the resource that they are attempting to access. Policy-based resource management is a function of Identity Server in which the user does not need to pass their default authentication module in order to access a web resource.
Limitations
Policy-based resource management contains the following limitations:
- All policies applicable to the resource require the same authentication scheme or level of authentication. For example, if abc.html is defined in a policy for the LDAP authentication module, it can not be defined in a policy for the Certificate-based authentication module.
- Level and scheme are the only conditions that can be defined for this policy.
- This feature does not work across different DNS domains.
To Configure Policy-based Resource Management
Once both Identity Server and a policy agent have been installed, policy-based resource manangement can be configured. To do this, it is necessary to point Identity Server to the Gateway servlet.
- Open AMAgent.properties.
AMAgent.properties can be found (in a Solaris environment) in /export/SUNWam/agents/config/.
- Comment out the following line:
#com.sun.am.policy.am.loginURL = http://identity_server_host.domain_name:port/amserver/UI/Login.
- Add the following line to the file:
com.sun.am.policy.am.loginURL = http://identity_server_host.domain_name:port/amserver/gateway
- Restart the agent.
Policy Definition Type DocumentConfigured policy is stored in Directory Server in XML. In Directory Server, the XML-encoded data is not broken up but stored in one place. Although policy is defined and configured using the amadmin.dtd (or the console), it is actually stored in Directory Server as XML that is based on the policy.dtd. The policy.dtd contains the policy element tags extracted from the amadmin.dtd (without the policy creation tags). So, when the Policy Service loads policies from Directory Server, it parses the XML based on the policy.dtd. The amadmin.dtd is only used when creating policy with the command line. This section describes the structure of policy.dtd. The policy.dtd itself can be found in IdentityServer_base/SUNWam/dtd.
Note
Information on how to use the console and the amadmin interface can be found in the Sun ONE Identity Server Administration Guide.
Policy Element
Policy is the root element that defines the permissions or rules of a policy and to whom/what the rule applies or the subject. It also defines whether or not the policy is a referral (delegated) policy and whether there are any restrictions (or conditions) to the policy. It may contain one or more of the following sub-elements: Rule, Conditions, Subjects, or Referrals. The required XML attribute is name which specifies the name of the policy. The referralPolicy attribute identifies whether or not the policy is a referral policy; it defaults to a normal policy if not defined. Optional XML attributes include name and description.
Rule Element
The Rule element defines the specifics of the policy and can take three sub-elements: ServiceName, ResourceName, or AttributeValuePair. It defines the type of service or application for which the policy has been created as well as the resource name and the actions which are performed on it. A rule can be defined without any actions; for example, a referral policy rule doesn't have any actions.
Note
It is acceptable to have a defined policy that does not include a defined ResourceName element.
ServiceName Element
The ServiceName element defines the name of the service to which the policy applies. This element represents the service type. It contains no other elements. The value is exactly as that defined in the service’s XML file (based on the sms.dtd). The XML service attribute for the ServiceName element is the name of the service (which takes a string value).
ResourceName Element
The ResourceName element defines the object that will be acted upon. The policy has been specifically configured to protect this object. It contains no other elements. The XML service attribute for the ResourceName element is the name of the object. Examples of a ResourceName might be http://www.sunone.com:8080/images on a web server or ldap://sunone.com:389/dc=iplanet,dc=com on a directory server. A more specific resource might be salary://uid=jsmith,ou=people,dc=iplanet,dc=com where the object being acted upon is the salary information of John Smith.
AttributeValuePair Element
The AttributeValuePair element defines an action and its values. It is used as a sub-element to Subject Element, Referral Element and Condition Element. It contains both the Attribute and Value elements and no XML service attributes.
Attribute Element
The Attribute element defines the name of the action. An action is an operation or event that is performed on a resource. POST or GET are actions performed on web server resources, READ or SEARCH are actions performed on directory server resources and purchaseOptions or canUpdateCatalog might be actions performed on a catalog service. The Attribute element must be paired with a Value element. The Attribute element itself contains no other elements. The XML service attribute for the Attribute element is the name of the action.
Value Element
The Value element defines the action values. Allow/deny or yes/no are examples of action values. Other action values can be either boolean, numeric, or strings. The values are defined in the service’s XML file (based on the sms.dtd). The Value element contains no other elements and it contains no XML service attributes.
Subjects Element
The Subjects sub-element identifies a collection of objects to which the policy applies; this overview collection is chosen based on membership in a group, ownership of a role or individual users. It takes the Subject sub-element. The XML attributes it can be defined with are name which defines a name for the collection, description which takes a description and includeType which is not currently used.
Subject Element
The Subject sub-element identifies a collection of objects to which the policy applies; this collection pinpoints more specific objects from the collection defined by the Subjects element. Membership can be based on roles, group membership or simply a listing of individual users. It takes as a sub-element the AttributeValuePair Element. It’s required XML attribute is type which identifies a generic collection of objects from which the specifically defined subjects are taken. Other XML attributes include name which defines a name for the collection and includeType which defines whether the collection is as defined or its inverse (i.e.: the policy applies to users who are NOT members of the subject).
Referrals Element
The Referrals sub-element identifies a collection of policy referrals. It takes the Referral sub-element. The XML attributes it can be defined with are name which defines a name for the collection and description which takes a description.
Referral Element
The Referral sub-element identifies a specific policy referral. It takes as a sub-element the AttributeValuePair Element. It’s required XML attribute is type which identifies a generic collection of assignments from which the specifically defined referrals are taken. It can also include the name attribute which defines a name for the collection.
Conditions Element
The Conditions sub-element identifies a collection of policy restrictions (time range, authentication level, et.al.). It must contain one or more of the Condition sub-element. The XML attributes it can be defined with are name which defines a name for the collection and description which takes a description.
Condition Element
The Condition sub-element identifies a specific policy restriction (time range, authentication level, et.al.). It takes as a sub-element the AttributeValuePair Element. Its required XML attribute is type which identifies a generic collection of restrictions from which the specifically defined conditions are taken. It can also include the name attribute which defines a name for the collection.
Policy SDKThe Policy Service provides Java and C API to allow external applications to participate in its functionality. With the SDK, applications can determine privileges and manage policies.
Java SDK For Policy
The crux of the Policy Service is the Java SDK. It defines the following packages:
- com.sun.identity.policy provides the APIs for administering (creating, deleting, modifying) and evaluating policies. It is used by the Identity Server console and/or the command line interface.
- com.sun.identity.policy.interfaces provides source interfaces used to implement custom subjects, conditions, referrals and resource comparators.
- com.sun.identity.policy.client are APIs used by remote Java applications that need to evaluate policies and get policy decisions.
Policy API For Java
The com.sun.identity.policy package provides the classes and methods to manage, administer and evaluate policies. They can be used by the Identity Server console or the amadmin command line interface tool. Select classes and methods are discussed in this section.
Policy Evaluation Classes
The following information introduces some of the classes that can be used to evaulate configured policies for access to a protected resource.
com.sun.identity.policy.PolicyEvaluator can be integrated into Java applications to evaluate policy privileges and provide policy decisions. This class provides support for both boolean and non-boolean type policies. A PolicyEvaluator is created by calling the constructor with a service name. Public methods of this class include:
- isAllowed—evaluates the policy associated with the given resource and returns a boolean value indicating whether the policy evaluation resulted in an allow or deny.
- Returns a boolean value of:
- Arguments:
- com.iplanet.sso.SSOToken: The SSOToken associated with the principal for which the policy will be evaluated.
- java.lang.String resourceName: A string representing the requested resource.
- java.lang.String actionName: The action for which the policy will be evaluated. In a typical web application scenario, the action could be GET or POST.
- java.util.Map envParameters: A map containing environment parameters that may be needed to successfully evaluate the associated policies.
- Exceptions:
- getPolicyDecision—evaluates the policy and ascertains privileges for non-boolean decisions. It returns a decision that gives a user permission to perform a specific action on a specific resource. This method can also check permissions for multiple actions.
- Returns com.sun.identity.policy.PolicyDecision.
- Arguments:
- com.iplanet.sso.SSOToken: The SSO token associated with the principal for which the policy will be evaluated.
- java.lang.String resourceName: A string representing the requested resource.
- java.util.Set actionName: A collection of actions for which the policy will be evaluated.
- java.util.Map envParameters: A map containing environment parameters that may be needed to successfully evaluate the associated policies.
- Exceptions:
- getResourceResult—obtains the policy and ascertains privileges for non-boolean decisions. Possible values for the scope of this method are self and subtree. self gets the policy decision for the specified resource only. subtree includes the policy decisions for all resources (defined in the policies) which are sub-resources of the specified resource.
To illustrate, the PolicyEvaluator class can be used to display the links for a list of resources to which an authenticated user has access. The getResourceResult method would be used to get the list of resources. The resourceName parameter would be http://host.domain:port which would return all the resources to which the user has access on that server. These resources are returned as a PolicyDecision based on the user’s defined policies. If the user is allowed to access resources on different servers, this method needs to be called for each server.
Note
Not all resources that have policy decisions are accessible to the user. The ActionDecision(s) contained in policy decisions carry this information.
com.sun.identity.policy.ProxyPolicyEvaluator allows a privileged user (top level administrator, organization administrator, policy administrator, or organization policy administrator) to get policy privileges and evaluate policy decisions for any user in their respective scope of administration. com.sun.identity.policy.ProxyPolicyEvaluatorFactory is the singleton class used to get ProxyPolicyEvaluator instances.
com.sun.identity.policy.client.PolicyEvaluator evaluates policies and provides policy decisions for remote applications which do not have a direct access to Directory Server (for example, if there is a firewall). The com.sun.identity.policy.client.PolicyEvaluator defined in "PolicyEvaluator Class" requires direct LDAP access to policies stored in Directory Server. This class com.sun.identity.policy.client.PolicyEvaluator is implemented using XML over HTTP(s). It stores a cache of policy decisions for faster responses and maintains the cache in sync with the Policy Service on the instance of Identity Server using the notification and polling mechanism.
Note
The PolicyEvaluator class can be used in a deployment container running Identity Server, or in a stand alone Java Virtual Machine (JVM) running the Identity Server SDK. Respective to the JVM, a property must be defined to point to serverconfig.xml which, in turn, points to Directory Server. This is done by launching the JVM with the following argument:
-D "com.iplanet.coreservices.configpath=/etc/opt/SUNWam/ config/ums"
Policy Management Classes
The following classes can be used by system administrators to manage policies in Identity Server. The interfaces for this functionality are also found in the com.sun.identity.policy package.
com.sun.identity.policy.PolicyManager is the top level administrator class for policy management, providing methods that allow an administrator to create, modify or delete an organization’s policies. The PolicyManager can be obtained by passing a privileged user’s session token or by passing a privileged user’s session token with an organization name. Some of this class’s more widely used methods include:
- getPolicyNames—retrieves all named policies created for the organization for which the policy manager was instantiated. This method can also take a pattern (filter) as an argument.
- getPolicy—retrieves a policy when given the policy’s name.
- addPolicy—adds a policy to the specified organization. If a policy with the same name already exists, it will be overwritten.
- removePolicy—removes a policy from the specified organization.
com.sun.identity.policy.Policy represents a policy definition with all its intended parts (rules, subjects, referrals and conditions). The policy object is saved in the data store only when the store method is called or if the addPolicy or replacePolicy methods from the PolicyManager class are invoked. This class contains methods to add, remove, replace or get any of the parts of a policy definition.
com.sun.identity.policy.PolicyEvent represents a happening in a policy that could potentially change the current access status. For example, a policy event would be created and passed to the registered policy listeners whenever there is a change in a policy rule. This class works with the PolicyListener class in the com.sun.identity.policy.interface package.
Policy Plugin API For Java
The following classes are used by service developers and policy administrators who need to provide additional policy features as well as support for legacy policies. The package for these classes is com.sun.identity.policy.interfaces. The interfaces include:
ResourceName
ResourceName provides methods to determine the hierarchy of the resource names for a determined service type. For example, these methods can check to see if two resources names are the same or if one is a sub-resource of the other.
Subject
Subject defines methods that can determine if an authenticated user (possessing an SSOToken) is a member of the given subject.
Referral
Referral defines methods used to delegate the policy definition or evaluation of a selected resource (and its sub-resources) to another organization or policy server.
Condition
Condition provides methods used to constrain a policy; for example, time of day or IP address. This interface allows the pluggable implementation of the conditions.
PolicyListener
PolicyListener defines an interface to register for policy events when a policy is added, removed or changed. It is used by the Policy Service to send notifications and by listeners to review policy change events.
C Library For Policy
Identity Server also provides a library of policy evaluation APIs to enable integration of the policy functionality into for C applications. The C library provides a comprehensive set of interfaces that query policy results of an authenticated user for a given action on a given resource. The result of the policy evaluation is called an action value and may not always be binary (allow/deny or yes/no); action values can also be non-boolean. For example, John Smith has a mailbox quota of 100MB. 100 is the value defined by a policy. As policy evaluation results in string values only, the policy evaluation returned is 100 numeric not 100MB. It is up to the application developer to define metrics for the values obtained appropriately.
Caution
Previous releases of Identity Server contained C libraries in IdentityServer_base/lib/capi. The capi directory is being deprectated, and is curently available for backward compatability. It will be removed in the next release, and therefore it is highly recommended that existing application paths to this directory are changed and new applications do not access it. Paths include RPATH, LD_LIBRARY_PATH, PATH, compiler options, etc.)
As the first step of policy implementation, the API abstracts how a resource is represented by mandating that any resource be represented in a string format. For example, on a web server, resources may be represented as URLs. The policy evaluation engine cares only about the relative relevance of one resource to other. There are five relative relevances defined between two resources, namely: exact match, no match, subordinate match, superior match or exact pattern match. Having represented the resources in string format, the service developer must provide interfaces that establish the relevant relationship between resources.
Note
Exact pattern match is a special case where resources may be represented collectively as patterns. The information is abstracted from the Policy Service and the comparison operation must take a boolean parameter to trigger a pattern matched comparison. During the caching of policy information, the policy engine does not care about patterns, whereas during policy evaluation, the comparisons are pattern sensitive.
The service developer must also provide a method to extract the root of the given resource. For example, in a URL, the protocol://identity_server_host.domain_name:port portion represents the root. The three functions (has_patterns, get_resource_root and compare_urls) are specializations of resource representations. The 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 structure. Using the resource traits, the Policy Service constructs a resource graph for policy evaluation. In a web server policy sense, the relation between all the resources in the system spans out like a tree with the protocol://identity_server_host.domain_name:port/ being the root of the tree.
Note
The policy management system is generic and makes no assumptions about any particular policy definition requirement.
Policy Evaluation API for C
Two opaque data structures are defined: am_map_t and am_properties_t. am_map_t provides a key to multiple value mapping and am_properties_t provides a key to single value mapping. am_properties_t provides the additional functionality of loading a configuration file and getting values of specific data types. These are simple data structures that are only used for information exchange to and from the policy evaluation interfaces.
am_map_t
This data structure is an associative container with a key of type const char * and having multiple values of type const char *.
am_map_create(am_map_t *map_ptr)
Syntax
#include <am_map.h>
am_status_t am_map_create( am_map_t *map_ptr);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
This function creates an instance of am_map_t structure and returns the pointer to the structure to the caller.
Memory Concerns
You should free the allocated structure by calling am_map_destroy.
am_map_copy(am_map_t source_map, am_map_t *map_ptr)
Syntax
#include <am_map.h>
am_status_t am_map_copy(am_map_t source_map, am_map_t *map_ptr);
Parameters
This function takes the following parameters:
map_ptr
After successful execution of this function, this pointer will be assigned a new instance of am_map_t structure and all the entries in source_map will be copied into this structure.
Returns
This function returns one of the following values:
Description
This function creates an instance of am_map_t structure, copies all the elements in source_map into the newly created structure and assigns it to map_ptr. It does not alter the contents of source_map.
Memory Concerns
The caller must make sure not to pass a map_ptr which as a valid am_map_t structure, otherwise the reference will be lost. The must destroy map_ptr after usage by calling am_map_destroy.
am_map_destroy(am_map_t *map_ptr)
Syntax
#include <am_map.h>
am_status_t am_map_destroy(am_map_t *map_ptr);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
This function destroys an instance of am_map_t structure which is pointed by map_ptr.
Memory Concerns
Care must be taken that map_ptr was not freed before by calling am_map_destroy or by erroneously calling the system void free (void *) function.
am_map_clear(am_map_t map)
Syntax
#include <am_map.h>
am_status_t am_map_clear(am_map_t map);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
This function takes in a valid am_map_t structure and clears all the elements in it. After successful completion of this function am_map_size on this structure will return 0.
Memory Concerns
None.
am_map_size(const am_map_t map)
Syntax
#include <am_map.h>
size_t am_map_size(const am_map_t map);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
This function takes in a valid am_map_t structure and returns its size.
Memory Concerns
None.
am_map_get_entries(am_map_t map, am_map_entry_iter_t *entry_iter_ptr)
Syntax
#include <am_map.h>
am_status_t am_map_get_entries(am_map_t map, am_map_entry_iter_t *entry_iter_ptr);
Parameters
This function takes the following parameters:
map
The map for which iterator needs to be extracted.
entry_iter_ptr
The iterator pointer that must be assigned with the iterator of the map structure. This is an output parameter.
Returns
This function returns one of the following values:
Description
This function extracts an iterator pointer that could be used to iterate over the key value pairs stored in this table.
Memory Concerns
The iterator pointer passed in must not have non destroyed iterators assigned to them. The caller, in future must call am_map_entry_iter_destroy to destroy the iterator instance.
am_map_insert(am_map_t map, const char *key, const char *value, int replace)
Syntax
#include <am_map.h>
am_status_t am_map_insert(am_map_t map, const char *key, const char *value, int replace);
Parameters
This function takes the following parameters:
map
The map to which the key-value pair must be added.
key
The key for the entry.
value
The value for the entry.
replace
Boolean to indicate whether to replace an existing value for the key or not.
Returns
This function returns one of the following values:
Description
This function inserts a key-value pair into a map.
Memory Concerns
None.
am_map_erase(am_map_t map, const char *key)
Syntax
#include <am_map.h>
am_status_t am_map_erase(am_map_t map, const char *key);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
This function removes a key-value pair from a map.
Memory Concerns
None.
am_map_find(am_map_t map, const char *key, am_map_value_iter_t *value_iter_ptr)
Syntax
#include <am_map.h>
am_status_t am_map_find(am_map_t map, const char *key, am_map_value_iter_t *value_iter_ptr);
Parameters
This function takes the following parameters:
map
The map to which the key-value pair must be added.
key
The key for the entry.
value_iter_ptr
The iterator to which value iterator has to be assigned.
Returns
This function returns one of the following values:
Description
This function takes a key and returns an iterator that iterates over the values associated with the key.
Memory Concerns
At the end of usage of value_iter_ptr, the caller must call am_map_value_iter_destroy with the iterators pointer.
am_map_find_first_value(am_map_t map, const char *key)
Syntax
#include <am_map.h>
const char *am_map_find_first_value(am_map_t map, const char *key);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
This function takes a key and returns the first value associated with the key.
Memory Concerns
Caller must not modify or free the return value.
am_map_entry_iter_destroy(am_map_entry_iter_t entry_iter)
Syntax
#include <am_map.h>
void am_map_entry_iter_destroy(am_map_entry_iter_t entry_iter);
Parameters
This function takes the following parameters:
Returns
None.
Description
This function destroys the am_map_entry_iterator_t passed to it.
Memory Concerns
Caller must be sure that this function is not called multiple times on the same am_map_entry_iter_t.
am_map_entry_iter_get_first_value(am_map_entry_iter_t entry_iter)
Syntax
#include <am_map.h>
const char * am_map_entry_iter_get_first_value(am_map_entry_iter_t entry_iter);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
This function destroys the am_map_entry_iterator_t passed to it.
Memory Concerns
Caller must be sure that this function is not called multiple times on the same am_map_entry_iter_t.
am_map_entry_iter_get_key(am_map_entry_iter_t entry_iter)
Syntax
#include <am_map.h>
const char * am_map_entry_iter_get_key(am_map_entry_iter_t entry_iter);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
This function returns the key of this key-value pair entry iterator.
Memory Concerns
Caller must not modify or free the return value.
am_map_entry_iter_get_values(am_map_entry_iter_t entry_iter, am_map_value_iter_t *value_iter_ptr)
Syntax
#include <am_map.h>
am_status_t am_map_entry_iter_get_values(am_map_entry_iter_t entry_iter, am_map_value_iter_t *value_iter_ptr);
Parameters
This function takes the following parameters:
entry_iter
The iterator that must be destroyed.
value_iter_t
The iterator that goes over the values associated with the key-value pair entry iterator.
Returns
This function returns one of the following values:
Description
This function returns an am_map_value_iter_t that enumerates over the values associated with am_map_entry_iter_t.
Memory Concerns
After the use of value_iter_t the caller must call am_map_value_iter_destroy.
am_map_entry_iter_is_entry_valid(am_map_entry_iter_t entry_iter)
Syntax
#include <am_map.h>
int am_map_entry_iter_is_entry_valid(am_map_entry_iter_t entry_iter);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
This function returns if the entry_iter passed in is valid.
Memory Concerns
None.
am_map_entry_iter_entry_iter_next(am_map_entry_iter_t entry_iter)
Syntax
#include <am_map.h>
int am_map_entry_iter_iter_next(am_map_entry_iter_t entry_iter);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
Advances the specified iterator to the next entry in the map specified when the iterator was created.
Memory Concerns
None.
am_map_value_iter_destroy(am_map_value_iter_t iter)
Syntax
#include <am_map.h>
void
am_map_value_iter_destroy(am_map_value_iter_t value_iter);
Parameters
This function takes the following parameters:
Returns
None.
Description
This function destroys a previously created am_map_value_iter_t structure.
Memory Concerns
Caller must make sure that previously destroyed instance of am_map_value_iter_t is not attempted to be destroyed again.
am_map_value_iter_get(am_map_value_iter_t value_iter)
Syntax
#include <am_map.h>
const char *
am_map_value_iter_get(am_map_value_iter_t value_iter);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
Returns the value referenced by the value iterator.
Memory Concerns
None.
am_map_value_iter_is_value_valid(am_map_value_iter_t value_iter)
Syntax
#include <am_map.h>
int
am_map_value_iter_is_value_valid(am_map_value_iter_t value_iter);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
Returns the validity of the value_iter iterator.
Memory Concerns
None.
am_map_value_iter_is_value_next(am_map_value_iter_t value_iter)
Syntax
#include <am_map.h>
int
am_map_value_iter_next(am_map_value_iter_t value_iter);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
Returns the validity of the value_iter iterator.
Memory Concerns
None.
am_properties_t
This data structure is an associative container with a key of type const char * and having single value of type const char *. It also provides convenience methods to load and store property files (like the Java property file) and get methods to return specific data types. This structure enables the user of the policy evaluation library to bring in the required configuration from any configuration source.
am_properties_create(am_properties_t *properties_ptr)
Syntax
#include <am_properties.h>
am_status_t
am_properties_create(am_properties_t *properties_ptr);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
Creates an instance of am_properties_t and assigns it to properties_ptr.
Memory Concerns
After the usage of the instance the caller must call am_properties_destroy to clean up the allocated memory.
am_properties_copy(am_properties_t source_ptr, am_properties_t *properties_ptr)
Syntax
#include <am_properties.h>
am_status_t
am_properties_create(am_properties_t source_ptr, am_properties_t *properties_ptr);
Parameters
This function takes the following parameters:
source_ptr
The am_properties_t instance whose data must be copied.
properties_ptr
The pointer to the am_properties_t to which the cloned instance must be assigned.
Returns
This function returns one of the following values:
Description
Creates an instance of am_properties_t and assigns it to properties_ptr. The function copies all the elements in the source_ptr to properties_ptr. The source_ptr is not affected during this operation.
Memory Concerns
After the usage of the instance properties_ptr the caller must call am_properties_destroy to clean up the allocated memory. The removal of any item in either structures do not affect the other.
am_properties_destroy(am_properties_t properties)
Syntax
#include <am_properties.h>
am_status_t
am_properties_destroy(am_properties_t properties);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
Destroys an instance of am_properties_t.
Memory Concerns
Caller must make sure not to pass the same instance of am_properties_t to be destroyed more than once. After calling this function it is advised that the caller initializes properties to NULL.
am_properties_load(am_properties_t properties, const char *file_name)
Syntax
#include <am_properties.h>
am_status_t
am_properties_load(am_properties_t properties, const char *file_name);
Parameters
This function takes the following parameters:
properties
The am_properties_t instance to which the key-value pairs needs to be loaded into.
file_name
The name of the file from which the properties need to be loaded.
Returns
This function returns one of the following values:
Description
Loads property information from a specified file, an instance of am_properties_t.
Memory Concerns
None.
am_properties_store(am_properties_t properties, const char *file_name)
Syntax
#include <am_properties.h>
am_status_t
am_properties_store(am_properties_t properties, const char *file_name);
Parameters
This function takes the following parameters:
properties
The am_properties_t instance to which the key-value pairs needs to be saved.
file_name
The name of the file from which the properties need to be written to.
Returns
This function returns one of the following values:
Description
Stores all the key-value pairs in this object into the file.
Memory Concerns
None.
am_properties_is_set(am_properties_t properties, const char *key)
Syntax
#include <am_properties.h>
int
am_properties_is_set(am_properties_t properties, const char *key);
Parameters
This function takes the following parameters:
properties
The am_properties_t instance whose contents need to be examined.
key
The key whose presence will be checked.
Returns
This function returns one of the following values:
Description
This function checks if the key is present is the properties instance.
Memory Concerns
None.
am_properties_get(am_properties_t properties, const char *key, const char **value_ptr)
Syntax
#include <am_properties.h>
am_status_t
am_properties_get(am_properties_t properties, const char *key, const char **value_ptr);
Parameters
This function takes the following parameters:
properties
The am_properties_t instance from which the keys value needs to be extracted.
key
The key whose value will be returned.
value_ptr
The value pointer to which the value will be assigned to. This is an output parameter.
Returns
This function returns one of the following values:
Description
This function checks if the key is present is the properties instance and returns its value.
Memory Concerns
Caller must not modify the value_ptr structure or free the memory.
am_properties_get_with_default(am_properties_t properties, const char *key, const char *default_value, const char **value_ptr)
Syntax
#include <am_properties.h>
am_status_t
am_properties_get(am_properties_t properties, const char *key, const char *default_value, const char **value_ptr);
Parameters
This function takes the following parameters:
properties
The am_properties_t instance from which the keys value needs to be extracted.
key
The key whose value will be returned.
default_value
The value to be returned in case of any error condition.
value_ptr
The value pointer to which the value will be assigned to. This is an output parameter.
Returns
Return values may be ignored.
Description
This function checks if the key is present is the properties instance. If the key is not present, the function returns the default value passed in. Otherwise it returns the value of the key.
Memory Concerns
Caller must not modify the value_ptr structure or free the memory.
Information And Utility APIs For C
Following are the policy data structures and operations.
am_policy_result_t
Syntax
#include <am_policy.h>
typedef struct am_policy_result {
const char *remote _user;
const char *remote_IP;
am_map_t advice_map;
am_map_t attr_response_map;
am_policy_result_t;
Parameters
This structure has the following components:
remoteUser
After policy evaluation, this variable is assigned the name of the remote user.
advice_map
On the server side some policies may have resulted in advices. For detailed discussion on advices, please refer to the policy service documentation.
attr_response_map
After evaluation of policies, each policy may define pairs of keys and values. These values may provide more information about the user or about the policy evaluation itself. Apart from this, library may be requested to obtain user attributes. This is a configuration parameter set during service initialization in the service configuration properties structure.
Description
This structure unifies various components of policy evaluation: name of the user try to perform an action on the resource, the advices as recommended by individual policies during evaluation and attribute responses providing specific values as set in policy definition or user attributes as requested during service initialization. The property com.iplanet.am.policy.am.headerAttributes specifies what all attributes in the users entry needs to be returned along with policy evaluation results.
Memory Concerns
Caller to am_policy_evaluate must call am_policy_result_destroy after using the results.
am_resource_traits_t
Syntax
typedef struct am_resource_traits {
am_resource_match_t (*cmpFuncPtr)(const char *policyResName,
const char *resourceName,
am_bool_t usePatterns);
am_bool_t (*hasPatterns)(const char *resourceName);
am_bool_t (*getResourceRoot)(const char *resourceName,
char *rootResourceName,
size_t buflength);
} am_resource_traits_t;
Parameters
This structure has the following components:
cmpFuncPtr
The compare function takes two resource strings and a boolean value. The boolean value controls whether the compare function must use patterns defined in the resource name or not.
hasPatterns
The is function takes a resource name, examines it and returns true if it has patterns or not. Since the service writer can decide the implementation of pattern representations and so the symbols used as patterns, this function is a resource trait.
getResourceRoot
This function takes a given resource and finds a root resource name for that resource. The length is the size of the rootResourceName buffer. The minimum required length of the rootResourceName buffer is governed by the representation of the resource name and so up to the discretion of the service writer.
Description
This structure is an input parameter to am_policy_init function. This structure contains all the resource traits interfaces that are required during policy information maintenance and evaluation.
Memory Concerns
None.
am
The am methods are one-time library initialization and cleanup methods. These functions may be called once and only once for the entire life of the shared object.
am_init(am_policy_t policy)
Syntax
#include <am.h>
am_status_t
am_init(am_properties_t library_init_config);
Parameters
This function takes the following parameters:
library_init_config
This structure contains configuration information required to initialize the shared object.
Returns
This function returns one of the following values:
Description
This function initializes the shared object. This function must be called only once and must be the first function to be called in the library.
Memory Concerns
Caller must call ascertain that this function is not called more than once and its cleanup counterpart am_cleanup is called once and is the last function to be called in the library.
am_init(am_policy_t policy)
Syntax
#include <am.h>
am_status_t
am_cleanup(void);
Parameters
None.
Returns
This function returns one of the following values:
Description
This function cleans up all the memory and resources allocated by the shared object. This function must be called only once and must be the last function to be called in the library.
Memory Concerns
None.
am_policy
The am_policy methods are service specific methods. These methods may be used only after am_init has been invoked successfully and may not used after am_cleanup has been performed.
am_policy_init(const char *service_name, const char *instance_name, am_resource_traits_t rsrcTraits, am_properties_t service_config_properties, am_policy_t *policy_handle_ptr)
Syntax
#include <am_policy.h>
am_status_t
am_policy_init(const char *service_name, const char *instance_name, am_resource_traits_t rsrcTraits, am_properties_t service_config_properties, am_policy_t *policy_handle_ptr);
Parameters
This function takes the following parameters:
service_name
The name of the service about to be created.
instance_name
The instance name of the new service. Currently this parameter is unused.
rsrcTraits
The resource traits structure that contains the pointers to the actual implementations of the resource name operations.
service_config_properties
The am_properties_t instance that has the initialization values required during the initialization of the service.
policy_handle_ptr
The pointer to the am_policy_t that will be initialized a policy_handle after successful completion of service creation.
Returns
This function returns one of the following values:
Description
This function initializes a policy service instance.
Memory Concerns
Caller must call am_policy_destroy structure or free the memory.
am_policy_destroy(am_policy_t policy)
Syntax
#include <am_policy.h>
void
am_policy_destroy(am_policy_t policy);
Parameters
This function takes the following parameters:
Returns
None.
Description
This function destroys a policy service instance.
Memory Concerns
Caller must call make sure the same service instance not be destroyed more than once.
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)
Syntax
#include <am_policy.h>
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);
Parameters
This function takes the following parameters:
policy_handle
The policy service which needs to be destroyed.
sso_token
The single sign-on token of the user who must be evaluated for accessing the resource and perform a given action.
resource_name
The string form of the resource that the user wants to perform the action on.
action_name
The action the user wants to perform on the action.
env_parameter_map
The environment parameters like IP address the user is accessing the resource from.
policy_response_map_ptr
The response structure that will be populated after evaluation of the policies.
policy_result
Pointer to am_policy_result_t structure that will be populated during policy evaluation.
Returns
This function returns one of the following values:
Description
This function destroys a policy service instance.
Memory Concerns
After using the results the caller must call am_policy_result_destroy on the policy_result to cleanup the memory allocated by the evaluation operation. am_map_destroy must also be called on response and env_parameter_map after their respective usage scope.
am_policy_is_notification_enabled(am_policy_t policy_handle)
Syntax
#include <am_policy.h>
am_bool_t
am_policy_is_notification_handled(am_policy_t policy_handle);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
This function checks and returns the state of notification. This configuration is read by the service during initialization from the service configuration properties.
Memory Concerns
None.
am_policy_notify(am_policy_t policy_handle, const char *notification_data, size_t notification_data_len)
Syntax
#include <am_policy.h>
am_status_t
am_policy_notify(am_policy_t policy_handle, const char *notification_data, size_t notification_data_len);
Parameters
This function takes the following parameters:
policy_handle
The policy service instance whose configuration needs to be examined.
notification_data
The notification data that was received by the caller.
notification_data_len
Notification data length.
Returns
This function returns one of the following values:
Description
When the configuration com.iplanet.am.policy.am.notificationEnabled is set to true, the library registers with the server to receive notification in case of any change of information (session or policy) on the server. The notification is sent to the URL again, set in the service configuration properties as a value of com.iplanet.am.policy.am.notificationURL during initialization.
Memory Concerns
None.
Specialization Methods
These functions are resource traits implementations for URLs. These are provided for the sake of convenience and as reference implementations of resource names.
am_policy_compare_urls(const char *policyResourceName, const char *resourceName, am_bool_t usePatterns)
Syntax
#include <am_policy.h>
void
am_policy_compare_urls(const char *policyResourceName, const char *resourceName, am_bool_t usePatterns);
Parameters
This function takes the following parameters:
policyResourceName
The resource name as defined in the policy. This is the only parameter that can have patterns it them.
resourceName
The name of the resource accessed by the user.
usePatterns
The patterns in the policyResourceName if present must be used if this parameter is set to AM_TRUE otherwise used as normal characters.
Returns
This function returns one of the following values:
- EXACT_MATCH if policyResourceName and resourceName match verbatim.
- SUB_RESOURCE_MATCH if resourceName is a subordinate resource of policyResourceName.
- SUPER_RESOURCE_MATCH if policyResourceName is a subordinate resource of resourceName.
- NO_MATCH if policyResourceName and resourceName do not match.
- EXACT_PATTERN_MATCH This value will be returned only if usePatterns argument is AM_TRUE and if policyResourceName has patterns which matches resourceName string.
Description
This function compares two given URLs. The policyResourceName is the URL defined in the policy definition. The policy definition can contain patterns. In the reference implementation, the comparison mechanism does only wildcard match, that is, it supports only * in a policyResourceName as a pattern. A service writer may replace this function with another implementation that supports complete regular expressions. But, the service writer must also take care to change the hasPatterns function to behave appropriately.
Memory Concerns
None.
am_policy_get_url_resource_root(const char *resourceName, char *resourceRoot, size_t length)
Syntax
#include <am_policy.h>
am_bool_t
am_policy_get_url_resource_root(const char *resourceName, char *resourceRoot, size_t length);
Parameters
This function takes the following parameters:
resourceName
The resource name for which the root resource must be extracted.
resourceRoot
The pointer where the resource root will be copied to.
length
The length of the resourceRoot buffer.
Returns
This function returns one of the following values:
Description
This function is takes a URL and extracts a root of the URL. 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/.
Memory Concerns
In an implementation for a different resource other than URLs, the service writer implementing this function must make accurate judgement about the minimum size of resourceRoot.
am_policy_get_url_resource_has_patterns(const char *resourceName)
Syntax
#include <am_policy.h>
am_bool_t
am_policy_get_url_resource_has_patterns(const char *resourceName);
Parameters
This function takes the following parameters:
Returns
This function returns one of the following values:
Description
This function takes a URL and returns a boolean value reflecting its pattern content. For example, http://www.sun.com/index.html will return AM_FALSE and http://www.sun.com/*.html will return AM_TRUE. http://www.sun.com/* will return AM_TRUE.
Memory Concerns
None.
Initialization Variables
Initialization variables are properties defined in AMAgent.properties. For a listing of these variables see the Sun ONE Identity Server Web Policy Agents Guide or J2EE Policy Agents Guide.
Specialization Methods For Web Agents
am_web_init(const char *config_file)
Syntax:
#include <am_web.h>
am_status_t am_web_init(const char *config_file);
Parameters:
This function takes the following parameters:
Returns:
This function returns one of the following values:
- AM_SUCCESS if the initialization was successful.
- AM_INVALID_ARGUMENT if any argument is NULL or invalid.
- AM_NSPR_ERROR if there is an error while performing an NSPR operation.
- AM_NO_MEMORY if there was an internal memory operation error.
- AM_FAILURE if the initialization failed due to unexpected error condition.
Description:
This function initializes the shared object. This function must be called only once and must be the first function to be called in the library.
Memory Concerns:
Caller must ascertain that this function is not called more than once and its cleanup counterpart am_web_cleanup is the last function to be called in the library.
am_web_cleanup()
Syntax:
#include <am_web.h>
am_status_t am_web_cleanup();
Parameters:
None.
Returns:
This function returns one of the following values:
- AM_SUCCESS if the operation was successful.
- AM_INVALID_ARGUMENT if any argument is NULL or invalid.
- AM_NSPR_ERROR if there is an error while performing an NSPR operation.
- AM_NO_MEMORY if there was an internal memory operation error.
- AM_FAILURE if the initialization failed due to unexpected error condition.
Description:
This function releases all the resources allocated by the library. This function must be called only once and must be the last function to be called in the library.
Memory Concerns:
Caller must ascertain that this function is not called more than once and its initialization counterpart am_web_init has been called before its invocation.
am_web_is_access_allowed(const char *sso_token, const char *url, const char *action_name, const char *client_ip, const am_map_t env_parameter_map, am_policy_result_t *result);
Syntax:
#include <am_web.h>
am_status_t
am_web_is_access_allowed(const char *sso_token, const char *url,const char *action_name,const char *client_ip, const am_map_t env_parameter_map, am_policy_result_t *result);
Parameters:
This function takes the following parameters:
sso_token
The sso_token from the Identity Server cookie. This parameter may be NULL if there is no cookie present.
url
The URL whose accessibility is being determined. This parameter may not be NULL.
action_name
The action (GET, POST, etc.) being performed on the specified URL. This parameter may not be NULL.
client_ip
The IP address of the client attempting to access the specified URL. If client IP validation is turned on, then this parameter may not be NULL.
env_parameter_map
A map containing additional information about the user attempting to access the specified URL. This parameter may not be NULL.
result
A data structure to store the result of this operation as passed back to the caller.
Returns:
This function returns one of the following values:
- AM_SUCCESS if the evaluation was performed successfully and access is to be allowed to the specified resource.
- 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 result parameters is NULL or if client IP validation is enabled and the client_ip parameter is NULL.
- AM_INVALID_SESSION if the specified sso_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.
Description:
This function evaluates the access control policies for a specified web-resource and action. The web-resource is identified as the URL that the user is trying to access and the action is the associated HTTP call made by the user agent such as GET or POST.
Memory Concerns:
The caller must free the memory associated with all the arguments passed into this function when they are no longer in use or applicable.
am_web_is_notification(const char *request_url)
Syntax:
#include <am_web.h>
am_bool_t
am_web_is_notification(const char *request_url);
Parameters:
This function takes the following parameters:
Returns:
This function returns one of the following values:
Description:
This function determines if the request is an Identity Server notification message intended for the policy SDK.
Memory Concerns:
None.
am_web_handle_notification(const char *data, size_t data_length);
Syntax:
#include <am_web.h>
void
am_web_handle_notification(const char *data, size_t data_length);
Parameters:
This function takes the following parameters:
data
A buffer containing data as obtained from the request.
data_length
The length of the data contained in the buffer.
Returns:
None
Description:
This function processes the notification data as sent by Identity Server and updates the state of the Policy SDK accordingly. Any errors that may occur during the processing of the given data are logged in the appropriate log files.
Memory Concerns:
None.
am_web_get_redirect_url(am_status_t status, const am_map_t advice_map, const char *goto_url, am_bool_t *allocated_ptr);
Syntax:
#include <am_web.h>
char *am_web_get_redirect_url(am_status_t status, const am_map_t advice_map, const char *goto_url, am_bool_t *allocated_ptr);
Parameters:
This function takes the following parameters:
status
The return value obtained from the call to function am_web_is_access_allowed().
advice_map
The advice map contained in the policy result as obtained from the call to function am_web_is_access_allowed().
goto_url
The return URL to be used by the Identity Server to redirect the user after successful authentication.
allocated_ptr
A flag that indicates if any memory was allocated during the course of this operation which should the be deallocated by the caller accordingly.
Returns:
A URL that may be used to redirect the user accordingly. This URL may be either the login URL or the access denied URL.
Description:
This function returns a string representing the URL for redirection that is appropriate to the provided status code and advice map returned by the Policy SDK. This may either redirect the user to the login URL or the access denied URL. If the redirection is to the login URL then the URL will include any existing information specified in the URL from the configuration file, like org value etc., followed by the specified goto parameter value, which will be used by Identity Server after the user has successfully authenticated.
Memory Concerns:
If the value returned in allocated_ptr parameter is AM_TRUE, then the caller is responsible for calling am_web_free_memory() function when done with the returned string. Using another free function may cause corruption of memory and result in fatal runtime errors. If allocated_ptr is NULL, then the function will always return a pointer to the access denied URL, which is not allocated.
am_web_do_result_attr_map_set(am_policy_result_t *result, am_status_t (*setFunc)(char *, char *, void **), void **args);
Syntax:
#include <am_web.h>
am_status_t
am_web_do_result_attr_map_set(am_policy_result_t *result, am_status_t (*setFunc)(char *, char *, void **), void **args);
Parameters:
This function takes the following parameters:
result
The result obtained from the call to function am_web_is_access_allowed().
setFunc
A function pointer for the call back function to be used when iterating over various values of the result.
args
The optional arguments to be passed to the call back function during its invocation.
Return:
This function returns one of the following values:
Description:
This function process attr_response_map of am_policy_result_t and performs the appropriate set action that caller pass in.
Memory Concerns:
None.
am_web_free_memory(void *memory)
Syntax:
#include <am_web.h>
void am_web_free_memory(void *memory);
Parameters:
This function takes the following parameter:
Return:
None.
Description:
This function releases previously allocated memory by any of the am_web_* functions.
Memory Concerns:
This function must be called in order to free any memory allocated by the am_web_* functions. Using other routines to free such memory may result in memory corruption and lead to fatal runtime error conditions.
am_web_get_cookie_name()
Syntax:
#include <am_web.h>
const char *am_web_get_cookie_name()
Parameters:
None.
Return:
This function returns the name of the Identity Server cookie.
Description:
This function returns the Identity Server cookie name as used by the Policy SDK. The value of this depends upon the value stored in the configuration file that was used to initialize the library.
Memory Concerns:
None
am_web_get_notification_url()
Syntax:
#include <am_web.h>
const char *am_web_get_notification_url()
Parameters:
None.
Return:
This function returns the notification URL used by the Agent.
Description:
This function returns the URL used by the Agent to receive Identity Server notifications. The value of this depends upon the value stored in the configuration file that was used to initialize the library.
Memory Concerns:
None
am_web_is_debug_on()
Syntax:
#include <am_web.h>
am_bool_t am_web_is_debug_on();
Parameters:
None.
Return:
This function returns one of the following values:
Description:
This function returns a flag which indicates if debugging has been enabled or disabled. When enabled, the Agent can use various convenience functions in order to log debug messages to the appropriate log files.
Memory Concerns:
None.
am_web_is_max_debug_on()
Syntax:
#include <am_web.h>
am_bool_t am_web_is_max_debug_on();
Parameters:
None.
Return:
This function returns one of the following values:
Description:
This function returns a flag which indicates if debugging has been set at its maximum level. The caller can use this function to determine if it is appropriate to emit very verbose information to the debug logs.
Memory Concerns:
None.
am_web_log_always(const char *fmt, ...)
Syntax:
#include <am_web.h>
void am_web_log_always(const char *fmt, ...);
Parameters:
This function takes the following parameters:
fmt
A printf style format string along with associated variable list to be used to emit a formatted message.
Return:
None.
Description:
This function allows logging of information regardless of the level at which the library has been configured through the specified values in the configuration file. It takes a printf style format string and argument list which is used to generate a formatted message that is then logged into the appropriate log file.
Memory Concerns:
None.
am_web_log_auth(am_web_access_t accessType, const char *fmt, ...)
Syntax:
#include <am_web.h>
am_bool_t am_web_log_auth(am_web_access_t accessType, const char *fmt, ...);
Parameters:
This function takes the following parameters:
accesstype
An enumeration that indicates the type of access that is being logged. This value could be either LOG_DENY or LOG_ALLOW or LOG_BOTH or LOG_NONE.
fmt
A printf style format string along with associated variable list to be used to emit a formatted message.
Return:
This function returns one of the following values:
Description:
This function is used to log information to the remote Identity Server's log service. Depending upon the value specified in the configuration file, requests associated with certain accesstype values may or may not get logged by this function.
Memory Concerns:
None.
am_web_log_error(const char *fmt, ...)
Syntax:
#include <am_web.h>
void am_web_log_error(const char *fmt, ...);
Parameters:
This function takes the following parameters:
fmt
A printf style format string along with associated variable list to be used to emit a formatted message.
Return:
None.
Description:
This function formats and logs the given message as an error in the associated log file. This message will be logged if the associated logging level is greater than or equal to the error logging level.
Memory Concerns:
None.
am_web_log_warning(const char *fmt, ...)
Syntax:
#include <am_web.h>
void am_web_log_warning(const char *fmt, ...);
Parameters:
This function takes the following parameters:
fmt
A printf style format string along with associated variable list to be used to emit a formatted message.
Return:
None.
Description:
This function formats and logs the given message as a warning in the associated log file. This message will be logged if the associated logging level is greater than or equal to the warning logging level.
Memory Concerns:
None.
am_web_log_info(const char *fmt, ...)
Syntax:
#include <am_web.h>
void am_web_log_info(const char *fmt, ...);
Parameters:
This function takes the following parameters:
fmt
A printf style format string along with associated variable list to be used to emit a formatted message.
Return:
None.
Description:
This function formats and logs the given message as an informational message in the associated log file. This message will be logged if the associated logging level is greater than or equal to the informational logging level.
Memory Concerns:
None.
am_web_log_debug(const char *fmt, ...)
Syntax:
#include <am_web.h>
void am_web_log_debug(const char *fmt, ...);
Parameters:
This function takes the following parameters:
fmt
A printf style format string along with associated variable list to be used to emit a formatted message.
Return:
None.
Description:
This function formats and logs the given message as a debug message in the associated log file. This message will be logged if the associated logging level is greater than or equal to the debug logging level.
Memory Concerns:
None.
am_web_log_max_debug(const char *fmt, ...)
Syntax:
#include <am_web.h>
void am_web_log_max_debug(const char *fmt, ...);
Parameters:
This function takes the following parameters:
fmt
A printf style format string along with associated variable list to be used to emit a formatted message.
Return:
None.
Description:
This function formats and logs the given message as a debug message in the associated log file. This message will be logged if the associated logging level is greater than or equal to the maximum debug logging level.
Memory Concerns:
None.
Initialization Variables
Initialization variables are properties defined in AMAgent.properties. For a listing of these variables see the Sun ONE Identity Server J2EE Policy Agents Guide or Web Policy Agents Guide.
Policy SamplesSample files have been included to help understand how the Policy Service can be used. These samples are located in IdentityServer_base/SUNWam/samples/ policy and Readme.html offers detailed instructions on how to:
- Add a new policy service.
- Develop and add custom Subjects, Referrals, and Conditions.
- Create policies using the amadmin command line tool.
- Develop and run a programmatic policy evaluation (i.e.: without the use of a policy agent).
- Construct policies programmatically and add them to the Directory Server data store.
