Post-installation tasks

There are a couple of tasks that you usually need to complete after you have installed the Digipass Authentication Module software.

Set up the response-only logon page

An example logon page (logon.aspx) is delivered together with Digipass Authentication for OWA Forms. If this example logon page exactly matches the OWA installation you are using, you can use this template as the logon page. No further configuration steps are necessary.

Open the logon.aspx file to determine which version of OWA you are using.

To set up the Response-Only logon page

1. Back up the existing logon page.

2. Replace the existing page with the supplied logon page in %PROGRAMFILES%\OneSpan\Digipass Authentication for OWA Forms\Templates\OWAFversion\logon.aspx.

   -OR-

   Modify the existing page with custom code.

   Modifying the existing page with custom OneSpan code should only be used as an alternative if copying over the templates does not work. This might be the case because the logon page was modified by Microsoft, e.g. with a patch. In that case, you need to modify the page manually: compare the template with the original file and merge the Digipass sections into the original file.

   Be careful to insert the code to the correct location in the file. Refer to the example file delivered with Digipass Authentication for OWA Forms to find out where the custom code needs to go in your custom logon page.

Set up 1-step challenge/response logon

This step is only required if 1-step Challenge/Response is being implemented.

Implementing 1-step Challenge/Response logon requires a modification of the logon page used by OWA. You can use the example logon page, which is located in %PROGRAMFILES%\OneSpan\Digipass Authentication for OWA Forms\Templates\OWAF VERSION. To use a logon page which has been customized for your company, e.g., colors and graphics, see Modify the custom logon page.

To configure the authentication server

• Enable 1-step Challenge/Response in the policy for the Digipass Authentication Module client record. For more information about the policy settings required for 1-step Challenge/Response, see Policy.

To configure the Digipass Authentication Module

• Enable 1-step Challenge/Response in the Digipass Authentication for OWA Forms Configuration Center. You can do so for the main website, or for a dedicated website only for 1-step Challenge/Response logons.

To configure the logon page

1. Back up owa_directory\auth\logon.aspx to a suitable place.

2. To use the default logon page supplied with Digipass Authentication for OWA Forms, copy the logon page from %PROGRAMFILES%\OneSpan\Digipass Authentication for OWA Forms\Templates\OWAF VERSION\logon.aspx to %windir%\web\owa_directory\auth\logon.aspx.

   -OR-

   modify the existing page with OneSpan code.

   Modifying the existing page with custom OneSpan code should only be used as an alternative if copying over the templates does not work. This might be the case because the logon page was modified by Microsoft, e.g. with a patch. In that case, you need to modify the page manually: compare the template with the original file and merge the Digipass sections into the original file.

Modify the custom logon page

If your current logon page is not the standard OWA logon page, you may need to modify it rather than replace it with the logon page provided with the Digipass Authentication Module.

When the Digipass Authentication Module detects a request for the logon page, it adds the following headers to the request before passing it on:

• VASCO-Challenge: contains the string challenge to be displayed to the user, e.g. 1234

• VASCO-State: contains data that needs to be passed as the VMExtState field on the logon request.

To modify the custom logon page for 1-step Challenge/Response

1. Back up owa_installation_folder\auth\logon.aspx to a suitable place.

2. Open logon.aspx, which is located in %PROGRAMFILES%\OneSpan\Digipass Authentication for OWA Forms\Templates\OWAF version\.

3. Modify the existing page with OneSpan code.

   Copy the following code snippet to the appropriate location in your custom logon file:

   Make sure you insert the OneSpan code in the correct location in the file. Refer to the example logon file delivered with the Digipass Authentication Module to find out where the OneSpan code needs to go in your custom logon page.

<!-- DIGIPASS Authentication for OWA Forms modifications : START -->
        <!--The following is required for one-step-challenge response -->
        <%
        System.String VascoChallenge =
        Request.ServerVariables ["HTTP_VASCO_CHALLENGE"];
        System.String VascoState = Request.ServerVariables ["HTTP_VASCO_STATE"];

        if (!System.String.IsNullOrEmpty (VascoState) &&
        !System.String.IsNullOrEmpty (VascoChallenge)) {
        %>
        <tr>
        <td nowrap><label for="vascochallenge">Challenge: </label></td>
        <td class="txtpad">
        <input id="vascochallenge" name="challenge" type="text" class="txt" readonly="true" value="<%=VascoChallenge %>">
        </td>
        </tr>
        <input name='DPExtState' type='hidden' value='<%= VascoState %>'>
        <%
        }
        %>
        <!-- DIGIPASS Authentication for OWA Forms modifications : END -->

4. Save and close the custom logon file.

Display the logon failure reason

This step is mandatory for all installations where Return failure reason has been enabled.

You can configure the Digipass Authentication Module to pass information to OWA upon a failed authentication request. You can, for example, provide users with an explanation of why their logon failed, and with instructions to fix the problem. The authentication server will pass the error or status code and message text for the authentication server to OWA, which can then display the message verbatim or interpret the code to provide the user with a clear explanation or set of instructions.

Configure the logon page

You can replace the default OWA logon page with the one provided with the Digipass Authentication Module. This will allow OWA to display an authentication server error or status code and message on the user’s screen.

To display the logon failure reason

1. Back up owa_directory\auth\logon.aspx to a suitable place.

2. Copy the modified logon page from %PROGRAMFILES%\OneSpan\Digipass Authentication for OWA Forms\Templates\OWAF VERSION\logon.aspx (or other location if using a custom logon page) to %windir%\web\owa_directory\auth\logon.aspx.

3. In the Digipass Authentication for OWA Forms Configuration Center, select Return failure reason and specify the URL of the failed logon page.

Modify the custom logon page

If you have a custom logon.aspx page in use, you may need to modify it rather than replace it with the logon.aspx page provided with the Digipass Authentication Module.

The logon.aspx page will also be set up for 1-step Challenge/Response. However, these portions of the page will be ignored by the Digipass Authentication Module unless 1-step Challenge/Response is enabled in the configuration.

To modify the custom logon page for displaying the logon failure reason

1. Back up owa_installation_folder\auth\logon.aspx to a suitable place.

2. Open logon.aspx, which is located in %PROGRAMFILES%\OneSpan\Digipass Authentication for OWA Forms\Templates\OWAF version\.

3. Modify the existing page with OneSpan code.

   Copy the following code snippet to the appropriate location in your custom logon file:

   Make sure you insert the OneSpan code in the correct location in the file. Refer to the example logon file delivered with the Digipass Authentication Module to find out where the OneSpan code needs to go in your custom logon page.

   <!-- DIGIPASS Authentication for OWA Forms modifications : START -->
                   <!--The following is required to display DIGIPASS failure reason -->
                   <%
                   System.String VascoFailCode = System.Web.HttpUtility.UrlDecode(Request.QueryString["failcode"]);
                   System.String VascoFailMessage = System.Web.HttpUtility.UrlDecode(Request.QueryString["failmessage"]);
                   if (!System.String.IsNullOrEmpty(VascoFailCode)) VascoFailMessage = "(" + VascoFailCode + ") " + VascoFailMessage;
                   if (String.IsNullOrEmpty (VascoFaileMessageState))
                   {
                   %>
                   <!-- DIGIPASS Authentication for OWA Forms modifications : END -->

   <!-- DIGIPASS Authentication for OWA Forms modifications : START -->
                   <!--The following is required to display DIGIPASS failure reason -->
                   <%
                   }
                   else
                   {
                   %>
                   <td>DIGIPASS error:&nbsp;<%=VascoFailMessage%></td>
                   <%
                   }
                   %>
                   <!-- DIGIPASS Authentication for OWA Forms modifications : END -->

4. Save and close the custom logon file.

Create a 2-step challenge/response template

To set up the logon page for 2-step Challenge/Response logons

1. Back up the existing logon page.

2. Copy over the existing page with the supplied logon page in %PROGRAMFILES%\OneSpan\Digipass Authentication for OWA Forms\Templates\OWAF VERSION\logon.aspx.

   -OR-

   modify the existing page with OneSpan code.

   Modifying the existing page with custom OneSpan code should only be used as an alternative if copying over the templates does not work. This might be the case because the logon page was modified by Microsoft, e.g. with a patch. In that case, you need to modify the page manually: compare the template with the original file and merge the Digipass sections into the original file.

   Make sure you insert the OneSpan code in the correct location in the file. Refer to the example logon file delivered with the Digipass Authentication Module to find out where the OneSpan code needs to go in your custom logon page.

3. On the Authentication page of the Configuration Center, specify the HTML site for 2-step Challenge/Response.

   You can use the example Challenge_template.html page, which is located in %PROGRAMFILES%\OneSpan\Digipass Authentication for OWA Forms\Templates\Common. You can modify this template, or use the example template as is.

   The Challenge/Response template must be correctly labeled for the used character encoding, which is configured in the related site configuration. The template must contain a number of keywords which the extension will replace with the appropriate HTML code.

   These fields are:

   • DPEXT_FORM_METHOD. This is replaced with the configured form method. The replaced content represents the value of the method attribute of the HTML form.

   • DPEXT_FORM_ACTION. This is replaced with the configured logon submit URL path and query strings. The replaced content represents the value of the action attribute of the HTML form.

   • DPEXT_PASSWORD_FIELD_NAME. This is replaced with the configured password field name and has to be the value of the name attribute of the corresponding HTML form field.

   • DPEXT_CHALLENGE_TEXT. This string is replaced with the challenge issued.

   • DPEXT_HIDDEN_FIELDS. This is replaced with any fields submitted from the logon page and has to be part of the HTML form.

   These fields may appear more than once in the file, and each instance will be replaced.