test

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

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:

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.

ProcedureTo Build a Sample Program on UNIX platforms

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

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

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

ProcedureTo Build a Sample Program on the Windows Platform

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

  1. Define WINNT in the compile flags.

  2. Add ../lib as an additional lib path.

  3. Add ../include as an additional include path.

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

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

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

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:

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.