update docs for changes made during SSP 2 upgrade

README.md

@@ -1,5 +1,6 @@
-# ssp-base 
-Base image for simpleSAMLphp
+# ssp-base
+
+Base image for SimpleSAMLphp IdP and Hub with custom modules
 
 Docker image: [silintl/ssp-base](https://hub.docker.com/r/silintl/ssp-base/)
 
@@ -9,8 +10,6 @@ must be installed.
 
 [Make](https://www.gnu.org/software/make) is optional but simplifies the build process.
 
-[PHP](https://www.php.net) and [Composer](https://getcomposer.org) are optional, but at a minimum you need COMPOSER_CACHE_DIR set to a local directory for storing the PHP dependency cache. This must be exported in your local development environment, not in the Docker container environment. For example, in your `~/.bashrc`, include `export COMPOSER_CACHE_DIR="$HOME/.composer"` and create an empty directory at `~/.composer`.
-
 ## Configuration
 By default, configuration is read from environment variables. These are documented
 in the `local.env.dist` file. Optionally, you can define configuration in AWS AppConfig.
@@ -35,10 +34,10 @@ will overwrite variables set in the execution environment.
 
 1. `cp local.env.dist local.env` within project root and make adjustments as needed.
 2. `cp local.broker.env.dist local.broker.env` within project root and make adjustments as needed.
-3. Add your github token to the `COMPOSER_AUTH` variable in the `local.env` file.
+3. Add your GitHub [personal access token](https://github.com/settings/tokens?type=beta) to the `COMPOSER_AUTH` variable in the `local.env` file.
 4. Create `localhost` aliases for `ssp-hub.local`, `ssp-idp1.local`, `ssp-idp2.local`, `ssp-idp3.local`, `ssp-sp1.local`, `ssp-sp2.local`, and `ssp-sp3.local`. This is typically done in `/etc/hosts`.  _Example line:  `127.0.0.1  ssp-hub.local ssp-idp1.local ssp-idp2.local ssp-idp3.local ssp-sp1.local ssp-sp2.local ssp-sp3.local`_
-4. `make` or `docker compose up -d` within the project root.
-5. Visit http://ssp-hub.local to see SimpleSAMLphp 
+5. Run `make test` within the project root.
+6. Visit http://ssp-hub.local to see SimpleSAMLphp
 
 _Note:_ there is an unresolved problem that requires a change to BASE_URL_PATH for ssp-idp1.local in docker-compose.yml due to a requirement in silauth that it be a full URL. For automated testing, it must not have a port number, but for manual testing it needs the port number.
 
@@ -93,7 +92,7 @@ docker composer up -d ssp-hub.local
  - Port: 80
  - Debugger: Xdebug
  - Check use path mappings and add map from project root to `/data`
- 
+
 13. Hit `Apply` and `OK`
 14. Click on `Run` and then `Debug 'Debug on Docker'`
 
@@ -168,7 +167,7 @@ Example (in `metadata/saml20-idp-hosted.php`):
             'dateFormat' => 'm.d.Y', // Use PHP's date syntax.
             'loggerClass' => '\\Sil\\Psr3Adapters\\Psr3SamlLogger',
         ],
-        
+
         // ...
     ],
 
@@ -181,12 +180,18 @@ the user's expiry date, which must be formated as YYYYMMDDHHMMSSZ (e.g.
 `20111011235959Z`). Those two attributes need to be part of the attribute set
 returned when the user successfully authenticates.
 
+The `passwordChangeUrl` parameter contains the URL of the password manager. A
+link to that URL may be presented to the user as a convenience for updating
+their password.
+
 The `warnDaysBefore` parameter should be an integer representing how many days
 before the expiry date the "about to expire" warning will be shown to the user.
 
 The `dateFormat` parameter specifies how you want the date to be formatted,
 using PHP `date()` syntax. See <http://php.net/manual/en/function.date.php>.
 
+The `originalUrlParam` parameter is not used.
+
 The `loggerClass` parameter specifies the name of a PSR-3 compatible class that
 can be autoloaded, to use as the logger within ExpiryDate.
 
@@ -200,46 +205,31 @@ they did on those two modules.
 
 Material Design theme for use with SimpleSAMLphp
 
-#### Installation
-
-```
-composer.phar require silinternational/simplesamlphp-module-material:dev-master
-```
-
 #### Configuration
 
-Update `/simplesamlphp/config/config.php`:
-
-```
-'theme.use' => 'material:material'
-```
-
-This project sets this as the default value in the provided config file.
+No configuration is necessary. The `theme.use` config option is pre-configured to `material:material`.
+Optional configuration is described below.
 
 ##### Google reCAPTCHA
 
-If a site key has been provided in `$this->data['recaptcha.siteKey']`, the
+If a site key has been provided in the `RECAPTCHA_SITE_KEY` environment variable, the
 username/password page may require the user prove his/her humanity.
 
 ##### Branding
 
-Update `/simplesamlphp/config/config.php`:
+Set the `THEME_COLOR_SCHEME` environment variable using one of the following values:
 
 ```
-'theme.color-scheme' => ['indigo-purple'|'blue_grey-teal'|'red-teal'|'orange-light_blue'|'brown-orange'|'teal-blue']
+'indigo-purple', 'blue_grey-teal', 'red-teal', 'orange-light_blue', 'brown-orange', 'teal-blue'
 ```
 
+The default is `indigo-purple`.
+
 The login page looks for `/simplesamlphp/public/logo.png` which is **NOT** provided by default.
 
 ##### Analytics
 
-Update `/simplesamlphp/config/config.php`:
-
-```
-'analytics.trackingId' => 'UA-some-unique-id-for-your-site'
-```
-
-This project provides a convenience by loading this config with whatever is in the environment variable `ANALYTICS_ID`._
+Set the `ANALYTICS_ID` environment variable to contain your Google Analytics 4 tag ID.
 
 ##### Announcements
 
@@ -259,11 +249,12 @@ If provided, an alert will be shown to the user filled with the content of that
 
 #### i18n support
 
-Translations are categorized by page in definition files located in the `dictionaries` directory.
+Translations are categorized by page in definition files located in the `modules/material/locales` directory.
 
-Localization is affected by the configuration setting `language.available`. Only language codes found in this property will be utilized.  
-For example, if a translation is provided in Afrikaans for this module, the configuration must be adjusted to make 'af' an available
-language. If that's not done, the translation function will not utilize the translations even if provided.
+Localization is affected by the configuration setting `language.available`. Only language codes found in this property
+will be utilized. For example, if a translation is provided in Afrikaans for this module, the configuration must be
+adjusted to make 'af' an available language. If that's not done, the translation function will not utilize the
+translations even if provided.
 
 ### Multi-Factor Authentication (MFA) simpleSAMLphp Module
 A simpleSAMLphp module for prompting the user for MFA credentials (such as a
@@ -285,9 +276,9 @@ Example (for `metadata/saml20-idp-hosted.php`):
 
     use Sil\PhpEnv\Env;
     use Sil\Psr3Adapters\Psr3SamlLogger;
-    
+
     // ...
-    
+
     'authproc' => [
         10 => [
             // Required:
@@ -303,7 +294,7 @@ Example (for `metadata/saml20-idp-hosted.php`):
             // Optional:
             'loggerClass' => Psr3SamlLogger::class,
         ],
-        
+
         // ...
     ],
 
@@ -312,7 +303,7 @@ the user's Employee ID stored in it. In certain situations, this may be
 displayed to the user, as well as being used in log messages.
 
 The `loggerClass` parameter specifies the name of a PSR-3 compatible class that
-can be autoloaded, to use as the logger within ExpiryDate.
+can be autoloaded, to use as the logger within the module.
 
 The `mfaSetupUrl` parameter is for the URL of where to send the user if they
 want/need to set up MFA.
@@ -327,12 +318,12 @@ Based on...
   implemented as AuthProcs,
 - implementing my solution as an AuthProc and having a number of tests that all
   confirm that it is working as desired, and
-- a discussion in the SimpleSAMLphp mailing list about this:  
+- a discussion in the SimpleSAMLphp mailing list about this:
   https://groups.google.com/d/msg/simplesamlphp/ocQols0NCZ8/RL_WAcryBwAJ
 
 ... it seems sufficiently safe to implement MFA using a simpleSAMLphp AuthProc.
 
-For more of the details, please see this Stack Overflow Q&A:  
+For more of the details, please see this Stack Overflow Q&A:
 https://stackoverflow.com/q/46566014/3813891
 
 #### Acknowledgements
@@ -361,9 +352,9 @@ Example (for `metadata/saml20-idp-hosted.php`):
 
     use Sil\PhpEnv\Env;
     use Sil\Psr3Adapters\Psr3SamlLogger;
-    
+
     // ...
-    
+
     'authproc' => [
         10 => [
             // Required:
@@ -375,7 +366,7 @@ Example (for `metadata/saml20-idp-hosted.php`):
             // Optional:
             'loggerClass' => Psr3SamlLogger::class,
         ],
-        
+
         // ...
     ],
 
@@ -397,8 +388,6 @@ SimpleSAMLphp auth module implementing custom business logic:
 - rate limiting
 - status endpoint
 
-[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://raw.githubusercontent.com/silinternational/simplesamlphp-module-silauth/develop/LICENSE)
-
 #### Database Migrations
 To create another database migration file, run the following (replacing
 `YourMigrationName` with whatever you want the migration to be named, using
@@ -466,7 +455,7 @@ load balancer) in the TRUSTED_IP_ADDRESSES environment variable (see
 `local.env.dist`).
 
 #### Status Check
-To check the status of the website, you can access this URL:  
+To check the status of the website, you can access this URL:
 `https://(your domain name)/module.php/silauth/status.php`
 
 ### SilDisco module for SAML Discovery

docs/editing_authprocs.md

@@ -1,9 +1,5 @@
 The sildisco module includes a few Auth Procs that can be called from the `config.php` file or **SP or IdP metadata**.
 
-### AttributeMap.php
-
-Copies (rather than replaces) attributes according to an attribute map.
-
 ### TagGroup.php
 
 Grabs the values of the `urn:oid:2.5.4.31` (member of) attribute and prepends them with `idp|<the_idp's_name>|`.

docs/the_hub.md

@@ -1,10 +1,5 @@
 The hub will need its certs, `config.php` and `authsources.php` files as a normal simplesamlphp installation. Examples of these can be found in the `./development/hub` folder. (Note the `discoURL` entry in the `authsources.php` file.)
 
-Other files it will need are as follows ...
-* The files in the `./src` folder will need to go into `/data/vendor/simplesamlphp/simplesamlphp/modules/sildisco/src`
-* The files in the `./public` folder will need to go into `/data/vendor/simplesamlphp/simplesamlphp/modules/sildisco/public`
-* The `./sspoverrides/www_saml2_idp/SSOService.php` file will need overwrite the same out-of-the-box file in `/data/vendor/simplesamlphp/simplesamlphp/public/saml2/idp/`
-
 ### Metadata files
 The hub should use the `saml20-*-remote.php`  files from [ssp-base](https://github.com/silinternational/ssp-base) in `/data/vendor/simplesamlphp/simplesamlphp/metadata/`.  These pull in metadata from all the files named `idp-*.php` and `sp-*.php` respectively, including those in sub-folders.
 
@@ -22,12 +17,12 @@ It is also used by the `TagGroup.php` Auth Proc to convert group names into the
 `idp|<IDPNamespace>|<group name>`.
 
 ##### SPList
-In order to limit access to an IdP to only certain SP's, add an `'SPList'` array entry to the metadata for the IdP.  The values of this array should match the `entity_id` values from the `sp-remote.php` metadata.
+In order to limit access to an IdP to only certain SP's, add an `'SPList'` array entry to the metadata for the IdP.  The values of this array should match the `entityid` values from the `sp-remote.php` metadata.
 
 ##### excludeByDefault
 If you want to require SP's to list a certain IdP in their IDPList entry in order to be able to access it, add `excludeByDefault => true` to that IdP's metadata.
 
 ### Forced IdP discovery
-The `.../src/IdP/SAML2.php` file ensures that if an SP is allowed to access more than one IdP, then the user will be forced back to the IdP discovery page, even if they are already authenticated through one of those IdP's.
+The `dockerbuild/ssp-overrides/sp-php.patch` file ensures that if an SP is allowed to access more than one IdP, then the user will be forced back to the IdP discovery page, even if they are already authenticated through one of those IdP's.
 
 The reason for this is to ensure that the user has a chance to decide which of their identities is used for that SP.

local.env.dist

@@ -10,7 +10,6 @@ ANALYTICS_ID=
 BASE_URL_PATH=
 COMPOSER_ALLOW_SUPERUSER=1
 COMPOSER_AUTH={"github-oauth":{"github.com":"token-here"}}
-COMPOSER_CACHE_DIR=/composer
 HUB_MODE=false
 ENABLE_DEBUG=