Configuring user-defined authentication in IAG

  • Article

Applies To: Intelligent Application Gateway (IAG)

This topic describes how you can implement a custom authentication scheme, which is not one of the schemes that Whale Communications Intelligent Application Gateway (IAG) 2007 supports out-of-the-box.

Creating a custom authentication scheme

To implement a user-defined authentication scheme

  1. In the IAG Configuration console, in the Authentication and User/Group Servers dialog box, define an authentication server of type "Other".

  2. Copy the file repository.inc from the following location:

    ...\Whale-Com\e-Gap\von\InternalSite\samples

    Paste the file repository.inc in the following custom folder; if it does not exist, create it:

    ...\Whale-Com\e-Gap\von\InternalSite\inc\CustomUpdate

  3. Rename the file as follows:

    < Server_Name >.inc

    Where <Server_Name> is the name of the authentication server you defined in step 1.

    For example:

    If you named the server "CustomAuth", name the file CustomAuth.inc

  4. The file includes five functions. You can edit any of the functions in order to define your custom implementation; delete any functions where you wish to apply the default implementation.

    Tip

    You can see a sample implementation under the samples folder, in the file repository_for_cert.inc.

Authentication scheme functions

This section describes the functions that are used to define the authentication scheme.

Function Return Value

CheckCredentials(user_name, password)

Boolean

CheckChallenge(challenge)

Boolean

AuthenticateRepositoryUser(repository,user_name,password)

And,

ContinueAuthenticateRepositoryUser(repository,handle,challenge,challenge_code)

Object "UserMgrComLayer.AuthenticateUserOut"

The function sets the following fields:

  • Success

  • ErrorCode

  • Handle

  • Message

  • FullUserName

For a description of the fields, see the section "Authentication scheme object fields".

ChangeRepositoryUserPassword(repository,user_name,password,new_password)

Object "UserMgrComLayer.ChangePasswordOut"

The function sets the following fields:

  • Success

  • ErrorCode

  • Handle

  • Message

For a description of the fields, see the section "Authentication scheme object fields".

Authentication scheme object fields

This section describes the fields that are used by the objects that some of the authentication scheme functions return. For more information about the functions and the objects they can return, see the section "Authentication scheme functions".

Success

The value that is returned by the Success field determines the next step of the authentication. It can be one of the following:

  • AUTHENTICATE_SUCCESS: authentication succeeded, users are redirected to PostValidate.asp, or, if further authentication with different credentials is required, to Validate.asp.

  • AUTHENTICATE_FAIL: authentication failed, users are redirected to the error page InternalError.asp.

  • AUTHENTICATE_CONTINUE: users need to continue the authentication process and are redirected to LoginContinue.asp. For example: when the authentication server operates in a "Next Token" challenge-response mode and users are required to enter a tokencode.

  • AUTHENTICATE_AGAIN: users need to reauthenticate and are redirected to the Login.asp again.

  • CHANGE_PASSWORD: users are redirected to LoginChangePassword.asp, where they are required to change their password.

  • PASSWORD_EXPIRATION_THRESHOLD: the password expiration threshold was reached. Users are redirected to PasswordExpired.asp, where they are notified that the password is about to expire within a predefined number of days and can change their password.

ErrorCode

The value that is returned by the ErrorCode field provides additional details on the value that is returned by the Success field. It can be one of the following:

  • ERROR_CODE_FAILED_TO_AUTHENTICATE: user failed to authenticate.

  • ERROR_CODE_SUCCEEDED_TO_AUTHENTICATE: user successfully authenticated.

  • ERROR_CODE_CHANGE_PASSWORD: user is required to change the password.

  • ERROR_CODE_FAILED_TO_CHANGE_PASSWORD: user failed to change the password.

  • ERROR_CODE_PASSWORD_POLICY_NOT_OK: user failed to change the password; the new password does not comply with the password policy set by the administrator.

  • ERROR_CODE_USER_IS_BLOCKED: authentication failed since the user's account is blocked.

  • ERROR_CODE_USER_DEFINED: the message that the user receives in the next page contains the content of the Message field.

When the value of the Success field is AUTHENTICATE_CONTINUE, the authentication needs to be continued. The "ErrorCode" determines what type of "continue" is required and what message is displayed to the user. In this case, the value of ErrorCode can be one of the following:

  • ERROR_CODE_CONTINUE_AUTHENTICATE_TYPE_1: used for New PIN challenge-response mode, when the authentication server supplies the user with the new PIN. The following message is displayed to the user: "Your current PIN is invalid. Your new PIN is: <new PIN, as appears in the Message field>".

  • ERROR_CODE_CONTINUE_AUTHENTICATE_TYPE_2: used for Next Token challenge-response mode. The following message is displayed to the user: "Your token needs to be validated. Please wait for the current tokencode to change, and enter the next tokencode"

  • ERROR_CODE_CONTINUE_AUTHENTICATE_TYPE_3: used for New PIN challenge-response mode, when the user is prompted to enter the new PIN. The following message is displayed to the user: "Your current PIN is invalid. Please enter a new PIN (4-8 digits)"

  • ERROR_CODE_CONTINUE_AUTHENTICATE_TYPE_4: the message contains the text that is received in the Message field.

Handle

The Handle field is used when the authentication process needs to continue. It contains a value that is used by the authentication server in order to identify the user.

Message

The Message field contains text that is received from the authentication server, and it can be one of the following:

  • User's new PIN, generated by the server

  • Server-generated message

  • Number of remaining days until the password expires

  • User-defined text in the custom pages

FullUserName

The FullUserName field contains the user name.