diff --git a/README.md b/README.md index 11864a8..51db3ed 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,67 @@ # SUMMARY -The simplesamlphp_auth module makes it possible for Drupal to support SAML for -authentication of users. The module will auto-provision user accounts into +The simplesamlphp_auth module makes it possible for Drupal to support SAML for +authentication of users. The module will auto-provision user accounts into Drupal if you want it to. It can also dynamically assign Drupal roles based on identity attribute values. # PREREQUISITES -1. You must have SimpleSAMLphp installed and configured as a working service -point (SP) as the module uses your local SimpleSAMLphp SP for the SAML support. -If you install the simplesamlphp_auth module with Composer support, you could -use the codebase that will be placed in your +1. You must have SimpleSAMLphp installed and configured as a working service +point (SP) as the module uses your local SimpleSAMLphp SP for the SAML support. +If you install the simplesamlphp_auth module with Composer support, you could +use the codebase that will be placed in your docroot/vendor/simplesamlphp/simplesamlphp directory (see "Installation" below). -You can also download and install SimpleSAMLphp separately. For more -information on installing and configuring SimpleSAMLphp as an SP visit: +You can also download and install SimpleSAMLphp separately. For more +information on installing and configuring SimpleSAMLphp as an SP visit: http://www.simplesamlphp.org. IMPORTANT: Your SP must be configured to use something other than phpsession for session storage (in config/config.php set store.type => 'memcache' or 'sql'). -To use memcache session handling you must have memcached installed on your -server and PHP must have the memcache extension. For more information on -installing the memcache extension for PHP visit: +To use memcache session handling you must have memcached installed on your +server and PHP must have the memcache extension. For more information on +installing the memcache extension for PHP visit: http://www.php.net/manual/en/memcache.installation.php -If you are on a shared host or a machine that you cannot install memcache on +If you are on a shared host or a machine that you cannot install memcache on then consider using the sql handler (store.type => 'sql'). -Make sure your SimpleSAMLphp installation has a correctly configured "config" -and "metadata" folder, and an appropriate vhost configuration. See +Make sure your SimpleSAMLphp installation has a correctly configured "config" +and "metadata" folder, and an appropriate vhost configuration. See http://www.simplesamlphp.org for more information. - -2. You must have installed the ExternalAuth module -(https://www.drupal.org/project/externalauth). See README.txt in the + +2. You must have installed the ExternalAuth module +(https://www.drupal.org/project/externalauth). See README.txt in the ExternalAuth module for installation instructions. - -3. It is recommended to have Composer Manager -(https://www.drupal.org/project/composer_manager) module installed and allow it + +3. It is recommended to have Composer Manager +(https://www.drupal.org/project/composer_manager) module installed and allow it to download the simplesamlphp libraries. See README.txt in the composer_manager module for installation instructions. If Composer is not an option for you, see -the installation instructions below to link your SimpleSAMLphp instance with +the installation instructions below to link your SimpleSAMLphp instance with Drupal through settings.php. - + # INSTALLATION -The Drupal simplesamlphp_auth module will need to connect to a working +The Drupal simplesamlphp_auth module will need to connect to a working SimpleSAMLphp instance. This can be done in two ways - depending on your setup: ## INSTALLATION WITH COMPOSER MANAGER -Make sure you have the composer_manager module installed according to its +Make sure you have the composer_manager module installed according to its README.txt. 1. Download the simplesamlphp_auth module 2. Uncompress it 3. Move it to the appropriate modules directory (usually, /modules) 4. Run the "composer drupal-update" command (see Prerequisites above) -5. The SimpleSAMLphp library will now be installed in your +5. The SimpleSAMLphp library will now be installed in your docroot/vendor/simplesamlphp/simplesamlphp directory. Configure the library (see http://www.simplesamlphp.org) by adding the 'config' -and 'metadata' directories with appropriate settings. If is recommended to -symlink those from your already installed SimpleSAMLphp instance or from +and 'metadata' directories with appropriate settings. If is recommended to +symlink those from your already installed SimpleSAMLphp instance or from another location where they are saved. 6. Go to the Drupal module administration page for your site 7. Enable the module @@ -69,12 +69,12 @@ another location where they are saved. ## INSTALLATION WITHOUT COMPOSER -1. Make sure you have a working SimpleSAMLphp installation. It needs to be a +1. Make sure you have a working SimpleSAMLphp installation. It needs to be a standalone installation, which has a "vendor" folder in the root of the project. 2. Download the simplesamlphp_auth module 3. Uncompress it 4. Move it to the appropriate modules directory (usually, /modules) -5. In your settings.php file, add the location of your SimpleSAMLphp +5. In your settings.php file, add the location of your SimpleSAMLphp installation (no trailing slashes): e.g.: @@ -86,15 +86,15 @@ installation (no trailing slashes): # UPGRADING -The Drupal 8 version of this module provides a tested upgrade path from Drupal +The Drupal 8 version of this module provides a tested upgrade path from Drupal 6.x-2.x, Drupal 7.x-2.x and Drupal 7.x-3.x branches, through the Migrate API in Drupal 8. Other branches might have a working upgrade path, but are untested. -In order to upgrade the SimpleSAMLphp settings from your Drupal 6 or Drupal 7 +In order to upgrade the SimpleSAMLphp settings from your Drupal 6 or Drupal 7 website, follow these instructions: - Install and enable the simplesamlphp_auth module as described above. - Activate the Migrate and Migrate Drupal core modules and perform your - upgrade migration. + upgrade migration. See https://www.drupal.org/upgrade/migrate for more information about this process. - Some settings did not exist in earlier versions of this module. They will @@ -102,9 +102,53 @@ website, follow these instructions: - The setting "Activate authentication via SimpleSAMLphp" will always be migrated as deactivated, to avoid being locked out of your website after migration. Please check the migrated configuration thoroughly, and after - validation of the settings, activate authentication via SimpleSAMLphp + validation of the settings, activate authentication via SimpleSAMLphp manually. + + +## Updating from Drupal 9 + simplesamlphp_auth 3 to Drupal 10 + simplesamlphp_auth 4 + +Drupal 10 has a dependency on Symfony 6. As of this release, the underlying library, `simplesamlphp/simplesamlphp`, does not have a release that is compatible with Symfony 6. The current version of its `master` branch is compatible with Symfony 6, but there is no roadmap for a release; it might be merged into the 2.x branch, but it may not. When Symfony 7 is released in November 2023, there is no guarantee that `simplesamlphp/simplesamlphp` won't simply move on to Symfony 7 compatibility without providing a Symfony 6-compatible release. See https://github.com/simplesamlphp/simplesamlphp/issues/1689 + +**Therefore, integrating your Drupal site with the `simplesamlphp/simplesamlphp` library at this time is a risk. If you understand the risk, you can install a specific commit hash of the library that is compatible, as explained below.** + +These instructions should work for any Composer-based Drupal site. See https://www.drupal.org/docs/develop/using-composer/manage-dependencies#s-create-a-project + +If you have been using this module with Drupal 9, updating to Drupal 10 via Composer requires specific syntax, since you will be requiring a "development"-level package. Prior to the update, you will have Composer requirements similar to the following: + +``` +"drupal/core-recommended": "^9.5", +"drupal/simplesamlphp_auth": "^3" +``` + +1. Visit https://github.com/simplesamlphp/simplesamlphp and find the hash of the latest commit on the `master` branch (e.g., `2f37266`). + +2. Update the requirements in `composer.json` manually to the following, replacing the commit hash for `simplesamlphp` as needed. Using this syntax to target a specific commit is highly recommended, since a ``composer update`` would otherwise update to the latest available commit hash of a branch, and unexpected changes could be introduced. + +``` + "drupal/core-recommended": "^10", + "drupal/simplesamlphp_auth": "^4", + "simplesamlphp/simplesamlphp": "dev-master#2f37266" +``` + +Note: the above syntax assumes a tagged 4.x release. If that is not available, you can retrieve the 4.x branch with `"drupal/simplesamlphp_auth": "dev-4.x"`, with a specific commit hash (e.g., `dev-4.x#666615`) + +3. Remove the contents of the `vendor` directory. (This prevents an error with a nonstandard part of the simplesamlphp library, `"Unable to install module simplesamlphp/simplesamlphp-assets-base, package name must be on the form "VENDOR/simplesamlphp-module-MODULENAME".`) + +4. In case you haven't already allowed the `simplesamlphp` plugin, run `composer config allow-plugins.simplesamlphp/simplesamlphp true` + +5. Run one of the following commands, depending on how narrow or broad the Drupal 10 update needs to be: + +- Narrow: `composer update drupal/core-recommended drupal/simplesamlphp_auth simplesamlphp/simplesamlphp -W` +- Broad: `composer update -W` + +Your site should now update to Drupal 10, along with a Drupal 10-compatible version of `simplesamlphp`. If you have other Composer requirements, of course, they could prevent the update. + +6. Update the publicly-accessible directory of the simplesamlphp library from `www` to `public`, a change from `simplesamlphp` 1.x to 2.x. Your previous configuration would have used one of multiple ways to define this directory, such as a symlink or a Composer Installers directive. Configuration is out of the scope of the Drupal module. See https://simplesamlphp.org/docs/stable/simplesamlphp-install#appendix-installing-simplesamlphp-in-alternative-locations + + + # CONFIGURATION ## Basic configuration @@ -115,7 +159,7 @@ module in order to map them into Drupal. An additional step is required to allow access to SimpleSAMLphp paths within the .htaccess for the Drupal 8 version of this module. Add in the lines below at the -appropriate place within the Drupal 8 .htaccess or the configuration will +appropriate place within the Drupal 8 .htaccess or the configuration will cause permission denied errors. # Copy and adapt this rule to directly execute PHP files in contributed or @@ -127,40 +171,40 @@ cause permission denied errors. RewriteRule "^.+/.*\.php$" - [F] ## Linking SAML-authenticated users to Drupal users - + - If you don't have pre-existing Drupal users, you should make sure the checkbox "Register users" is enabled. - When a user is correctly authenticated via the IdP, a Drupal user will - automatically be created linked to the SAML authname. Upon following + When a user is correctly authenticated via the IdP, a Drupal user will + automatically be created linked to the SAML authname. Upon following successful SAML authentications, the created Drupal user will be loaded and - logged in. - + logged in. + - If you have pre-existing Drupal users, you can link them with SAML accounts upon successful SAML authentication. You can do so by enabling the option "Automatically enable SAML authentication - for existing users upon successful login". If a user successfully - authenticates via SAML, the provided SAML authname is checked against + for existing users upon successful login". If a user successfully + authenticates via SAML, the provided SAML authname is checked against available Drupal usernames. If a match is found, the pre-existing Drupal user is linked to the authenticated SAML identity. You can also match existing - users on different Drupal fields and SAML attributes. See + users on different Drupal fields and SAML attributes. See hook_simplesamlphp_auth_existing_user in simplesamlphp_auth.api.php for details. - + - Alternatively, you can link specific Drupal users to SAML accounts by checking the checkbox "Enable this user to leverage SAML authentication" upon user registration or user editing. In that case the Drupal username - (by default) will be added to the authmap table. This allows a SAML + (by default) will be added to the authmap table. This allows a SAML authenticated user with an authname identical to the one in the authmap table to be logged in as that Drupal user. If the stored authname to match on - shouldn't be the Drupal username in your use case, you can implement - hook_simplesamphp_auth_account_authname_alter() - see + shouldn't be the Drupal username in your use case, you can implement + hook_simplesamphp_auth_account_authname_alter() - see simplesamlphp_auth.api.php. - + - If you wish to limit which users can authenticate with Drupal, you can: - - allow only access to SAML users within specific roles - see + - allow only access to SAML users within specific roles - see hook_simplesamlphp_auth_allow_login in simplesamlphp_auth.api.php - - disable the "Register users" option, enable the option "Automatically - enable SAML authentication for existing users upon successful login" and + - disable the "Register users" option, enable the option "Automatically + enable SAML authentication for existing users upon successful login" and register Drupal accounts for the users you wish to allow. Make sure their username matches the SAML authname attribute, or link them based on another field (see paragraphs above). @@ -172,25 +216,25 @@ cause permission denied errors. is still set to phpsession. - If that's set up correctly, make sure your Drupal installation can connect to a working SimpleSAMLphp instance. See "INSTALLATION" above. - + * Usernames are not correctly synchronized or result in errors: - Drupal usernames need to be unique. This is enforced in code and on database level. Based on your settings, it's possible that this is not enforced in the SimpleSAMLphp attributes that are received, or that a pre-existing Drupal - user already exists with the same username. Here's how you can fix this + user already exists with the same username. Here's how you can fix this problem: - - It is recommended to set the SimpleSAMLphp Auth setting "SimpleSAMLphp + - It is recommended to set the SimpleSAMLphp Auth setting "SimpleSAMLphp attribute to be used as username for the user" to a SAML attribute that is - unique, preferably the same as "SimpleSAMLphp attribute to be used as unique - identifier for the user". This might make the Drupal username less + unique, preferably the same as "SimpleSAMLphp attribute to be used as unique + identifier for the user". This might make the Drupal username less human-readable, and might not be how you want to visually represent the user - on your website. You can fix this by altering how the account's name is + on your website. You can fix this by altering how the account's name is displayed by using hook_user_format_name_alter(). - In case of pre-existing users with the same username, you should verify if the pre-existing Drupal user and SAML-authenticated users are one and the - same person. If so, make sure you have enabled the setting "Automatically + same person. If so, make sure you have enabled the setting "Automatically enable SAML authentication for existing users upon successful login". This - will make sure the existing Drupal user will be linked to the + will make sure the existing Drupal user will be linked to the SAML-autenticated user, and not result in errors. Though you should make sure that this action is valid, and won't result in SAML-authenticated users taking over accounts of other pre-existing Drupal users.