Add two factor authentication.

[drgrice1]

This uses the TOTP (time-based one-time password) protocol. Any authenticator app on a mobile device that supports this protocol can be used (for example, Google Authenticator, Microsoft Authenticator, Twilio Authy, etc.).

Whether this is enabled or not is controlled by new course environment variable $twoFA{enabled}. If that is set to 0, then two factor authentication is disabled for all courses. If that is 1 (the default), then two factor authentication is enabled for all courses that use password authentication (of course two factor authentication does not apply to courses that use external authentication methods like LTI, CAS, Shibboleth, etc.). If that is a string course name like 'admin', then two factor authentication is enabled only for that course. If that is an array of string course names, then two factor authentication is enabled only for those courses listed. This can also be set in a course's course.conf file. Note that only the values of 0 and 1 make sense there.

There are two methods that can be used to setup two factor authentication when a user signs in for the first time. The setup information can be emailed to the user, or can be directly displayed in the browser on the next page that is shown after password verification succeeds.

This is controlled by the new course environment variable $twoFA{email_sender}. If that is set, then the email approach will be used. In this case, after a user signs in and the password is verified, the user will be sent an email containing a QR code and instructions on how to set up a OTP generator app. This is probably a more secure way to set up two factor authentication, as it ensures the user setting it up is the correct user. Note that if a user does not have an email address, then the browser method below will be used as a fallback.

If $twoFA{email_sender} is not set, then after a user signs in and the password is verified, the QR code, OTP link, and instructions will be displayed directly on the page in the browser. This is potentially less secure because a hacker could guess a username and password before a user has setup two factor authentication (particularly if the username and password are initially the same), and then the hacker would gain access to that user's account, and the actual user would be locked out. Note that you will need to use this option if your server can not send emails. Also note that no-reply addresses may be blocked by the email server or marked as spam. So it may be better to find a valid email address to use for this.

This requires a new database column otp_secret that was added to the password table (for lack of a better place to put it).

There is a new wwsh script (bin/reset2fa) that can be used to reset two factor authentication for a user if a user somehow loses their setup in an authentactor app on their mobile device. That just removes the OTP secret from the database. This means that the user will need to go through the two factor authentication setup process again. To use it execute: wwsh courseID /opt/webwork/webwork2/bin/reset2fa userID. Multiple user ids can be listed if you want to reset more than one user at a time. Note that this script is the only way that an admin user can reset their own two factor authentication (and there should never be another way for admin users to do this for themselves). Perhaps a page in the admin course could be added for resetting this for instructors.

A form has been added to the Accounts Manager for resetting two factor authentication for students. This form does not allow the user to reset their own two factor authentication secret, but that of other users at equal or lesser permission level to their own. Note that in the admin course if there are multiple admin users, then one admin user can reset two factor authentication for another. Also there is some clean up and issue fixes in the htdocs/js/UserList/userlist.js file with form validation. The "change" event handler was being added multiple times to the users list table. More clean up is needed though (with this and the other pages with action forms). There is a lot of redundancy with this form validation implementation.

There is an option to skip two factor authentication on trusted devices. A checkbox is on the two factor verification page. If that is checked, then a signed cookie (separate from the session cookie) is set. If that cookie is set, then two factor verification is skipped for sign in attempts.

This builds on #2333 and #2334, and is the final part of the authentication system revamp.

[drgrice1]

I should point out that the option to skip two factor authentication on trusted devices uses a cookie (not the session cookie, another one) to work. This is the case regardless of what session_management_via is set to. There really is no other way that this can be done.

[drgrice1]

I realized that allowing the render_rpc to disable cookies via a URL parameter is a security vulnerability. So I added a new configuration option in webwork2.mojolicious.dist.yml named allow_unsecured_rpc. If that is set then the render_rpc and html2xml endpoints can disable cookies (html2xml always does if that is set, and render_rpc can by passing the URL parameter disableCookies). This option should always be 0 (disabled) for a typical webwork server. It should only be enabled if you are @Alex-Jordan (or a PreTeXt serving cohort)!

[pstaabp]

Testing this with the new default settings ($twoFA{enabled}=1) and logging on to the admin course, getting

Use of uninitialized value in subroutine entry at template ContentGenerator/TwoFactorAuthentication.html.ep line 10.

and a broken image link for the QR code. It seems that the $img_data variable in TwoFactorAuthentication.pm is not getting defined.

[drgrice1]

Have you installed the new dependencies (Imager::Color, Imager::QRCode, and Mime::Base32)?

[drgrice1]

I am unable to reproduce what you are seeing. It seems that if the dependencies were not installed, then the application would not compile, and you wouldn't even be able to load any page. So that is probably not the issue. You might check versions of the dependencies. Maybe there is some issue with certain versions? On my system I have version 0.033 of Imager::QRCode and 1.013 of Imager::Color (the versions in the Ubuntu packages), and I have version 1.303 of MIME::Base32 (installed from cpan).

[pstaabp]

I'm testing this on a ubuntu development machine. All of the modules have been installed, restarted hypnotoad and the only error I'm seeing in webwork2.log is the message above.

[drgrice1]

I tested this on a production machine (well, really a test server but with a production setup), and I still can't reproduce what you are seeing. That machine also has Ubuntu 22.04 installed, and I used the Ubuntu pacakges libimager-perl, libimager-qrcode-perl, and libmime-base32-perl.

[pstaabp]

I had originally added them via cpanm (my standard on my development machine), but removed and then added the ubuntu packages you mentioned. I see the QR code now.

And successfully logged on.

[drgrice1]

I tried uninstalling the Ubuntu packages for Imager and Imager::QRCode and installing from cpan, and have the same problem. In fact, attempting to use those modules directly from a script also fails. No image is generated. I also tried downgrading Imager::QRCode to the earlier versions. Version 0.035 (the latest) installs but no images are generated. Version 0.034 is the same. Version 0.033 (the same version that is in the Ubuntu package libimager-qrcode-perl) does not install. The build fails. So Ubuntu has something changed in the package to make it work. I haven't tested other versions of Imager as of yet.

This may be something that only affects Ubuntu. We will need testing on other distributions probably.

Have you by chance tested this on OSX with morbo?

[dlglin]

There doesn't appear to be a package for Imager::QRCode in RHEL8.

Do you have a MWE script that I can use to test the package on other distros without a WW installation?

[drgrice1]

Here is a minimal script:

#!/usr/bin/env perl

use strict;
use warnings;

use Imager::QRCode;
use Imager::Color;
use Mojo::File qw(path);

my $img_data;
Imager::QRCode->new(
    size          => 4,
    margin        => 3,
    level         => 'L',
    casesensitive => 1,
    lightcolor    => Imager::Color->new(255, 255, 255, 0),
    darkcolor     => Imager::Color->new(0,   0,   0),
)->plot('blah blah')->write(data => \$img_data, type => 'png');

path('img.png')->spew($img_data);

If it works the file img.png should be written in the directory the script is executed from and contain a valid png image.

[drgrice1]

Note it does use Mojo::File so it also depends on Mojolicious. That was just a quick way to be able to write the file. You could also use:

#!/usr/bin/env perl

use strict;
use warnings;

use Imager::QRCode;
use Imager::Color;

my $img_data;
Imager::QRCode->new(
    size          => 4,
    margin        => 3,
    level         => 'L',
    casesensitive => 1,
    lightcolor    => Imager::Color->new(255, 255, 255, 0),
    darkcolor     => Imager::Color->new(0,   0,   0),
)->plot('blah blah')->write(file => 'img.png', type => 'png');

[drgrice1]

I have strong reason to believe that the Imager::QRCode issue when installed from cpan is an Ubuntu issue. I created a perl 5.26 docker image (which is based on debian 10.4) and ran the minimal script above. It generated the image with no issues. I also testing with a perl 5.34 image (based on debian 11.8), and it also had no problem generating the image.

The basic docker file (which I named testing.Dockerfile) is

FROM perl:5.26
RUN cpanm -fi --notest Imager Imager::QRCode
RUN mkdir -p /home/testing
WORKDIR /home/testing
CMD ["/bin/bash"]

(of course change 5.26 to 5.34 for newer perl and debian). Build the image with docker build -t testing -f testing.Dockerfile .. Run this with docker run -it --rm -v `pwd`:/home/testing testing from the directory containing the above perl script.

[Alex-Jordan]

I'm trying to test on Oracle, running the script above (without Mojo::File) after using cpan to install Imager and Imager::QRCode. I don't get any errors, but I don't get an image file either. I must be doing something basic wrong.

[alex.jordan@vmwebworkdevw02:~ $ ls
 image.pl  my-ping.te  perl5
[alex.jordan@vmwebworkdevw02:~ $ ./image.pl 
[alex.jordan@vmwebworkdevw02:~ $ ls
 image.pl  my-ping.te  perl5

[drgrice1]

Darn. No, you probably aren't doing something wrong. That probably means the issue is not just limited to Ubuntu.

[drgrice1]

This will probably need to be switched to another perl module. I believe that the GD::Barcode::QRcode module will work. I tested this in a docker image of oracle linux version 9, and it worked. Here is a quick test script:

#!/usr/bin/env perl

use strict;
use warnings;

use GD::Image;
use GD::Barcode::QRcode;
use File::Slurp;
my $img = GD::Barcode::QRcode->new('blah blah', { Ecc => 'L', ModuleSize => 4, Version => 9 })->plot->png;
write_file('gd-qrcode.png', $img);

This does need to use Mojo::File (or something else) to write the file. The GD::Barcode::QRcode package does not provide a way to write to a file itself (as far as I can tell).

[drgrice1]

This has now been switched to using the GD::Barcode::QRcode package instead of the Imager::QRCode package. I tested on Ubuntu directly, and in docker images of Oracle linux 9 and Redhat 8, and this package seems to work fine.

[dlglin]

Testing on Fedora 39 the QR code generation works, but I'm running into a couple of issues with the code:

I originally got the attached error. I was able to fix it by adding the options from your test script to line 58 of TwoFactorAuthentication.pm (i.e. Ecc => 'L', ModuleSize => 4, Version => 9).

After that the QR code is still not displaying. It looks like the HTML is treating the base64 encoded image as a URL: <img alt="One-time password generator setup QR Code" class="mx-auto" src="/data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPQAAAD0AQMAAACW4Zm9AAAABlBMVEX///8AAABVwtN+AAAACXBI%0AWXMAAA7EAAAOxAGVKw4bAAACq0lEQVRYhe2YUY4jMQhEuQH3vyU3YF2v3J2MtL/wM+NE6cTPkZAN%0ABTjib/zy0d0VVdGVmecRepSnN/j5rMo+r0PPGmaa6R3eJctk2Fl0gBYm02u8IrVFx8Ds0E6dqU1+%0ANiU1dChYWrHHWSLDjo0hDPpxfpNcNv1n/PDfSa6BX+CZhZucLfoxJvmxA1PyvI5R58EZyWVX+JmM%0Axia5JdIQjYm1wnUW0WWopfbVerZommviHA5rNOcAlVjt8AAoOKVLWseK7l7iZz4Sw0gLFgqEaoWX%0ApVG02auWTEZscVG9kzCRk7b+oY8VXgoEnUaTHfETzT7nM80znY6lCvdkEhe5HjrO5RONRLIKs/Kj%0AzuO8UEaSNOERNrJyh+Ofb0BYGaRV7/lNc0UCZYnrQwkFevHm71nOF8y7AlFJkfDu3zC3JDXH5ChR%0AbZYfhZ7mmER+Vn1GfFCofQR0lKfaA2m0NiaoFIiOJz9P81uPqTpMyjL7aNUrn7PcvRH1iRxFp5Lo%0AVS7xxCXDGqWn9OqrOh3m+GITmcEuPf+oHa6fWeRnzZAnP+q4wRvPQJb0VUHazhYrPKsfZUhkSqvO%0AstrhnuScFJrE522aVjjZoOiK7C7Bso98DnPps0s0lyr8RK5rh18qw3AO6bOmlzhFcXNBE3kvB1JG%0AdqxwUjEBKlm6/tnI5hZPvCNdKig1OEPVCnd7XuB0bqZRffdvmnMp6PxErRB3SdYSV3/qO0p3p26N%0A3vJsmNMNPpdivh1TnNSTn6d5cBdpN/H1HIfzlb+HeYSrEXWGVCVFzfa9YJLf+zm3SLoiKfSqtjiy%0AyDn1Fcq2ZH7dX47ydj8QnEq7Rc5Pfb7CfT2HLNtnq58CbYNLIe/9qFu0Zrt2eLztCW2JvrtXjxVO%0AK+Z6BHWmWeh+5WGa/41fPP4BFfUlsiIeeNwAAAAASUVORK5CYII=%0A">

I still haven't had any luck getting GD::Barcode::QRcode working on RHEL8.

[drgrice1]

I dropped the Ecc option, and decided to use the default value of M (medium level error correction). I dropped the Version option because the GD::Barcode::QRcode package by default auto selects what is needed, and if I add Version => 9 I got the error that you are showing with the message Overflow error. version 9 total bits: 1516 max bits: 1456. I also tested all versions from 1 - 9, and got similar errors (for version 1 I get the exact error you get). So it seems that the auto selection of the version is not working right for Fedora. Here is a test script for you with an actual otpauth link as will be used for webwork2:

#!/usr/bin/env perl

use strict;
use warnings;

use GD::Image;
use GD::Barcode::QRcode;
use Mojo::File qw(path);

my $img = GD::Barcode::QRcode->new('otpauth://totp/grice1?secret=MNJSSVTKKYTHOJCROIQXMWK6PEQTO3RSJJUEQ4TIKQSV4RLQONGVAJSRMFRXAUJPFB3W2NRSFIQVQ4RPFIRXCJDIERAWQILJL5UXS4I&algorithm=SHA512&digits=6&period=30&issuer=myTestCourse', { ModuleSize => 4, Version => 12 })->plot->png;
path('gd-qrcode.png')->spew($img);

I found that higher versions work (I tested 10 - 20). A version of 20 gives a huge image. So I think I will set it to 12. I am concerned that for some otpauth links 10 might not be enough and give the same error, so I am choosing 12 to hopefully make sure that doesn't happen, and keeping it small enough to not make the image huge. Although I believe that omitting the option is the right thing to do. It should select the minimal version needed to correctly render the QR code for the link. Note that with "blah blah" a version of 9 is more than sufficient.

I tested in a docker image of Redhat 8 and it worked fine, and the same as above. A Version of 9 or less fails, not setting the Version or setting it to 10 or higher works. I used the perl that was in the distribution which is version 5.26. Maybe this is something with the perl version you are using in Redhat (although presumably you are using a newer version which should work fine)?

I tested in a docker image of Oracle Linux 9 and everything worked the same there as well. A Version of 9 or less fails, not setting the Version or setting it to 10 or higher works. (The version of perl for Oracle 9 is 5.32.)

I have now also tested in a docker image of Fedora 39, and everything works the same as my testing above also. Not setting the Version works. Setting it to 9 fails. Setting it to 10 or higher works. So something is not right with your setup. (Note that the version of perl is 5.38 for Fedora 39.)

The image is added to the HTML as a base64 encoded image data url. That is how it is intended to be, and should work fine. I don't know why your browser wouldn't work with that. Data url's are supported by all browsers, and have been for a long time. There is something odd in what you posted though. You showed src="/data:image/png;base64,.... It should be src="data:image/png;base64,... (no forward slash before data:image). I am using the latest version of Mojolicious from cpan (version 9.36). Are you using an earlier version that might be adding that forward slash?

[drgrice1]

@dlglin: I just noticed there is a perl-GD-Barcode package for Fedora (and RHEL 8). I tested with that package in a docker image, and found that if the Version is not set, then it fails to generate an image. However, if the Version is set to 9 it also fails. Using 10 or more works though. That is of course testing with the actual otpauth link and not "blah blah". So the package is not as good as using the cpan module in my testing, but might work better for you?

[pstaabp]

Successfully worked on ubuntu (2022 LTS). I used the package libgd-barcode-perl.

[dlglin]

I don't like having this enabled globally by default. This could be a nightmare to manage for large classes.

I'd also like to see the option to enable this based on roles. I could see asking instructors to use 2FA but letting students not.

Does the user need a separate 2FA instance for each course? That could get really cumbersome for a system administrator, but it doesn't look like there's any way around it with our current structure.

[drgrice1]

It would be easy to make this disabled by default. Although it is also quite simple for a system administrator to do so if they don't want to use it. I think it is best to leave it enabled by default.

There really is no point of enabling two factor authentication based on roles. A secure system doesn't allow for such things.

Yes, a user needs a separate 2FA instance for each course, and there really is no way around that with webwork2's structure. The reality of things is that the user has separate user instances for each course even if you give that user the same username in each course.

[drgrice1]

There is now a new permission level called use_two_factor_auth. Roles with this permission level are required to use two factor authentication to sign in. Users below this permission level can sign in directly. The default user role with this permission is "student". But if there is strong opposition to this default, then I suppose it could be switched to "login_proctor".

Note that even if this is set to "guest", guest users will still be able to sign in without two factor authentication since it never really makes sense to have guests (i.e. practice users) use two factor authentication.

[Alex-Jordan]

Trying this out and it's not letting me in. But the way this all works, should I expect it to fail if the WW server is behind a firewall? I'm trying it on a school test server where access is only through the school's VPN.

[drgrice1]

It should work fine behind a firewall. What do you mean that it is not letting you in? Do you have any idea of what is going wrong?

[drgrice1]

What authenticator app are you trying to use?

[Alex-Jordan]

It's Microsoft Authenticator. I get:

[Alex-Jordan]

Maybe worth mentioning, the first time I tried this last night, I fumbled so much with my phone that the first code expired. I tried with the next several codes it gave me. And tried a few times after completely reloading the page like just now this morning. Same results.

[drgrice1]

So it seems that it is the Microsoft Authenticator that is not working with this. It worked before when I tested it, but it isn't now. So I must have changed something from how it was set up at that time. I will look at it.

It is working with Google Authenticator still.

[drgrice1]

I see. So I switched to using the SHA512 algorithm for computing the HMAC SHA. Apparently Microsoft Authenticator only supports the SHA1 algorithm. So this is switched back to using that algorithm. So now it should work for you.

[drgrice1]

I figured I better actually test Twilio Authy as well, since I list that as an app that will work. Fortunately it does!

[Alex-Jordan]

I updated the branch, and had getting the same result with Invalid security code. But then I deleted that item from the authenticator app and tried again from the beginning, and I got in.

[Alex-Jordan]

An observation: If I check the box to skip 2FA and enter the course, then log out and log in again, it works as expected. However if I attempt to log in to the course as a different user, then attempt to log in as the original user, it has forgotten me. I'm not sure this is something to "fix" because people don't usually log in as multiple users. And maybe it's safer this way in case someone clicks to skip 2FA on a public machine.

[drgrice1]

I updated the branch, and had getting the same result with Invalid security code. But then I deleted that item from the authenticator app and tried again from the beginning, and I got in.

You would need to do that if you setup the authenticator app with the SHA512 setting. That is one of the parameters passed to the app in setup.

[Alex-Jordan]

I worked some tweaking QR code generation for PTX, and based on that experience I changed { ModuleSize => 4, Version => 12 } to { Ecc => 'L', ModuleSize => 4 } and at least for me, I still get a functional QR code but overall it's smaller and with much less granularity.

[drgrice1]

Unfortunately, the Version => 12 argument is necessary. See my comment https://github.com/openwebwork/webwork2/pull/2335#issuecomment-1993332752.

We could switch to Ecc => 'L'. That is in fact what I had it at initially.

[Alex-Jordan]

In my testing, declaring the version as 12 and using Ecc => 'L' had no effect.

[drgrice1]

Yeah, then maybe Ecc => 'L' won't work. The issue is specific to the perl-GD-Barcode package for Fedora 39 and Redhat 8 as my comment noted.

[drgrice1]

I tested it again with Fedora 39. If the settings are { ModuleSize => 4, Ecc => 'L' }, then the QR code fails to generate and the exception Overflow error. version 1 total bits: 1516 max bits: 152 is thrown.

I didn't actually test with Redhat 8 before, but did now. The perl-GD-Barcode package is not available for Redhat 8. So those using Redhat 8 will need to install from cpan.

In my testing with both Redhat 8 and Fedora 39, if the GD::Barcode::QRcode package (which is really part of the GD::Barcode package) is installed from cpan, it works fine with those options. As I mentioned before, I believe that the correct thing to do is NOT include Version option. So if we just insist that Fedora 39 systems also install from cpan then we can switch to { ModuleSize => 4, Ecc => 'L' }.

[drgrice1]

@dlglin: When you tested this, did you install from cpan or did you use the perl-GD-Barcode package?

If I am not mistaken, @dlglin installed from cpan, but still had this issue when the Version option was not given. Can you do some more testing @dlglin?

[Alex-Jordan]

For me on Oracle, all was installed from cpan.

[drgrice1]

An observation: If I check the box to skip 2FA and enter the course, then log out and log in again, it works as expected. However if I attempt to log in to the course as a different user, then attempt to log in as the original user, it has forgotten me. I'm not sure this is something to "fix" because people don't usually log in as multiple users. And maybe it's safer this way in case someone clicks to skip 2FA on a public machine.

I think this needs some work. What you are describing is probably correct, but not in the way that is actually works behind the scenes. Consider the following examples.

First example: Log in as one user, setup a two factor authentication app, check the remember check box, submit the code, and then log out. Then log in as another user, DON'T check the remember check box, submit the code, and log out. Now both users MUST enter their code.

Log in as one user, setup a two factor authentication app, check the remember check box, submit the code, and then log out. Then log in as another user, check the remember check box, submit the code, and log out. Now both users can sign in without needing to enter their code.

The first is probably okay. The second may seem natural, but is not okay at all in the way it is implemented. What is happening in both cases is that a (non-session) cookie is created when the first user successfully signs all the way in after checking the remember me check box. Then when the second user signs in that cookie is destroyed as soon as the second user's username and password are verified. But then when the second user also checks the remember me check box, another cookie is created. That cookie has no user identifying properties (the mistake in my implementation). So it works for both users.

So the cookie needs to identify the user. That is easy enough, and I will add that. Note that the first case will still occur, but once there is user identifying information in the cookie, it could be changed. However, it will still only be possible to remember one user in a browser per course.

[Alex-Jordan]

Oh wait, I failed to notice that while { Ecc => 'L', ModuleSize => 4 } makes a fine QR image, there are perl warnings:

    Use of uninitialized value in left bitshift (<<) at /usr/local/share/perl5/GD/Barcode/QRcode.pm line 124.
    Use of uninitialized value within @aMask in bitwise xor (^) at /usr/local/share/perl5/GD/Barcode/QRcode.pm line 217.
    Use of uninitialized value within @aMatrixX in array element at /usr/local/share/perl5/GD/Barcode/QRcode.pm line 217.
    Use of uninitialized value within @aMatrixY in array element at /usr/local/share/perl5/GD/Barcode/QRcode.pm line 217.

[drgrice1]

Interesting. I haven't see those perl warnings in any of my testing.

[drgrice1]

The two factor authentication cookie is now user specific.

So if one user logs in, sets up a two factor authentication app, checks the remember check box, submits the code, and then logs out. Then another user logs in, and doesn't check the remember check box, submits the code, and logs out. Now the first user can still sign in without two factor authentication, but the second user will need to use two factor authentication.

If one user logs in, sets up a two factor authentication app, checks the remember check box, submits the code, and then logs out. Then another user logs in, and does check the remember check box, submits the code, and logs out. Now the first user will need to enter the two factor authentication code again, but the second user will not need to do so.

In thinking about this more, I believe this is the correct behavior. Only one user can be remembered for a given course in a given browser. I don't think it is the right thing to do for the second user's sign in to remove first user's remember me cookie unless the second user also uses remember me (which will replace the first). I am thinking of the case of an instructor having a student sign in in their office to see something in a problem. In that case, you wouldn't want the student's sign in to remove the instructors remember me cookie. If a user checks the remember me box on a public workstation, and shouldn't have, unfortunately, there is not much that can be done about that.

[drgrice1]

@Alex-Jordan: What version of Oracle Linux are you using?

[Alex-Jordan]

The server I'm testing on is using Oracle 8.7.

[drgrice1]

Odd. I tested in a docker image with Oracle Linux 8.7, and didn't get any warnings or errors and the image generates fine. Testing in a docker image is perhaps not the same.

This is frustrating how hard it is to find a perl package that can generate a nice QR code without errors or warnings!

[somiaj]

This is frustrating how hard it is to find a perl package that can generate a nice QR code without errors or warnings!

Does it have to be perl? What about a command line utility like qrencode. Debian (and probably ubuntu) have packages for this, unsure about other distros. I haven't tested any of this, but just a suggestion if finding a pure perl utility isn't working.