Sun OpenSSO Enterprise 8.0 C API Reference for Application and Web Policy Agent Developers

The Authentication API for C

C applications can authenticate users with the OpenSSO Enterprise 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 OpenSSO Enterprise 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 a realm 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 OpenSSO Enterprise 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. 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 1, Using the Authentication Service API and SPI, in Sun OpenSSO Enterprise 8.0 Developer’s Guide.

Authentication Properties

With the newly developed policy agents 3.0, has been replaced with and Properties in are mandatory for any C API to work. Properties in will only be used if the repository type of the agent user is local. If the repository type is centralized, any required properties not in will be retrieved from the OpenSSO Enterprise server.

Note –

See Centralized Agent Configuration in Sun OpenSSO Enterprise 8.0 Technical Overview for more information.

The following table lists the mandatory properties in

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




URL of the OpenSSO Enterprise Naming Service in the format: 



The logging directory in the format: 



The level at which logs are written in the format: 


where # is the level 5 being the highest, 3 medium and 1 the lowest.


Path to the directory containing the certificate and key databases for Secure Sockets Layer (SSL). 


Set this property if the certificate databases in the directory specified by com.sun.identity.agents.config.sslcert.dir has a prefix.


The password to the key3.db file.

Note –

This property may be added to

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.


The nickname of the client certificate in the cert7.db.

Note –

This property may be added to