The Authentication API for C

C applications can authenticate users with the Access Manager Authentication Service by using the authentication API for C. The C application contacts the Authentication Service to initiate the authentication process, and the Authentication Service responds with a set of requirements. The application then 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.

Authentication Call Sequence

The sequence of calls necessary to authenticate to Access Manager begins with the function call am_auth_create_auth_context(). This call returns an am_auth_context structure that is then used for the rest of the authentication calls. Once the 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 am_auth_context 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 Lightweight Directory Access Protocol (LDAP) authentication with no authentication module chaining involved, the server will respond with a request for a user name and password. The client loops the function call am_auth_has_more_requirements(), fills in the needed information and submits this back to the server using the function call am_auth_submit_requirements(). (When the requirements are a user name and password, this will happen twice.) The final step is to make the function call am_auth_get_status() to determine if the authentication was successful or not.

---

Note –

The remote-auth.dtd is the template used to format XML authentication requests sent to Access Manager and to parse XML authentication responses received by the external application. The attributes in the requests/responses correspond to elements in the remote-auth.dtd, which can be found in the directory AccessManager-base/SUNWam/dtd. In the example, user name corresponds to the NameCallback element and password to the PasswordCallback element in the remote-auth.dtd. More information on remote-auth.dtd can be found in Chapter 5, Using Authentication APIs and SPIs, in Sun Java System Access Manager 7.1 Developer’s Guide.

---

Authentication Properties

The following list of properties are used by the authentication API. Some are defined in the AMAgent.properties file and some are not. Those that are not defined can be added to the file so they do not have to be defined for each function call. For example, com.sun.am.auth.org.name, which identifies the organization from which you want to authenticate, can be added to AMAgent.properties.

---

Tip –

The web agent AMAgent.properties includes information for a variety of configurations. By default, the authentication API checks the directory where Access Manager is installed for AMAgent.properties. After installing Access Manager though, the file does not exist. If the file does not exist, you must create it and add these properties to the file. More information on AMAgent.properties can be found in Appendix C, Web Agent AMAgent.properties Configuration File, in Sun Java System Access Manager Policy Agent 2.2 Guide for Sun Java System Web Server 6.1.

---

Table 2–1 Properties Needed by the Authentication API for C

Property	Definition
com.sun.am.naming.url	URL of the Access Manager Naming Service in the format:  http://server.domain:port/amserver/namingservice
com.sun.am.policy.agents.config.local.log.file	The logging directory in the format:  path-to-directory/logs/auth-log Note – This property may be added to AMAgent.properties.
com.sun.am.log.level	The level at which logs are written in the format:  all:# where # is the level 5 being the highest, 3 medium and 1 the lowest. More information can be found in AMAgent.properties.
com.sun.am.sslcert.dir	Path to the directory containing the certificate and key databases for Secure Sockets Layer (SSL).
com.sun.am.certdb.prefix	Set this property if the certificate databases in the directory specified by com.sun.am.sslcert.dir has a prefix.
com.sun.am.certDBPassword=	The password to the key3.db file. Note – This property may be added to AMAgent.properties.
com.sun.am.trust_server_certs	Defines whether or not to trust SSL certificates not defined in the certificate database. Takes a value of true or false where true enables trust.
com.sun.am.auth.certificateAlias=	The nick name of the client certificate in the cert7.db. Note – This property may be added to AMAgent.properties.
com.sun.am.auth.org.name	The Access Manager organization desired for authentication. The value is the root suffix of the organization using domain-component (dc) as in:  dc=sun,dc=com Note – This property may be added to AMAgent.properties.