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

Sun Java System Access Manager 7 2005Q4 Developer's Guide

Contained Within

Sun Java System Access Manager 7 2005Q4

Find More Documentation

Featured Support Resources

Download this book in PDF (1251 KB)

Chapter 9 Using the C APIs

Sun Java^TM System Access Manager 7 2005Q4 provides C APIs that enable external applications to participate in Access Manager authentication, authorization, single sign-on (SSO), and logging operations. To quickly lookup C API functions and syntax contained in the C header files, see Sun Java System Access Manager 7 2005Q4 C API Reference.

This chapter provides information on how the C APIs work, and includes instructions for using the C sample code that comes with Access Manager. The chapter includes the following topics:

About the C Library for Authentication

C applications can authenticate users with the Access Manager Authentication Service by using the Authentication C API. The C application contacts the Authentication Service to initiate the authentication process, and the Authentication Service responds with a set of requirements. The client application submits authentication credentials back to the Authentication Service and receives further authentication requirements back until there are no more to fulfill. After all requirements have been sent, the client makes one final call to determine if authentication has been successful or has failed.

The sequence of calls necessary to authenticate to Access Manager begins with the function call am_auth_create_auth_context. This call will return an AuthContext structure used for the rest of the authentication calls. Once an AuthContext structure has been initialized, the am_auth_login function is called. This indicates to the Authentication Service that an authentication is desired. Depending on the parameters passed when creating the AuthContext structure and making the am_auth_login function call, the Authentication Service will determine the login requirements with which to respond. For example, if the requested authentication is to an organization configured for LDAP authentication, and no authentication module chaining is involved, the server will respond with the requirements to supply a user name and a password. These attributes correspond to elements in the remote-auth.dtd structure. The user name corresponds to the NameCallback element; the password which corresponds to the PasswordCallback element. The client loops on function call am_auth_has_more_requirements (in this specific case there will be two). The client then fills in the needed information and submits this back to the server with function call am_auth_submit_requirements. The final step is to make function call am_auth_get_status to determine if the authentication was successful or not.

C Sample Code for Authentication

By default, the C Authentication sample checks the directory where Access Manager is installed for a properties file named AMAgent.properties. At installation, the file does not exist. If the file does not exist, you must create an AMAgent.properties file, and add the appropriate properties.

Code Example 6-7 lists the properties that are needed by the C Authentication API. Some of these are defined in AMAgent.properties and some are not. Those that are not defined in AMAgent.properties can be added to the file so they do not have to be identified for each function call. For example, com.sun.am.auth.orgName, which identifies the organization from which you want to authenticate, can be added to AMAgent.properties.

C Header File. The C Authentication API header file, am_auth.h, can be found in AccessManager-base/SUNWam/agents/include. It contains the function prototypes for the function calls available in the C Authentication API.

Example 9–1 AMAgent.properties File

# SOME PROPERTIES LISTED ARE NOT PRE-EXISTING IN THE PROPERTIES FILE

# the identity server naming service url
com.sun.am.namingURL=http://serverexample.domain.com:58080/amserver/namingservice
# the directory to use for logging
com.sun.am.logFile=/home/uid/logs/auth-log
# the logging level, all:5 being the highest and all:3 being medium
com.sun.am.logLevels=all:5
# the directory containing the certificate and key databases
com.sun.am.sslCertDir=/home/level/certdir
# the prefix of the cert7.db and key3.db files, if any
com.sun.am.certDbPrefix=
# the password to the key3.db file
com.sun.am.certDBPassword=11111111
# true to trust SSL certificates not in the client cert7.db
com.sun.am.trustServerCerts=true
# the nick name of the client certificate in the cert7.db
com.sun.am.auth.certificateAlias=Cert-Nickname
# the identity server organization desired for authentication
com.sun.am.auth.orgName=dc=sun,dc=com

About the C Library For Policy

Access Manager provides C APIs to allow external applications to determine access privileges and manage policies. Access Manager 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. The value 100 is defined by a policy. As policy evaluation results in string values only, the policy evaluation returned is 100 numeric and not 100MB. It is up to the application developer to define metrics for the values obtained appropriately.

Note –

The policy management system is generic and makes no assumptions about any particular policy definition requirement.

Policy Implementation

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. Five relative relevances are defined between two resources:

exact match
no match
subordinate match
superior match
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:// AcceessManager-HostName.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 following being part of the root tree:

protocol:// AcceessManager-HostName.domain_name : port/

Policy Evaluation

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.

About the C Library for Single Sign-On

The C API are provided in the SUNWamcom package which comes with Access Manager or any of its downloadable agents. The package includes header files, libraries and samples.

C SSO Include Files

Include files for the C SSO API are am_sso.h and am_notify.h. am_sso.h must be included for any SSO routines. am_notify.h must be included for parsing notification messages from the server and calling SSO listeners.

C SSO Properties

Certain properties must be read in and passed to am_sso_init(), the routine which initializes C API. Because of this, am_sso_init() must be called before any other SSO interface. The default properties file used is AMAgent.properties, located in AccessManager-base/SUNWam/config/. The following properties must be set:

The com.sun.am.namingURL property specifies the URL for the Naming Service. This service is used to find the URL of the Session Service for the given SSOToken ID. This property must be set as:

com.sun.am.namingURL = https://myhost.mydomain.com:58080/amserver/namingservice
The com.sun.am.notificationEnabled and com.sun.am.notificationURL properties specify whether notification is enabled, and if enabled, a URL where the application can listen for messages from Access Manager. These properties must be set as:

com.sun.am.notificationEnabled=true

Note –

If com.sun.am.notificationEnabled is not found in the properties file, the default is false.

com.sun.am.notificationURL=https://myhost.mydomain.com:8000/myURL

The com.sun.am.sso.cacheEntryLifeTime property specifies how long, in minutes, a session token can live in cache before it should be removed. This property must be set as:

com.sun.am.sso.cacheEntryLifeTime=5

If not set, the default is 3 minutes.
The com.sun.am.sso.checkCacheInterval property specifies how often, in minutes, the cache should be checked for entries that have reached the cache entry life time. This property must be set as:

com.sun.am.sso.checkCacheInterval=5
The com.sun.am.sso.maxThreads specify the maximum number threads the SSO API should invoke for handling notifications. The API maintains a thread pool and invokes a thread for each notification. If the maximum number of threads has been reached, the notification will wait until a thread is available. If not specified the default maximum number of threads is 10. This property must be set as:

com.sun.am.sso.maxThreads = 5
The com.sun.am.cookieEnabled property specifies whether the session ID found in the cookie is URL encoded. If true, it will be URL decoded before sent to Access Manager for any session operation. This property must be set as:

com.sun.am.cookieEncoded = true|false

More information on properties in the AMAgent.properties file can be found in the J2EE Policy Agent Guide.

C SSO Interfaces

The C SSO interfaces consist of the following routines. A detailed description of the input and output parameters for each interface is in the header files.

Initialization and Cleanup
Get, Validate, Refresh And Destroy SSO Token
Get Session Information Interfaces
Get And Set Property Interfaces
Listener And Notify Interfaces

Initialization and Cleanup

To use the C SSO API, the am_sso_init() routine needs to be called before any other routines. This interface initializes the internal SSO module. At the end of all SSO routines, am_cleanup() should be called to cleanup the internal SSO module. Code Example 4-5 on page 90 is a code sample for these interfaces.

am_sso_init() initializes internal data structures for talking to the Session Service. It takes a properties input parameter that contains name value pairs from a configuration or properties file, and returns a status on the success or failure of the initialization.

am_cleanup() cleans up all internal data structures created by am_sso_init, am_auth_init, or am_policy_init. am_cleanup() needs to be called only once when using any of the Access Manager C API interfaces (authentication, SSO or policy).

Example 9–2 Code Sample For am_sso_init and am_cleanup

     #include <am_sso.h>

     int main() {
        am_properties_t *properties;
        am_status_t status;

        /* create a properties handle */
        status = am_properties_create(&properties);
        if (status != AM_SUCCESS) {
             printf("am_properties_create failed.\\n");
             exit(1);
        }

        /* load properties from a properties file */
        status = am_properties_load(properties, "./myPropertiesFile");
        if (status != AM_SUCCESS) {
            printf("am_properties_load failed.\\n");
            exit(1);
        }

        /* initialize SSO module */
        status = am_sso_init(properties);
        if (status != AM_SUCCESS) {
            printf("am_sso_init failed.\\n");
            return 1;
        }

         /* login through auth module, and do auth functions.
          * ...
          */

        /* do sso functions
         * ...
         */

         /* done - cleanup. */
         status = am_cleanup();
         if (status != AM_SUCCESS) {
             printf("am_cleanup failed!\\n");
             return 1;
         }
         /* free memory for properties */
         status = am_properties_destroy(properties);
         if (status != AM_SUCCESS) {
             printf("Failed to free properties.\\n");
             return 1;
         }

         /* exit program successfully. */
         return 0;
     }

Get, Validate, Refresh And Destroy SSO Token

A user needs to be authenticated to get the token ID for the user login session. A token can be obtained with the token ID and the am_sso_create_sso_token_handle interface. This interface checks to see if the token is in its local cache and, if not, goes to the server to get the session information associated with the token ID and caches it. If the reset flag is set to true, this interface will refresh the idle time of the token on the server. Here is the interface of am_sso_create_sso_token_handle:

am_status_t am_sso_create_sso_token_handle(am_sso_token_handle_t * sso_token_handle_ptr, const char *sso_token_id, boolean_t refresh_token);

Once a token handle is obtained, the caller can check if the session is valid with the am_sso_is_valid_token interface. The am_sso_token_validate interface will flush the token handle in the local cache (if any) and go to the server to fetch the latest session information. The am_sso_refresh_token will also flush the token handle in the local cache (if any) and go to the server to fetch the session information. In addition, it will reset the idle time of the session on the server. Here are the token-related interfaces:

boolean_t am_sso_is_valid_token(am_sso_token_handle_t sso_token_handle);
am_status_t am_sso_validate_token(am_sso_token_handle_t sso_token_handle);
am_status_t am_sso_refresh_token(am_sso_token_handle_t sso_token_handle);

When caller is done with a token handle, it must be freed by calling am_sso_destroy_sso_token_handle to prevent memory leak. The following is that interface:

am_status_t am_sso_destroy_sso_token_handle(am_sso_token_handle_t sso_token_handle);

The session associated with the token can be invalidated or ended with am_sso_invalidate_token. Although this ends the session for the user, the proper way to log out is through am_auth_logout. Using the former interface to end a session will result in authentication resources associated with the session to remain on the server unnecessarily until the session has timed out. The following is the interface for am_sso_invalidate_token:

am_status_t am_sso_invalidate_token(am_sso_token_handle_t sso_token_handle);

Get Session Information Interfaces

The following interfaces make it convenient to get server-defined information (or properties) about the session associated with a token. This can include the session idle time, maximum session time, and so forth.

const char * am_sso_get_sso_token_id(const am_sso_token_handle_t sso_token_handle);
const char * am_sso_get_auth_type(const am_sso_token_handle_t sso_token_handle);
unsigned long am_sso_get_auth_level(const am_sso_token_handle_t sso_token_handle);
time_t am_sso_get_idle_time(const am_sso_token_handle_t sso_token_handle);
time_t am_sso_get_max_idle_time(const am_sso_token_handle_t sso_token_handle);
time_t am_sso_get_time_left(const am_sso_token_handle_t sso_token_handle);
time_t am_sso_get_max_session_time(const am_sso_token_handle_t sso_token_handle);
const char * am_sso_get_principal(const am_sso_token_handle_t sso_token_handle);
am_string_set_t am_sso_get_principal_set(const am_sso_token_handle_t sso_token_handle);
const char * am_sso_get_host(const am_sso_token_handle_t sso_token_handle);

Get And Set Property Interfaces

The get and set property interfaces allows an application to get any property (server or application defined) and to set any property in a session. Note that am_sso_set_property will update the sso_token_handle with the latest session properties from Access Manager, including the new property that was set. In addition, if the property that is given in prop_name is a protected property, am_sso_set_property will return success, however the value given will not be set as it is a property protected by Access Manager. These interfaces are:

const char * am_sso_get_property(const am_sso_token_handle_t sso_token_handle, const char *prop_name);
am_status_t am_sso_set_property(am_sso_token_handle_t sso_token_handle, const char *prop_name, const char *prop_value);

Code Example 4-6 is a sample of the SSO get, set, create, refresh, validate, invalidate, and destroy interfaces.

Example 9–3 Sample Code For Get, Set, Create, Refresh, Validate, Invalidate, and Destroy Interfaces

     /* initialize sso as in previous sample */

     am_status_t status = NULL;
     am_sso_token_handle_t sso_handle = NULL;
     char *session_status = NULL;
     am_string_set_t principal_set = NULL;

     /* create sso token handle */
     status = am_sso_create_sso_token_handle(&sso_handle, sso_token_id, false);
     if (status != AM_SUCCESS) {
         printf("Failed getting sso token handle for sso token id %s.
					\\n", sso_token_id);
         return 1;
     }

     /* check if session is valid */
     session_status = am_sso_is_valid_token(sso_handle) ? "Valid" : "Invalid";
     printf("Session state is %s\\n", session_status);

     /* check if session is valid using validate. This also updates the handle with 
		 /*info from the server */
     status = am_sso_validate_token(sso_handle);
     if (status == AM_SUCCESS) {
         printf("Session state is valid.\\n");
     } else if (status == AM_INVALID_SESSION) {
         printf("Session status is invalid.\\n");
     } else {
         printf("Error validating sso token.\\n");
         return 1;
     }

     /* get info on the session */
     printf("SSO Token ID is %s.\\n", am_sso_get_sso_token_id(sso_handle));
     printf("Auth type is %s.\\n", am_sso_get_auth_type(sso_handle));
     printf("Auth level is %d.\\n", am_sso_get_auth_level(sso_handle));
     printf("Idle time is %d.\\n", am_sso_get_idle_time(sso_handle));
     printf("Max Idle time is %d.\\n", am_sso_get_max_idle_time(sso_handle));
     printf("Time left is %d.\\n", am_sso_get_time_left(sso_handle));
     printf("Max session time is %d.\\n", am_sso_get_max_session_time(sso_handle));
     printf("Principal is %s.\\n", am_sso_get_principal(sso_handle));
     printf("Host is %s.\\n", am_sso_get_host(sso_handle));
     principal_set = am_sso_get_principal_set(sso_handle);
     if (principal_set == NULL) {
            printf("ERROR: Principal set is NULL!\\n");
     }else {
            printf("Principal set size %d.\\n", principal_set->size);
            for (i = 0; i < principal_set->size; i++) {
                printf("Principal[%d] = %s.\\n", i, principal_set->strings[i]);
            }
            am_string_set_destroy(principal_set);
     }

     /* get "HOST" property on the session. Same as am_sso_get_host(). */
     printf("Host is %s.\\n", am_sso_get_property(sso_handle, "HOST"));

     /* set a application defined property and get it back */
     status = am_sso_set_property(sso_handle, "AppPropName", "AppPropValue");
     if (status != AM_SUCCESS) {
         printf("Error setting property.\\n");
         return 1;
     }
     printf("AppPropName value is %s.\\n", am_sso_get_property
				(sso_handle, "AppPropName");

     /* refresh token, idle time should be 0 after refresh */
     status = am_sso_refresh_token(sso_handle);
     if (status != AM_SUCCESS) {
         printf("Error refreshing token !\\n");
         return 1;
     }
     printf("After refresh, idle time is %d.\\n", am_sso_get_idle_time(sso_handle));

     /* end this session abruptly. am_auth_logout() is the right way 
		 /* to end session */
     status = am_sso_invalidate_token(sso_handle);
     if (status != AM_SUCCESS) {
         printf("Error invalidating token.\\n");
         return 1;
     }

     /* we’re done with sso token handle. free memory for sso handle. */
     status = am_sso_destroy_sso_token_handle(sso_handle);
     if (status != AM_SUCCESS) {
         printf("Failed to free sso token handle.\\n");
         return 1;
     }

     /* call am_cleanup, and other cleanup routines as in previous sample */

Listener And Notify Interfaces

Applications can be notified when a session has become invalid, possibly because it has been idle over a time limit, or it has reached the maximum session time. This is done by implementing a listener function of type am_sso_token_listener_func_t , which takes a SSO token handle, event type, event time, application-defined arguments handle, and a boolean argument to indicate whether the listener function should be called in the calling thread or dispatched to a thread from the internal thread pool managed by the C SDK. This listener function must be registered to be invoked when the session has ended and notification must be enabled for an application to receive notifications. Notification is enabled by setting the property com.sun.am.notificationEnabled to true, and by providing a URL where the application is receiving HTTP messages from Access Manager. The URL where the application is receiving messages from the Access Manager is expected to take any message from the server (as an XML string) and pass it to am_notify(). am_notify() will parse the message and invoke session listeners or policy listeners depending on whether the message is a session or policy notification. Code Example 4-7 is a sample implementation of SSOToken listener and how to register it.

Example 9–4 Sample Implementation Of SSOToken Listener

     void sample_listener_func(
                   am_sso_token_handle_t sso_token_handle,
                   const am_sso_token_event_type_t event_type,
                   const time_t event_time,
                   void *opaque)
     {
         if (sso_token_handle != NULL) {
             const char *sso_token_id = am_sso_get_sso_token_id(sso_token_handle);
             boolean_t is_valid = am_sso_is_valid_token(sso_token_handle);
             printf("sso token id is %s.\\n",
                    sso_token_id==NULL?"NULL":sso_token_id);
             printf("session state is %s.\\n",
                      is_valid == B_TRUE ? "valid":"invalid");
             printf("event type %d.\\n", event_type);
             printf("event time %d.\\n", event_time);
         }
         else {
             printf("Error: sso token handle is null!");
         }
         if (opaque)
             *(int *)opaque = 1;
         return;
     }

     int main(int argc, char *argv[]) {

     am_status_t status;
     char *sso_token_id = argv[1];
     int listener_func_done = 0;

     /* initialize sso as in previous samples */

     /* get sso token handle */
     status = am_sso_create_sso_token_handle(&sso_handle, sso_token_id,  false);

     /* register listener function. notification must be enabled, if not, 
     /* status AM_NOTIF_NOT_ENABLED will be returned. */
 status = am_sso_add_sso_token_listener(sso_handle, sample_listener_func,
				&listener_func_done, B_TRUE);
     if (status != AM_SUCCESS) {
         printf("Failed to register sample listener function.\\n");
         return 1;
     }

Non-Web-Based Applications

Access Manager provides the SSO API primarily for web-based applications, although it can be extended to any non-web-based applications with limitations. With non-web-based applications, you can use the API in one of two ways:

The application has to obtain the Access Manager cookie value and pass it into the SSO client methods to get to the session token. The method used for this process is application-specific.
Command line applications, such as amadmin, can be used. In this case, session tokens can be created to access the Directory Server directly. There is no session created, making the Access Manager access valid only within that process or VM.

Using the C API Code Samples

Access Manager provides sample code you can use to connect your C application to the Access Manager framework. Access Manager also provides the following resources:

At installation, C header files are placed in the following directory:

AccessManager-base/SUNWam/include
For your convenience, the methods in the header files are documented in one volume Sun Java System Access Manager 7 2005Q4 C API Reference.
At installation, sample C code is placed in the following directory:

AccessManager-base/SUNWam/samples/csdk

The following provides descriptions of the C code sample files located in the /csdk directory.

am_policy_test.c: Demonstrates how to use the Policy APIs to evaluate policy for specified resources.
am_auth_test.c: Demonstrates how to use the Authentication APIs to log in to an Access Manager server.
am_sso_test.c: Demonstrates how to use the Single Sign-On (SSO) APIs to perform session operations.
am_log_test.c: Demonstrates how to use the Logging APIs to log a message to Access Manager logs.
apache_agent.c: Demonstrates how to use the Policy APIs to build a Web Agent for the Apache Web Server. This is a sample Web Agent and is not intended to serve as a real Web Agent. When you build the sample code, apache_agent.c is not compiled. The apache_agent.c is provided for reference purposes only.

To Build a Sample Program on UNIX platforms

Be sure you have gmake or other compliant make program available. When possible, use the GNU gmake program, version 3.76 or higher. Be sure you have gcc or other compliant C compiler program available.

In the /samples directory, run the make program:

gmake

This produces executables of the samples am_*_test in the same directory.

On Red Hat Linux Advanced Server release 2.1AS/i686 platform:

On the Red Hat Linux AS 2.1/i686 platform, due to a bug in the default gcc and glibc that comes with RedHat Linux AS 2.1, you must use the following versions (or later) of gcc and glibc:

glibc-2.2.4-32.11
gcc-2.96-124.7.2

The rpms are available at the following locations:

ftp://rpmfind.net/linux/redhat/updates/enterprise/2.1AS/en/os/SRPMS/gcc-2.96-124.7.2.src.rpm

ftp://rpmfind.net/linux/redhat/updates/enterprise/2.1AS/en/os/SRPMS/glibc-2.2.4-32.11.src.rpm

To Build a Sample Program on the Windows Platform

On the Windows platform, you can build sample programs using Microsoft Visual Studio 6.0.

Define WINNT in the compile flags.

Add ../lib as an additional lib path.

Add ../include as an additional include path.

Link with all libraries in the ../lib directory.

Be sure that gmake and MKS Tooolkit are installed on the system.

Run the gmake command:

C:\samples>gmake

The Makefile can be used to make all samples.

Executing the Sample Programs

The sample programs operate in command-line mode and demonstrate the use of C APIs for authorization, authentication, single sign-on (SSO), and logging.

Platform Information

To Execute a Sample Program on the Solaris Platform

On the Solaris platform you can run the sample programs by launching the generated executables on the command line. Set the LD_LIBRARY_PATH environment variable to include the following /lib directories:

/usr/lib/mps
/opt/SUNWam/lib
/usr/lib
/usr/ucblib

These directories contain libamsdk.so, libxml2.so , libssl3.so, libnss3.so, libplc4.so, libplds4.so, libnspr4.so, and libucb.so. Include the directory /usr/lib before /usr/ucblib so that common programs such as editors will continue to function.

To Execute a Sample Program on the Linux Platform

On the Linux platform you can run the sample programs by launching the generated executables on the command line. Be sure to set the LD_LIBRARY_PATH environment variable to include the directory AccessManager-base/agent/lib, which contains the following: libamsdk.so, libxml2.so, libssl3.so, libnss3.so, libplc4.so, libplds4.so and libnspr4.so.

To Execute a Sample Program on the Windows Platform

On the Windows platform you can run the sample programs by launching the generated executables on the command line You must have the ../sample/lib directory in your path before launching the sample programs. Alternatively, you can use the run.bat script to launch the sample programs. The run.bat script sets your path appropriately.

To Execute `am_policy_test`

The sample program am_policy_test evaluates the policy for the given ssoToken, resource name, and action. Before you can run this program, you must have a policy defined for the specified resource in an Access Manager server.

To execute am_policy_test, use the following command:

am_policy_test initPropertyFile ssoToken resourceName action

initPropertyFile

The path to the AMAgent.properties file.

Example: ../config/AMAgent.properties

ssoToken

Valid SSO Token issued by Access Manager. You can get this value from your browser after logging into the Access Manager server. See the documentation for your browser for information about how to determine the cookie values. Once you have that information, you can use the cookie value for iPlanetDirectoryPro as the value for this argument.

If the browser you are using does not provide URL decoded cookie values, you may have to decode the value yourself before using it in this sample program. Alternatively, for test purposes, you can also use the SSO value displayed in the Access Manager debugging logs.

resourceName

Name of a resource for which you want to evaluate a policy. Example:

http://myServer.myDomain .com:80/myResource.html

action

The action name. For example GET or POST .

To Execute `am_auth_test`

The sample program am_auth_test authenticates to the specified organization using the specified authentication module. You must have an Access Manager server with a user profile set up with the corresponding authentication module before running this program.

To execute am_auth_test, run the following command:

am_auth_test [-u user ] [-p password] [-f properties_file] [-r url ] [-n cert_nick_name] [-o org_name] [-m auth_module ]

The following variables are used:

user: Specify the Access Manager user name.
password: Specify the Access Manager user's password.
properties_file: Specify the complete path of the AMAgent.properties file.
url: (Optional) Specify the authentication login URL.
cert_nick_name: (Optional) Specify the certificate nickname.
org_name: Specify the default organization name.
auth_module: Specify the authentication module type. The default is LDAP.

If no options are supplied on the command line, login uses the org_name specified in the properties file and auth_module LDAP. The user can specify the org_name on the command line to override the value specified in the properties file. Example: dc=iplanet,dc=com . In either case, the user is prompted for User Name and Password.

For certificate—based login, the user specifies auth_module Cert on the command line. The user can specify the cert_nick_name on the command line to override the value specified in the properties files. Other values affecting certificate-based login are taken from the properties file. The default properties file is ../../config/AMAgent.properties. Check to be sure the appropriate properties and values are set in the properties file before calling this program. The following properties are specific to authentication:

com.sun.am.auth.orgName
com.sun.am.auth.certificateAlias

To Execute the `am_sso_test` Program

The sample program am_sso_test logs into an Access Manager server using the specified user and password and the LDAP authentication module, and performs SSO Token operations on the session. Before running this program, you must have an Access Manager with a user profile set up with the LDAP authentication module.

To execute am_sso_test, run the following command:

am_sso_test -u user  -p password
			 [-f  properties_file] [-s session_url  ]

user: User to log in to the Access Manager server using the LDAP authentication module.
password: Password to log in to the Access Manager server using the LDAP authentication module.
properties_file: The path to the properties file. If not set, the default properties file ../../config/AMAgent.properties is used. Check to be sure the appropriate values are set in the properties file before calling this program. See Sun Java System Access Manager Policy Agent 2.2 User’s Guidefor more information on the properties file.
session_url: The session URL of the Access Manager server if known. Example: https://myhost/amserver/sessionservice. If not set (the default is not set), the Naming Service specified in the properties file is used to obtain the session URL for the Token ID of the login session.

am_log_test

The sample program am_log_test logs a message to the specified log file on the Access Manager server, using the specified SSO Token.

To execute the am_log_test sample program, run this command:

am_log_test -n log_name -u logged_by_token_id -u user_token_id -m message [-d log_module] [-f properties_file]

log_name: Name of Log file on the Access Manager server.
logged_by_token_id: SSO token ID with access to the Logging Service on the Access Manager server.
user_token_id: SSO token ID of a user for the log. Can be the logged_by_token_id or something else.
message: The log message.
log_module: The module name, if not specified, the default TestModule is used.
properties_file: path to the properties file. If not set, the default properties file ../../config/AMAgent.properties is used. Check to make sure appropriate values are set in the properties file before calling this program. See the Agents documentation for more information on the properties file.

apache_agent.c

The apache_agent.c sample demonstrates how to implement a web agent plugin for the apache HTTP server. This is a sample only and should not be used as an actual web agent.

Contained Within

Find More Documentation

Featured Support Resources

Chapter 9 Using the C APIs

About the C Library for Authentication

C Sample Code for Authentication

Example 9–1 AMAgent.properties File

About the C Library For Policy

Policy Implementation

Policy Evaluation

About the C Library for Single Sign-On

C SSO Include Files

C SSO Properties

C SSO Interfaces

Initialization and Cleanup

Example 9–2 Code Sample For am_sso_init and am_cleanup

Get, Validate, Refresh And Destroy SSO Token

Get Session Information Interfaces

Get And Set Property Interfaces

Example 9–3 Sample Code For Get, Set, Create, Refresh, Validate, Invalidate, and Destroy Interfaces

Listener And Notify Interfaces

Example 9–4 Sample Implementation Of SSOToken Listener

Non-Web-Based Applications

Using the C API Code Samples

To Build a Sample Program on UNIX platforms

On Red Hat Linux Advanced Server release 2.1AS/i686 platform:

To Build a Sample Program on the Windows Platform

Executing the Sample Programs

Platform Information

To Execute a Sample Program on the Solaris Platform

To Execute a Sample Program on the Linux Platform

To Execute a Sample Program on the Windows Platform

To Execute am_policy_test

To Execute am_auth_test

To Execute the am_sso_test Program

am_log_test

apache_agent.c

To Execute `am_policy_test`

To Execute `am_auth_test`

To Execute the `am_sso_test` Program