Previous Topic: Forgotten Password (FPS) Interface (Forgot)Next Topic: Authentication Scheme

Advanced Password Services (APS) Guide › Application Programming Interface

Application Programming Interface

Starting with Version 3.0, APS provides a true Application Programming Interface (API). This interface does not provide a generic interface to updating directories; rather, it provides programmatic access to APS' password evaluation capabilities and run-time authentication checking.

The API is "housed" in a library called APSAPI (under Windows, APSAPI.DLL, and under Solaris, libAPSAPI.so). This library and the required C/C++ language header file, are installed with APS on the Policy Server under the SDK directory.

The API is supplied for C/C++ and COM only. If it must be called from Java, it is up to the site to build a JNI interface to the API, though a JNI interface may be provided with a future release. It is not possible at this time to produce a native Java API, because the APS API calls into the SiteMinder Agent API, which is C/C++ only. Thus, a JNI call must be made at that point. The SiteMinder Agent API remains C/C++ only for security reasons.

CA Professional Services can be contracted to write programs that use this API and can be contracted to help architect applications that use it. However, we do not provide direct support for customer-written programs that use the API. Since APS includes utilities (such as SmCPW and APSAdmin) that call the API, the API itself can be tested cleanly without using customer code. Failures in customer code should be tested using a CA-supplied interface before calling for support.

This section contains the following topics:

Compiling & Linking

Run-Time Requirements

Function Descriptions

Compiling & Linking

The APSAPI package includes a file called APSAPI.h, which contains all of the function definitions for the API. This file must be included in your source code in order to declare the functions.

When linking under Windows, you will need APSAPI.lib (also provided with the APSAPI kit). This file contains information that the linker needs to connect your program to APSAPI.DLL.

Under Solaris, you can specify libAPSAPI.so in your makefile for linking purposes.

Run-Time Requirements

Each of the functions has different requirements as to how it communicates with APS. See the description of each function below to determine the specific requirements.

If a function is to be called remotely (in other words, the program using the API will not be resident on a Policy Server with APS installed), then that machine will require that a configured copy of SmPortal be installed. SmPortal is used to communicate with a SiteMinder Policy Server.

Function Descriptions

IsPasswordValid

Synopsis:

This function can be used to determine if an arbitrary password is valid. It is intended to be used by Administrator Password Reset type applications. It does not check historical information.

Prototype:

bool IsPasswordValid (

const char*

lpszUserPath,

 

const char*

lpszPassword,

 

char*

lpszErrorBuffer,

 

int

nErrorBufferSize,

 

const char*

lpszLanguage = NULL,

 

const char*

lpszCountry = NULL,

 

const char*

lpszQualifier = NULL);

Callable:

Locally (direct), if available, otherwise Remote (SmPortal)

Returns:

True if the password is valid, otherwise false.

Arguments:

const char* lpszUserPath

The full path to a user. This is in the format

LDAP://<server>/<DN>

or

WinNT://<server>/<user>.

It is used to determine which settings are in effect, the actual user record is not checked (it need not even exist). This value can be supplied as NULL.

const char* lpszPassword

The actual password to check. Cannot be NULL.

char* lpszErrorBuffer

A caller-supplied buffer to contain any returned error message. This may be the error message describing why the password is invalid or it may describe communications or parameter errors.

int nErrorBufferSize

The size of error message buffer above.

const char* lpszLanguage

The ISO-standard code of the desired language that the error message should be provided in. This argument can be supplied as NULL. If so, EN will be used.

const char* lpszCountry

The ISO-standard code of the desired country (locale) that the error message should be provided in. This argument can be supplied as NULL.

const char* lpszQualifier

This argument is usually supplied as NULL, meaning no qualifier. If supplied, it will be used to qualify the service name provided to SmPortal (has no effect when the API is called locally), so that multiple Policy Servers can be used by the API from the same source computer.

Description:

This function generically checks to see if a password is valid. Typically, it is called by administration programs, since the current password is not needed.

The lpszUserPath argument is used to determine which settings apply; the user does not need to actually exist.

Note: The case (upper/lower) of the user's password must change, this function will return UPPER or LOWER in the lpszErrorBuffer argument and return a successful result. If the calling application is going to write this new password to the User's Directory entry, the password's case must be changed before modification.

Limitations:

Even if the following settings are specified in APS.Cfg, this function does not evaluate:

IsMyPasswordValid

Synopsis:

This function can be used to determine if a password is valid for a particular user. It is intended to be used by user-initiated password changes (though it is not needed, since ChangeMyPassword() also performs this function)

Prototype:

Bool IsMyPasswordValid(

const char*

lpszUserPath,

 

const char*

lpszOldPassword,

 

const char*

lpszNewPassword,

 

char*

lpszErrorBuffer,

 

int

nErrorBufferSize,

 

const char*

lpszLanguage = NULL,

 

const char*

lpszCountry = NULL,

 

const char*

lpszQualifier = NULL);

Callable:

Remote Only (SmPortal)

Returns:

True if the password is valid, otherwise false.

Arguments:

const char* lpszUserPath

The full path to a user. This is in the format

LDAP://<server>/<DN>

or

WinNT://<server>/<user>.

This value cannot be supplied as NULL.

const char* lpszOldPassword

The existing password on the user account. Cannot be NULL.

const char* lpszNewPassword

The new password to check. Cannot be NULL.

char* lpszErrorBuffer

A caller-supplied buffer to contain any returned error message. This may be the error message describing why the password is invalid or it may describe communications or parameter errors.

int nErrorBufferSize

The size of error message buffer above.

const char* lpszLanguage

The ISO-standard code of the desired language that the error message should be provided in. This argument can be supplied as NULL. If so, EN will be used.

const char* lpszCountry

The ISO-standard code of the desired country (locale) that the error message should be provided in. This argument can be supplied as NULL.

const char* lpszQualifier

This argument is usually supplied as NULL, meaning no qualifier. If supplied, it will be used to qualify the service name provided to SmPortal (has no effect when the API is called locally), so that multiple Policy Servers can be used by the API from the same source computer.

Description:

This function checks to see if a password is valid for the specified user. This function actually is never needed, since ChangeMyPassword (below) will check a user's password before changing it.

This function will fail if lpszOldPassword is not valid for the account. If it is not valid, the in-memory Failure Count (for APS authentication) will be incremented (though not stored back to the directory). This may prevent users from being logged in or may cause users to be disabled. If the in-memory Failure Count exceeds Max Failures, this function will not work for that account.

Note: If the case (upper/lower) of the user's password must change, this function will return UPPER or LOWER in the lpszErrorBuffer argument and return a successful result. If the calling application is going to write this new password to the User's Directory entry, the password's case must be changed before modification.

Limitations:

This function requires SmPortal, even if called on the Policy Server, to ensure that the activity is logged to a SiteMinder console (since the user may be locked out).

IsMyPasswordValid2

Synopsis:

This function can be used to determine if a password is valid for a particular user. It is intended to be used by user-initiated password changes (though it is not needed, since ChangeMyPassword() also performs this function). This function is only callable from within Authentication Schemes.

Prototype:

bool IsMyPasswordValid2 (

const Sm_Api_Context_t*

lpApiContext,

 

const char*

lpszUserPath,

 

const char*

lpszOldPassword,

 

const char*

lpszNewPassword,

 

char*

lpszErrorBuffer,

 

int

nErrorBufferSize,

 

const char*

lpszLanguage=NULL,

 

const char*

lpszCountry=NULL);

Callable:

Local Only (from Authentication Scheme)

Returns:

True if the password is valid, otherwise false.

Arguments:

const Sm_Api_Context_t* lpApiContext

API Context as passed from SiteMinder to the calling Authentication scheme.

const char* lpszUserPath

The full path to a user. This is in the format

LDAP://<server>/<DN>

or

WinNT://<server>/<user>.

This value cannot be supplied as NULL.

const char* lpszOldPassword

The existing password on the user account. Cannot be NULL.

const char* lpszNewPassword

The new password to check. Cannot be NULL.

char* lpszErrorBuffer

A caller-supplied buffer to contain any returned error message. This may be the error message describing why the password is invalid or it may describe communications or parameter errors.

int nErrorBufferSize

The size of error message buffer above.

const char* lpszLanguage

The ISO-standard code of the desired language that the error message should be provided in. This argument can be supplied as NULL. If so, EN will be used.

const char* lpszCountry

The ISO-standard code of the desired country (locale) that the error message should be provided in. This argument can be supplied as NULL.

Description:

This function checks to see if a password is valid for the specified user. This function actually is never needed, since ChangeMyPassword (below) will check a user's password before changing it.

This function will fail if lpszOldPassword is not valid for the account. If it is not valid, the in-memory Failure Count (for APS authentication) will be incremented (though not stored back to the directory). This may prevent users from being logged in or may cause users to be disabled. If the in-memory Failure Count exceeds Max Failures, this function will not work for that account.

Note: If the case (upper/lower) of the user's password must change, this function will return UPPER or LOWER in the lpszErrorBuffer argument and return a successful result. If the calling application is going to write this new password to the User's Directory entry, the password's case must be changed before modification.

Limitations:

This function must be called from within an Authentication Scheme, since it requires the ApiContext. Do not attempt to create your own ApiContext structure, this function will not work.

ChangeMyPassword

Synopsis:

This function can be used to change a user's password. The password is checked for validity before the change is actually made. It is intended to be used by user-initiated password changes.

Prototype:

bool ChangeMyPassword(

const char*

lpszUserPath,

 

const char*

lpszOldPassword,

 

const char*

lpszNewPassword,

 

char*

lpszErrorBuffer,

 

int

nErrorBufferSize,

 

const char*

lpszLanguage = NULL,

 

const char*

lpszCountry = NULL,

 

const char*

lpszQualifier = NULL);

Callable:

Remote Only (SmPortal)

Returns:

True if the password is changed, otherwise false.

Arguments:

const char* lpszUserPath

The full path to a user. This is in the format

LDAP://<server>/<DN>

or

WinNT://<server>/<user>.

This value cannot be supplied as NULL.

const char* lpszOldPassword

The existing password on the user account. Cannot be NULL.

const char* lpszNewPassword

The new password to store. Cannot be NULL.

char* lpszErrorBuffer

A caller-supplied buffer to contain any returned error message. This may be the error message describing why the password is invalid or it may describe communications or parameter errors.

int nErrorBufferSize

The size of error message buffer above.

const char* lpszLanguage

The ISO-standard code of the desired language that the error message should be provided in. This argument can be supplied as NULL. If so, EN will be used.

const char* lpszCountry

The ISO-standard code of the desired country (locale) that the error message should be provided in. This argument can be supplied as NULL.

const char* lpszQualifier

This argument is usually supplied as NULL, meaning no qualifier. If supplied, it will be used to qualify the service name provided to SmPortal (has no effect when the API is called locally), so that multiple Policy Servers can be used by the API from the same source computer.

Description:

This function checks to see if a password is valid for the specified user. If so, the user's password is changed to the new value.

This function will fail if lpszOldPassword is not valid for the account. If it is not valid, the in-memory Failure Count (for APS authentication) will be incremented (though not stored back to the directory). This may prevent users from being logged in or may cause users to be disabled. If the in-memory Failure Count exceeds Max Failures, this function will not work for that account.

Note: If the case (upper/lower) of the user's password must change, this function will return UPPER or LOWER in the lpszErrorBuffer argument and return a successful result.

Limitations:

This function requires SmPortal, even if called on the Policy Server, to ensure that the activity is logged to a SiteMinder console (since the user may be locked out).

ChangeMyPassword2

Synopsis:

This function can be used to change a user's password. The password is checked for validity before the change is actually made. It is intended to be used by user-initiated password changes. This version can only be called from within an authentication scheme.

Prototype:

bool ChangeMyPassword2 (

const Sm_Api_Context_t*

lpApiContext,

 

const char*

lpszUserPath,

 

const char*

lpszOldPassword,

 

const char*

lpszNewPassword,

 

char*

lpszErrorBuffer,

 

int

nErrorBufferSize,

 

const char*

lpszLanguage = NULL,

 

const char*

lpszCountry = NULL);

Callable:

Local Only (from within an Authentication Scheme)

Returns:

True if the password is changed, otherwise false.

Arguments:

const Sm_Api_Context_t* lpApiContext

API Context as passed from SiteMinder to the calling Authentication scheme.

const char* lpszUserPath

The full path to a user. This is in the format 

LDAP://<server>/<DN>

or

WinNT://<server>/<user>.

This value cannot be supplied as NULL.

const char* lpszOldPassword

The existing password on the user account. Cannot be NULL.

const char* lpszNewPassword

The new password to store. Cannot be NULL.

char* lpszErrorBuffer

A caller-supplied buffer to contain any returned error message. This may be the error message describing why the password is invalid or it may describe communications or parameter errors.

int nErrorBufferSize

The size of error message buffer above.

const char* lpszLanguage

The ISO-standard code of the desired language that the error message should be provided in. This argument can be supplied as NULL. If so, EN will be used.

const char* lpszCountry

The ISO-standard code of the desired country (locale) that the error message should be provided in. This argument can be supplied as NULL.

Description:

This function checks to see if a password is valid for the specified user. If so, the user's password is changed to the new value.

This function will fail if lpszOldPassword is not valid for the account. If it is not valid, the in-memory Failure Count (for APS authentication) will be incremented (though not stored back to the directory). This may prevent users from being logged in or may cause users to be disabled. If the in-memory Failure Count exceeds Max Failures, this function will not work for that account.

Note: If the case (upper/lower) of the user's password must change, this function will return UPPER or LOWER in the lpszErrorBuffer argument and return a successful result.

Limitations:

This function must be called from within an Authentication Scheme, since it requires the ApiContext. Do not attempt to create your own ApiContext structure, this function will not work.

Authenticate

Synopsis:

This function can be used from within an Authentication Scheme to allow APS to evaluate the Authentication. It will return any redirection that is a result of the authentication. It can only be called from an Authentication Scheme.

Prototype:

int Authenticate (

const Sm_Api_Context_t*

lpApiContext,

 

const Sm_Api_UserContext_t*

lpUserContext,

 

Sm_AuthApi_Status_t*

Status,

 

const char*

lpszParams,

 

char*

lpszRedirect,

 

int

nRedirectLen);

Callable:

Local, from within an Authentication Scheme Only

Returns:

Always returns zero.

Arguments:

const Sm_Api_Context_t* lpApiContext

API Context as passed from SiteMinder to the calling Authentication scheme.

const Sm_Api_UserContext_t* lpUserContext

User Context as passed from SiteMinder to the calling Authentication scheme.

Sm_AuthApi_Status_t* Status

The status of the authentication. APS can change this status.

const char* lpszParams

Parameters that would be passed to SmApsRedirect, such as macros or a default redirection.

char* lpszRedirect

A caller-supplied buffer in which to return any redirection.

int nRedirectLen

Length of passed redirection buffer

Description:

This function can be called from an authentication scheme to perform the standard authentication time APS checks. Under normal circumstances, this is not required, since SiteMinder will automatically make this call; however, there are some unusual situations where this call will be required.

You must make sure that SiteMinder does not call this function when it is called from an Authentication Scheme. You can do this by disabling Password Services for this Authentication Scheme (a checkbox on the Authentication Scheme definition panel in the SiteMinder Policy Interface).

APS assumes that all authentication checking has already been done before this call is made (this call should not be made during the disambiguation phase). The value of the Status argument reflects the current state of authentication, pass or fail.

Limitations:

This function can only be called by an Authentication Scheme. It requires in-memory structures provided by SiteMinder (and a few that are not passed as arguments), so it can never be called from anywhere else.

APSAdminGetDirectory

Synopsis:

APSAdminGetDirectory retrieves a list of the User Directories (supported by APSAdmin) that are defined to the SiteMinder Policy Server. A valid Administrator name/password (for the password GUI, not for the User Directory) must be passed. This administrator id must have rights to Users.

The information is returned in XML format.

Prototype:

int APSAdminGetDirectory (

const char*

Administrator,

 

char*

lpszOutput,

 

int

nOutputSize,

 

char*

lpszErrorBuffer,

 

int

nErrorBufferSize,

 

const char*

lpszLanguage = NULL,

 

const char*

lpszCountry = NULL,

 

const char*

lpszQualifier = NULL);

Callable:

Remote Only (SmPortal)

Returns:

Error Code. One of the following:

Arguments:

const char* Administrator

The credentials of an administrator defined to the SiteMinder Policy Server User Interface (GUI). This is not a SiteMinder login. This administrator must have User Management rights. Both the administrator ID and the password must be supplied, separated by a semicolon (";"). The combination can be passed encrypted (using APSEncrypt).

char* lpszOutput

A buffer to hold the returned XML.

int nOutputSize

The maximum size of lpszOutput.

char* lpszErrorBuffer

Returned error message

Int nErrorBufferSize

The maximum size of lpszErrorBuffer

const char* lpszLanguage

The desired language of any error messages. Defaults to EN.

const char* lpszCountry

The desired country (locale) of and error messages. Defaults to US.

const char* lpszQualifier

Not used at this time.

Description:

The result is returned in lpszOutput in XML format. The XML is self-contained; that is, it contains its own DTD (it does not refer to an external DTD).

At the time of this writing, the DTD is as follows:

<!DOCTYPE APSGetDirectory [
<!ELEMENT UserDirectories (UserDirectory*)>
<!ELEMENT UserDirectory (#PCDATA)>
<!ATTLIST UserDirectory name CDATA #REQUIRED>
]>

All LDAP and ODBC directories are returned. The name returned is the Description field in the User Directory definition in SiteMinder. The data is the server definition (usually the IP address). A directory will not to be returned if the description of the directory (as defined to SiteMinder) begins with a pound sign ("#"). The data is the server definition (usually the IP address).

This function is used by APSAdmin to get a list of the available directories for user lookup.

Limitations:

APSAdminGetDirectory only returns LDAP and ODBC directories.

APSAdminRead

Synopsis:

APSAdminRead retrieves information about a specified user and returns it in XML format. The information returned is defined in the APS Configuration file (in the APSAdmin section).

A valid Administrator name/password (for the password GUI, not for the User Directory) must be passed. This administrator id must have rights to Users.

Prototype:

int APSAdminRead

(const char*

Administrator,

 

const char*

AdminUserPath,

 

const char*

TargetUserPath,

 

char*

lpszOutput,

 

int

nOutputSize,

 

char*

lpszErrorBuffer,

 

int

nErrorBufferSize,

 

const char*

lpszMacros = NULL,

 

const char*

lpszLanguage = NULL,

 

const char*

lpszCountry = NULL,

 

const char*

lpszQualifier = NULL);

Callable:

Remote Only (SmPortal)

Returns:

If > 0, it is the number of attributes returned.

One of the following error codes if < 0:

Arguments:

const char* Administrator

The credentials of an administrator defined to the SiteMinder Policy Server User Interface (GUI). This is not a SiteMinder login. This administrator must have User Management rights. Both the administrator ID and the password must be supplied, separated by a semicolon (";"). The combination can be passed encrypted (using APSEncrypt).

const char* AdminUserPath

The fully qualified path name of the administrator. This is the SiteMinder login user, not the SiteMinder GUI administrator.

This value is a full user path in the form

<Namespace>://<server>/<user>,

such as:

LDAP://127.0.0.1/uid=erict,o=Airius.com

const char* TargetUserPath

The fully qualified path to the user whose information is to be retrieved.

This value is a full user path in the form

<Namespace>://<server>/<user>,

such as:

LDAP://127.0.0.1/uid=erict,o=Airius.com

char* lpszOutput

A buffer to hold the returned XML.

int nOutputSize

The maximum size of lpszOutput.

char* lpszErrorBuffer

Returned error message

int nErrorBufferSize

The maximum size of lpszErrorBuffer

const char* lpszMacros

Any macros desired in the form <name>=<value>, multiples separated by semicolons. These can be used as context macros in override expressions in the APS.cfg file.

const char* lpszLanguage

The desired language of any error messages. Defaults to EN.

const char* lpszCountry

The desired country (locale) of and error messages. Defaults to US.

const char* lpszQualifier

Not used at this time.

Description:

The result is returned in lpszOutput in XML format. The XML is self-contained; that is, it contains its own DTD (it does not refer to an external DTD).

<!DOCTYPE APSReadUser [
<!ELEMENT User (Attribute|Section|Group)*>
<!ATTLIST User name CDATA #REQUIRED>
<!ATTLIST User disabled CDATA "">
<!ELEMENT Section (Attribute|Group)+>
<!ATTLIST Section name CDATA #IMPLIED>
<!ATTLIST Section prompt CDATA #IMPLIED>
<!ELEMENT Attribute (Value*)><!ATTLIST Attribute name CDATA #REQUIRED>
<!ATTLIST Attribute read (true|false) "false">
<!ATTLIST Attribute write (true|false) "false">
<!ATTLIST Attribute prompt CDATA #IMPLIED>
<!ATTLIST Attribute redisable (true|false) "false">
<!ELEMENT Group EMPTY>
<!ATTLIST Group name CDATA #REQUIRED>
<!ATTLIST Group read (true|false) "false">
<!ATTLIST Group write (true|false) "false">
<!ATTLIST Group prompt CDATA #IMPLIED>
<!ATTLIST Group member (true|false|restricted) "restricted">
<!ATTLIST Group reasoncode CDATA #IMPLIED>
<!ELEMENT Value (#PCDATA)>
]>

The specific fields/groups returned for a given user are defined in the APS Configuration file (in the APSAdmin section). The field and group names should be abstracted (they will not usually reflect the "real" name of the underlying attribute).

APSAdminRead has restrictions on certain APS fields. For example, smapsNextAction cannot be read/write. If specified that way, the API will only return it as readable, not writeable.

Limitations:

All attributes are available within limits. Certain attributes may be suppressed for reading (such as userPassword and smapsHistory) and others are suppressed for writing (such as smapsHistory and smapsNextAction).

APSAdminWrite

Synopsis:

APSAdminWrite updates information about a specified user supplied in XML format. It cannot create a new user. The fields that can be updated are defined in the APS Configuration file.

A valid Administrator name/password (for the password GUI, not for the User Directory) must be passed. This administrator id must have rights to Users.

Prototype:

int APSAdminWrite

(const char*

Administrator,

 

const char*

AdminUserPath,

 

const char*

Instructions,

 

char*

lpszErrorBuffer,

 

int

nErrorBufferSize,

 

const char*

lpszMacros = NULL,

 

const char*

lpszLanguage = NULL,

 

const char*

lpszCountry = NULL,

 

const char*

lpszQualifier = NULL);

Callable:

Remote Only (SmPortal)

Returns:

If > 0, it is the number of attributes actually updated.

One of the following error codes if < 0:

Arguments:

const char* Administrator

The credentials of an administrator defined to the SiteMinder Policy Server User Interface (GUI). This is not a SiteMinder login. This administrator must have User Management rights. Both the administrator ID and the password must be supplied, separated by a semicolon (";"). The combination can be passed encrypted (using APSEncrypt).

const char* AdminUserPath

The fully qualified path name of the administrator. This is the SiteMinder login user, not the SiteMinder GUI administrator.

This value is a full user path in the form <Namespace>://<server>/<user>, such as:

LDAP://127.0.0.1/uid=erict,o=Airius.com

const char* Instructions

The XML instructions for the update. The user to be updated is defined in the XML.

char* lpszErrorBuffer

Returned error message

int nErrorBufferSize

The maximum size of lpszErrorBuffer

const char* lpszMacros

Any macros desired in the form <name>=<value>, multiples separated by semicolons. These can be used as context macros in override expressions in the APS.cfg file.

const char* lpszLanguage

The desired language of any error messages. Defaults to EN.

const char* lpszCountry

The desired country (locale) of and error messages. Defaults to US.

const char* lpszQualifier

Not used at this time.

Description:

The updates to be performed are supplied in the Instructions argument.

The XML should be formatted according to the following DTD (any contained DTD in the XML is ignored).

<!DOCTYPE APSWriteUser [
<!ELEMENT User (Attribute|Group)*>
<!ATTLIST User name CDATA #REQUIRED>
<!ELEMENT Attribute (Value*)>
<!ATTLIST Attribute name CDATA #REQUIRED>
<!ELEMENT Group EMPTY>
<!ATTLIST Group name CDATA #REQUIRED>
<!ATTLIST Group member ("1"|"0") #REQUIRED>
<!ELEMENT Value (#PCDATA)>
]>

Limitations:

APS will not write some fields regardless of its configuration. There is also special processing for certain fields by name.

With the exception of smapsNextAction, if an attribute does not appear, it will not be updated.