Lots more to document here.

Fix things for `$session_management_via = "key"`.

Fix using Saml2 in conjunction with two factor authentication.

Remove the Saml2 plugin.  Unfortunately, that approach is too limited.

conf/authen_saml2.conf.dist

@@ -0,0 +1,121 @@
+#!perl
+################################################################################
+# Configuration for using Saml2 authentication.
+# To enable this Saml2 authentication, copy this file to conf/authen_saml2.conf
+# and uncomment the appropriate lines in localOverrides.conf. The Saml2
+# authentication module uses the Net::SAML2 library. The library claims to be
+# compatible with a wide range of SAML2 implementations, including Shibboleth.
+################################################################################
+
+# Set Saml2 as the authentication module to use.
+# Comment out 'WeBWorK::Authen::Basic_TheLastOption' if bypassing Saml2
+# authentication is not allowed (see $saml2{bypass_query} below).
+$authen{user_module} = [
+	'WeBWorK::Authen::Saml2',
+	'WeBWorK::Authen::Basic_TheLastOption'
+];
+
+# List of authentication modules that may be used to enter the admin course.
+# This is used instead of $authen{user_module} when logging into the admin
+# course. Since the admin course provides overall power to add/delete courses,
+# access to this course should be protected by the best possible authentication
+# you have available to you.
+$authen{admin_module} = [
+	'WeBWorK::Authen::Saml2'
+];
+
+# Note that Saml2 authentication can be used in conjunction with webwork's two
+# factor authentication. If the identity provider does not provide two factor
+# authentication, then it is recommended that you DO use webwork's two factor
+# authentication. If the identity provider does provide two factor
+# authentication, then you would not want your users need to perform two factor
+# authentication twice, so you should disable webwork's two factor
+# authentication. The two factor authentication settings are set in
+# localOverrides.conf.
+
+# This URL query parameter can be added to the end of a course url to skip the
+# saml2 authentication module and go to the next one, for example,
+# http://your.school.edu/webwork2/courseID?bypassSaml2=1. Comment out the next
+# line to disable this feature.
+$saml2{bypass_query} = 'bypassSaml2';
+
+# If $external_auth is 1, and the authentication sequence reaches
+# Basic_TheLastOption, then the webwork login screen will show a message
+# directing the user to use the external authentication system to login. This
+# prevents users from attempting to login in to WeBWorK directly.
+$external_auth = 0;
+
+# The $saml2{idps} hash contains names of identity proviers and their SAML2
+# metadata URLs that are used by this server.  Webwork will request the identity
+# provider's metadata from the URL of the $saml2{active_idp} during the
+# authentication process. Additional identity providers can also be added for a
+# particular course by adding, for example, $saml2{idps}{other_idp} = '...' to
+# the course.conf file of the course. Note that the names of the identity
+# providers in this hash are used for a directory name in which the metadata and
+# certificate for the identity provider are saved. So the names should only
+# contain alpha numeric characters and underscores.
+$saml2{idps} = {
+	default => 'http://idp/simplesaml/module.php/saml/idp/metadata',
+	# Add additional identity providers used by this server below.
+	#other_idp => 'http://other.idp.server/metadata',
+};
+
+# The $saml2{active_idp} is the identity provider in the $saml2{idps} hash that
+# will be used. If different identity providers are used for different courses,
+# then set $saml2{active_idp} = 'other_idp' in the course.conf file of each
+# course.
+$saml2{active_idp} = 'default';
+
+# This the id for the webwork2 service provider. This is usually the application
+# root URL plus the base path to the service provider.
+$saml2{sp}{entity_id} = 'http://localhost:8080/webwork2/saml2';
+
+# This is the organization metadata information for the webwork2 service
+# provider. The Saml2 authentication module will generate xml metadata that can
+# be obtained by the identity provider for configuration from the URL
+# https://webwork.yourschool.edu/webwork2/saml2/metadata if Saml2 authentication
+# is enabled site wide. The URL needs to have the courseID URL parameter added
+# if Saml2 authentication is not enabled site wide, but is enabled for some
+# courses in those course's course.conf files. So for example if one course is
+# myTestCourse, then the metadata URL would be
+# https://webwork.yourschool.edu/webwork2/saml2/metadata?courseID=myTestCourse
+# Further note that if multiple courses use that same identity provider then
+# just pick any one of the courses to use in the metadata URL. All of the other
+# courses share the same metedata.
+$saml2{sp}{org} = {
+	contact      => '[email protected]',
+	name         => 'webwork',
+	url          => 'https://localhost:8080/',
+	display_name => 'WeBWorK'
+};
+
+# The following list of attributes will be checked in the given order for a
+# matching user in the webwork2 course. If no attributes are given, then
+# webwork2 will default to the NameID. It is recommended that you use the
+# attribute's OID.
+$saml2{sp}{attributes} = [
+	'urn:oid:0.9.2342.19200300.100.1.1'
+];
+
+# The following settings are the locations of the files that contain the
+# certificate and private key for the webwork2 service provider. A certificate
+# and private key can be generated using openssl. For example,
+#   openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem
+# The files saml.crt and saml.pem that are generated contain the public
+# "certificate" and the "private_key", respectively.
+# Note that if the files are placed within the root webwork2 app directory, then
+# the paths may be given relative to the the root webwork2 app directory.
+# Otherwise the absolute path must be given. Make sure that the webwork2 app has
+# read permissions for those files.
+$saml2{sp}{certificate_file} = 'docker-config/idp/certs/saml.crt';
+$saml2{sp}{private_key_file} = 'docker-config/idp/certs/saml.pem';
+
+##############################################################################
+# SECURITY WARNING
+# For production, you MUST provide your own unique 'certificate' and
+# 'private_key' files. The files referred to in the default settings above are
+# only intended to be used in development, and are publicly exposed. Hence, they
+# provide NO SECURITY.
+##############################################################################
+
+1;

conf/localOverrides.conf.dist

@@ -527,6 +527,16 @@ $mail{feedbackRecipients}    = [
 
 #include("conf/authen_ldap.conf");
 
+################################################################################
+# Saml2 Authentication
+################################################################################
+# Uncomment the following line to enable authentication via a Saml2 identity
+# provider.  You will also need to copy the file authen_saml2.conf.dist to
+# authen_saml2.conf, and then edit that file to fill in the settings for your
+# installation.
+
+#include("conf/authen_saml2.conf");
+
 ################################################################################
 # Session Management
 ################################################################################

docker-config/docker-compose.dist.yml

@@ -251,47 +251,27 @@ services:
     #ports:
     #  - "6311:6311"
 
-  # saml2 dev use only, separate profile from the other services so it doesn't
-  # start in normal usage. Use "docker compose --profile saml2dev up" to start.
+  # SimpleSAMLphp Saml2 identity provider for development use only. This is a separate profile from the other services
+  # so it doesn't start in normal usage. Use "docker compose --profile saml2dev up" to start, and "docker compose
+  # --profile saml2dev down" to stop.
   idp:
     build:
-      context: ./docker-config/idp/ # SimpleSAMLphp based IDP
+      context: ./docker-config/idp/
     profiles:
       - saml2dev
     ports:
       - '8180:80'
     environment:
-      SP_METADATA_URL: 'http://app.docker:8080/saml2/metadata'
-    # the healthcheck url is simplesamlphp's url for triggering cron jobs, the
-    # cron job it'll trigger is to automatically grab webwork sp's metadata
+      SP_METADATA_URL: 'http://app:8080/webwork2/saml2/metadata'
+    # The healthcheck url is SimpleSAMLphp's url for triggering cron jobs. The cron job it triggers will
+    # automatically fetch the webwork2 service provider's metadata.
     healthcheck:
-      test: ['CMD', 'curl', '-f', 'http://localhost/simplesaml/module.php/cron/run/docker/healthcheck']
+      test: ['CMD', 'curl', '-f', 'http://localhost/simplesaml/module.php/cron/run/metarefresh/webwork2']
       start_period: 1m
       start_interval: 15s
       interval: 1h
       retries: 1
       timeout: 10s
-  # Send internal docker traffic for the idp external port to the idp internal
-  # port. Needed so the webwork saml2 plugin can request the idp metadata.
-  socat-idp:
-    image: alpine/socat:1.8.0.0
-    profiles:
-      - saml2dev
-    command: 'TCP-LISTEN:8180,fork,reuseaddr TCP:idp:80'
-    networks:
-      default:
-        aliases:
-          - idp.docker
-  # same port redirect so the idp can get the webwork saml2 plugin metadata
-  socat-app:
-    image: alpine/socat:1.8.0.0
-    profiles:
-      - saml2dev
-    command: 'TCP-LISTEN:8080,fork,reuseaddr TCP:app:8080'
-    networks:
-      default:
-        aliases:
-          - app.docker
 
 volumes:
   oplVolume:

docker-config/idp/Dockerfile

@@ -1,36 +1,38 @@
-# actual image we'll run in the end
 FROM php:8.3-apache
 WORKDIR /var/www
 
-# Install composer & php extension installer
+# Install composer and the php extension installer.
 COPY --from=composer/composer:2-bin /composer /usr/bin/composer
 COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/
 
 RUN apt-get update && \
 	apt-get -y install git curl vim && \
 	install-php-extensions ldap zip
 
-# dirs used by simplesamlphp needs to be accessible by apache user
+# Directories used by simplesamlphp.  These need to be accessible by the apache2 user.
 RUN mkdir simplesamlphp/ /var/cache/simplesamlphp
-RUN chown www-data. simplesamlphp/ /var/cache/simplesamlphp
-# Composer doesn't like to be root, so we'll run the rest as the apache user
+RUN chown www-data simplesamlphp/ /var/cache/simplesamlphp
+
+COPY ./idp.apache2.conf /etc/apache2/conf-available
+RUN a2enconf idp.apache2
+
+# Composer doesn't like to be root, so run the rest as the apache user.
 USER www-data
 
 # Install simplesamlphp
-ARG SIMPLESAMLPHP_TAG=v2.2.1
-RUN git clone --branch $SIMPLESAMLPHP_TAG https://github.com/simplesamlphp/simplesamlphp.git
+RUN git clone --branch v2.2.1 https://github.com/simplesamlphp/simplesamlphp.git
 WORKDIR /var/www/simplesamlphp
 
-# Generate certs
+# Generate the server certificates.
 RUN cd cert/ && \
-	openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out server.crt -keyout server.pem -subj "/C=CA/SP=BC/L=Vancouver/O=UBC/CN=idp.docker"
+	openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out server.crt -keyout server.pem \
+		-subj "/C=US/S=New York/L=Rochester/O=WeBWorK/CN=idp.webwork2"
 
-# Use composer to install dependencies
+# Use composer to install dependencies.
 RUN composer install && \
 	composer require simplesamlphp/simplesamlphp-module-metarefresh
 
-# Copy config files
+# Copy configuration files.
 COPY ./config/ config/
 COPY ./metadata/ metadata/
 
-COPY ./apache.conf /etc/apache2/sites-available/000-default.conf