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

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 At installation, the file does not exist. If the file does not exist, you must create an 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 and some are not. Those that are not defined in can be added to the file so they do not have to be identified for each function call. For example,, which identifies the organization from which you want to authenticate, can be added to

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 File


# the identity server naming service url
# the directory to use for logging
# the logging level, all:5 being the highest and all:3 being medium
# the directory containing the certificate and key databases
# the prefix of the cert7.db and key3.db files, if any
# the password to the key3.db file
# true to trust SSL certificates not in the client cert7.db
# the nick name of the client certificate in the cert7.db
# the identity server organization desired for authentication,dc=com