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