Overview

The mod_authn_otp module is an Apache authentication provider. That basically means it knows how to retrieve the passwords corresponding to usernames when HTTP basic or digest authentication is performed.

Configuring Apache

As such, the first thing to do to enable one-time passwords is to tell Apache to use the OTP provider for authentication.

For example, if you want basic authentication you'd do something like this:

<Directory "/protected/stuff">
    AuthType basic
    AuthName "My Protected Area"
    AuthBasicProvider OTP
    Require valid-user
    # other options...
</Directory>

For digest authentication, you'd do something like this:

<Directory "/protected/stuff">
    AuthType digest
    AuthName "My Protected Area"
    AuthDigestProvider OTP
    Require valid-user
    # other options...
</Directory>

(but see the DigestAuthentication wiki page for limitations of OTP when used with digest authentication)

Next, sprinkle in whatever additional usual Apache configuration directives you want.

Note that the number of digits in a one-time password and the length of a single timer interval (for time based tokens) is configured in the UsersFile on a per-token basis.

Configuring mod_authn_otp

Finally, configure the mod_authn_otp specific directives:

A detailed description of each directive follows.

OTPAuthUsersFile

This directive configures the users file which is plain text file that functions as mod_authn_otp's database.

The system file permissions assigned to this file and its containing directory are important for proper operation. In order to function correctly, the Apache server must have permission to create files in the same directory as this file, and to delete (overwrite) this file with an updated copy.

See the UsersFile wiki page for more information about its format and required permissions.

OTPAuthMaxOffset

For event based tokens, this is the maximum allowable number of "lost" one-time passwords before the next one-time password will fail to authenticate. The higher this value, the more likely the server will stay synchronized with the token even if you have users who get bored and generate one-time passwords just for fun and then throw them away. On the other hand, the amount of computation the server performs when an incorrect one-time password is used increases linearly with this number (note if the PIN is incorrect, we never get that far, so there's no denial of service attack without knowing at least the PIN).

For time based tokens, this is the maximum number of time intervals that the server will search before and after the current time interval for a matching one-time password. The performance implications are similar as with event based tokens.

The default value for this directive is 4.

See OneTimePasswords for more details about synchronization.

OTPAuthMaxLinger

This defines the maximum "linger time" during which a previously entered one-time password will remain valid. The linger time allows browsing without requiring HTTP authentication on each page, image, etc. load.

The default value for this directive is 600 seconds, i.e., ten minutes. This is probably too low for extensive browsing (forcing your users to enter a password every ten minutes may be annoying).

Note that this is not an idle time. It doesn't matter how active (or inactive) the user is during this time: the timer starts counting from the time the one-time password is first used and then continues to count up toward the limit. Once the linger time expires, the previously used one-time password is no longer accepted.

See OneTimePasswords for more details about why a linger time is required for HTTP authentication.