com.netegrity.policyserver.smapi
Interface SmAuthScheme

public interface SmAuthScheme

The base interface in the Java Authentication API that each custom authentication scheme class must implement. SiteMinder calls the methods in the custom class.

The Java Authentication API allows you to create custom authentication schemes to provide authentication services not offered by any of the standard SiteMinder authentication schemes. See Create a Custom Authentication Scheme in the Programming Guide for Java for general information about authentication schemes.

Other classes in the Java Authentication API:

• SmAuthenticationContext
• SmAuthenticationResult
• SmAuthQueryCode
• SmAuthQueryResponse
• SmAuthStatus
• UserCredentialsContext

In addition, the Java Authentication API uses the following common classes. These classes are available to both the Java Authentication API and the Java Authorization API.

• APIContext
• AppSpecificContext
• SmJavaApiException
• UserContext

Since:

SDK 6.0

Method Summary

SmAuthenticationResult	authenticate(java.lang.String parameter, java.lang.String secret, int challengeReason, SmAuthenticationContext context) Performs the custom authentication and returns the authentication result.
SmAuthStatus	init(java.lang.String parameter, java.lang.String secret) Performs any initialization procedures that the authentication scheme requires.
SmAuthStatus	query(java.lang.String parameter, java.lang.String secret, SmAuthQueryCode request, SmAuthQueryResponse response) Returns information about the authentication scheme or about the kind of credentials that the authentication scheme requires.
SmAuthStatus	release(java.lang.String parameter, java.lang.String secret) Performs any rundown procedures that the authentication scheme requires.

Method Detail

query

SmAuthStatus query(java.lang.String parameter,
                   java.lang.String secret,
                   SmAuthQueryCode request,
                   SmAuthQueryResponse response)

Returns information about the authentication scheme or about the kind of credentials that the authentication scheme requires. The type of information returned to SiteMinder depends upon the type of information SiteMinder specifies when calling the method.

SiteMinder passes the type of information it is looking for in the request parameter. The authentication scheme returns the information in the output parameter response.

Parameters:

parameter - The optional parameter string specified in the Policy Server User Interface, to be used in any way that the authentication scheme requires.

secret - The shared secret specified for the authentication scheme in the Policy Server User Interface. The shared secret is used for any purpose that the authentication scheme requires, such as enryption or credentials operations. Your authentication scheme may or may not require a shared secret.

request - The request code. The type of information that the authentication scheme returns in response depends upon the request code that SiteMinder passes, as follows:

• SMAUTH_QUERY_DESCRIPTION.
• SMAUTH_QUERY_CREDENTIALS_REQ.

response - The requested information to pass back to SiteMinder.

Returns:

SMAUTH_SUCCESS on success, or SMAUTH_FAILURE on failure.

init

SmAuthStatus init(java.lang.String parameter,
                  java.lang.String secret)

Performs any initialization procedures that the authentication scheme requires.

SiteMinder calls this method once for each authentication scheme instance, when the authentication scheme is loaded.

Parameters:

parameter - The optional parameter string specified in the Policy Server User Interface, to be used in any way that the authentication scheme requires.

secret - The shared secret specified for the authentication scheme in the Policy Server User Interface. The shared secret is used for any purpose that the authentication scheme requires, such as enryption or credentials operations. Your authentication scheme may or may not require a shared secret.

Returns:

SMAUTH_SUCCESS on success, or SMAUTH_FAILURE on failure.

release

SmAuthStatus release(java.lang.String parameter,
                     java.lang.String secret)

Performs any rundown procedures that the authentication scheme requires.

SiteMinder calls this method once for each authentication scheme instance, when SiteMinder is shutting down.

Parameters:

parameter - The optional parameter string specified in the Policy Server User Interface, to be used in any way that the authentication scheme requires.

secret - The shared secret specified for the authentication scheme in the Policy Server User Interface. The shared secret is used for any purpose that the authentication scheme requires, such as enryption or credentials operations. Your authentication scheme may or may not require a shared secret.

Returns:

SMAUTH_SUCCESS on success, or SMAUTH_FAILURE on failure.

authenticate

SmAuthenticationResult authenticate(java.lang.String parameter,
                                    java.lang.String secret,
                                    int challengeReason,
                                    SmAuthenticationContext context)

Performs the custom authentication and returns the authentication result.

SiteMinder calls this method at least twice -- during user disambiguation and during user authentication. For information about these two phases of the authentication process, see the Programming Guide for Java.

Parameters:

parameter - The optional parameter string specified in the Policy Server User Interface, to be used in any way that the authentication scheme requires.

secret - The shared secret specified for the authentication scheme in the Policy Server User Interface. The shared secret is used for any purpose that the authentication scheme requires, such as enryption or credentials operations. Your authentication scheme may or may not require a shared secret.

challengeReason - The reason code from a previous authentication that failed or was challenged, or 0 if unknown. The reason code that SiteMinder passes is the REASON_ constant that the authentication scheme returned in SmAuthenticationResult after the failed or challenged authentication.

context - Contains request context objects, and also methods for passing error and user messages directly to SiteMinder.

Returns:

An SmAuthenticationResult object containing status and reason codes. How the returned status code is interpreted depends upon the phase during which SiteMinder called the authentication scheme, as follows:

• User disambiguation phase
  • SMAUTH_NO_USER_CONTEXT
    The authentication scheme asks SiteMinder to disambiguate the user. When returning this status code, pass an empty string in setUserText().
  • SMAUTH_SUCCESS The authentication scheme asks SiteMinder to disambiguate the user. When returning this status code, pass the user's login ID in setUserText().
  • SMAUTH_SUCCESS_USER_DN
    The authentication scheme disambiguates the user and passes the user's complete DN or ODBC database ID to SiteMinder in setUserText(). Only one DN or database ID can be passed at one time.
  • SMAUTH_ATTEMPT
    The user cannot be found in the directory.
  • SMAUTH_FAILURE
    An error occurred. Return any error text through setUserText().
• User authentication phase
  • SMAUTH_ACCEPT
    The user is authenticated.
  • SMAUTH_REJECT
    The user is not authenticated.
  • SMAUTH_CHALLENGE
    The user is challenged. The scheme passes the challenge message to SiteMinder through setUserText(). Also, a reason code must be supplied in the SmAuthenticationResult object returned by authenticate(). SiteMinder will pass back this reason code in the challengeReason parameter in a subsequent call to authenticate().
  • SMAUTH_FAILURE
    An error occurred. Return any error text through setUserText().

For more information about using and interpreting these status codes during user disambiguation and user authentication, see the Programming Guide for Java.