Overview

mod_authnz_fido2 is a module for Apache 2.4 that allows authorization of simple websites by FIDO2 / WebAuthn protocol, without using an standalone WebAuthn server process. Registered users are simply maintained in a text file. No modification of the web pages is needed, i.e. no special JavaScript needs to be added for authentication.

Caveat emptor: This all is still not finished and work in progress! Please don't use for productive applications at the moment, as some security mechanisms are not in place yet.

The basic outline of how it works is: If a user first requests a page with "fido2" authentication type, the server delivers some JavaScript code instead to trigger the WebAuthn authentication process. If that is successful, a cookie is set in the user's browser to store a JWT ticket that grants access without further authentication for some time.

Building

Build with:

autoreconf -is && ./configure && make

You generally need the following packages:

sudo apt install apache2-dev libapr1-dev libssl-dev libjwt-dev libfido2-dev

Configuration

mod_authnz_fido2 is usually installed like any other Apache module to /usr/lib/apache2/modules. You can let "make install" add a LoadModule statement to your httpd.conf, or you can create a /etc/apache2/mods-enabled/authnz_fido2.load file and use Debian's a2enmod mechanism:

LoadModule authnz_fido2_module /usr/lib/apache2/modules/mod_authnz_fido2.so

To use FIDO2 authentication for some Directory or Location, set the AuthType to "fido2" as usual:

	<Directory /fidotest>
		AuthType fido2
		AuthName "My Private Area"
		AuthFIDO2RelyingPartyID "example.com"
		AuthFIDO2UserFile "/etc/apache2/fido2users"
		Require valid-user
	</Directory>

The complete list of configuration variables is:

• AuthFIDO2UserFile

  The name of the file with user data. Also see below under User Registration.

• AuthFIDO2RelyingPartyID

  This is the "Relying Party ID" in the WebAuthn meaning. The default is the web server's hostname and correct in many cases, but can be overridden by an arbitrary string here.

• AuthFIDO2CookieName

  The name (a string) of the cookie that is set by mod_authnz_fido2 containing the ticket. The default is modfido2session.

• AuthFIDO2RequireUserVerification

  If set to true / on / 1 ... sets the "user verification required" flag during authentication process. This usually triggers some additional verification on client side, like e.g. requesting a fingerprint or the like.

• AuthFIDO2Timeout

  The timeout (in seconds) to be passed to the client for authentication. Default is 30s.

• AuthFIDO2TokenValidity

  The time (in minutes) how long a token should be valid. Default is 1 hour (= 60 minutes).

• AuthFIDO2TokenKeyLifetime

  The time (in minutes) how long a key for signing tokens remains valid. After that time, a new key is generated, but the old one is still accepted for the same time (rotation with depth 2). In other words: Tokens remain valid for at least TokenKeyLifetime and maximum twice this lifetime.

  Default is 12 hours (= 720 minutes).

• AuthFIDO2OfferAllUsers

  This flag can be used to work around some problems I've seen with Firefox and username-less authentication, i.e. when only an RP-ID is passed to the client, but no :allowed credential IDs". My Firefox 72.0 then reports an error "object invalid state" (XXX), whereas Chromium 79.0 seems to handle this gracefully.

  The workaround is passing all known credential IDs from the users file to the client as allowed. So this should be used with care if there are more than a few dozen users or so. The user name is still derived correctly, BTW.

User Registration

Instead of employing a separate server process and an often oversized database, mod_authnz_fido2 keeps its user info in a simple file, a bit like /etc/passwd. The downside is that new user registration cannot be done by a web page but is handled "offline". This is appropriate for small sites with a small, not very dynamic set of users.

The users file consists of lines with 5 fields, separated by colons:

USERNAME:CREDID:KEYTYPE:PUBKEY:COUNTER

• USERNAME

  This is simply a string that is written into the JWT ticket, and that can be matched by standard Apache configuration statements ("Require user roman").

• CREDID

  The WebAuthn "credential ID" which is generated by the authenticator device together with the key pair.

• KEYTYPE

  The type of public key in the next field. Currently supported are "es256" (ECDSA NIST P-256 key with SHA256), "rs256" (RSASSA-PKCS1-v1_5 with SHA256), and "eddsa" (EdDSA with edwards25519 curve).

• PUBKEY

  Base64-encoded COSE representation of the public key, like usually used with WebAuthn.

• COUNTER

  This field is current not yet used by mod_authnz_fido2. It is used to detect clones of authenticator devices. At the moment, there's always a 0 there.

In most cases, you will not manually construct such a line. Instead you can use the tool fido2-useradd provided together with mod_authnz_fido2. For example:

	$ fido2-useradd roman
	Enter PIN for /dev/hidraw3: ******
	# (Authenticator blinks -> press button)
	roman:ORkYp3d/RZ1zIqsHkQjOQQL5e6pLaoTCwLOWjlW5j7eNh94KCRP39fKHKGfeedYwYavh+QJU81i0SQbSfCiI5g==a:es256:MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEHvy6F0pkaAsTzH4ReFp+LuaQ5UN3DyfGa9g5hKhJeFk+hOPIrfJQpqOkfR2bpTRJPKsG8l5FxTVlFOGlgn60+Q==:0

Indeed, this is not very readable, but you usually don't have to recognize more than the user name at the beginning for maintenance, e.g. for deleting a line. (Yes, or maybe match the credential ID against a known one.)

You will most probably run fido2-useradd on you personal machine where your authenticator device is attached. You can then paste over the line printed to an editor on your web server to add it to the users file. Or you also could pipe it via ssh, e.g.:

fido2-useradd newuser | ssh myserver 'cat >> /etc/apache2/fido2users'

The fido2-useradd tool defaults to "es256" keys, but also can create "rs256" and "eddsa" which can be selected with the -k option. It also allows to use a different device than the first one found with -d (f.i., use fido2-token -L from fido2-tools package to print available names). Support for resident keys will be implemented soon.