Information for: DEVELOPERS   PARTNERS   SUPPORT

Installing the SimpleSAMLphp library

Important

EOL notice! Drupal 8 reached end-of-life on November 2, 2021. For more information, see Frequently Asked Questions.

The information on this documentation page is part of the SimpleSAMLphp installation process. Where possible, Acquia recommends you use the BLT steps outlined on the Setting up SimpleSAMLphp with Acquia BLT page in place of step 1 through 9 on this page.

Complete the following installation instructions for SimpleSAMLphp on a branch in a non-production environment:

  1. Download the latest version of the SimpleSAMLphp library.

  2. Extract the SimpleSAMLphp library to the root directory of your repository (the directory that contains your docroot acquia-utils and library directories). Be sure to append the SimpleSAMLphp version number to the name of this directory (for example, simplesamlphp-1.17.7).

  3. In the root directory of your repository, create a symbolic link from the library to simplesamlphp in the same directory in which the library is located. Using the directory name simplesamlphp-1.17.7 from the previous step, enter a command similar to the following:

    ln -s simplesamlphp-1.17.6 simplesamlphp
    

    This symlink allows you to upgrade SimpleSAMLphp by adding the new version and then updating the symlink. It also ensures the web interface is publicly accessible, while keeping the configuration outside of a web-accessible directory. When correctly symlinked, your directory should resemble the following example:

    dr-xr-s---  9 www-data meow 4096 May 19 20:55 docroot
    -r--r-----  1 www-data meow  655 Apr  1 21:17 .gitignore
    dr-xr-s---  2 www-data meow 4096 Apr  1 21:17 library
    -r--r-----  1 www-data meow  598 Apr  1 21:17 README.acquia
    lrwxrwxrwx  1 www-data meow   20 May 12 18:17 simplesamlphp -> simplesamlphp-1.17.6
    dr-xr-s--- 18 www-data meow 4096 May 12 18:17 simplesamlphp-1.14.10
    dr-xr-s--- 18 www-data meow 4096 May 12 18:17 simplesamlphp-1.17.6
    
  4. Change to your docroot directory, and then create a symbolic link for simplesaml. The symlink should point to the www directory in the SimpleSAMLphp library. For example:

    cd docroot
    ln -s ../simplesamlphp/www simplesaml
    

    The preceding commands ensure the web interface is publicly accessible at http://[www.example.com]/simplesaml while keeping the configuration outside of a web-accessible directory. When correctly symlinked, your directory should resemble the following example:

    -r--r-----  1 www-data examplesite 5382 Apr  1 21:17 README.txt
    -r--r-----  1 www-data examplesite 1550 Apr  1 21:17 robots.txt
    dr-xr-s---  2 www-data examplesite 4096 Apr  1 21:17 scripts
    lrwxrwxrwx  1 www-data examplesite   20 May 12 18:17 simplesaml -> ../simplesamlphp/www
    

    Important

    When upgrading SimpleSAMLphp, add the acquia_config.php file to the new folder and update it if needed. If SimpleSAMLphp can’t access the acquia_config.php file, Cloud Platform will display errors in the SimpleSAMLphp log file.

  5. Back up your application’s database.

  6. Install and enable the following modules to your codebase:

    Important

    Drupal’s administrative interface will display information on several pages that indicates SimpleSAMLphp isn’t active.

    Do not enable Activate authentication via SimpleSAMLphp until you have completed all other steps in this process. If you enable this option before authentication is completely configured, you won’t be able to sign in to your website.

    If you prematurely enable this setting and are locked out of your website, you can either use the drush uli command to sign in, or you can temporarily disable the simpleSAMLphp Authentication module with Drush. For help, see Disabling modules that block sites on Cloud Platform.

  7. Add the location of your SimpleSAMLphp_auth library to your settings.php file, based on your subscription type:

    Add the following lines to your settings.php file on lines that precede the Acquia require line, depending on your installed version of Drupal:

    if (file_exists('/var/www/site-php')) {
    $conf['simplesamlphp_auth_installdir'] = "/var/www/html/" . $_ENV['AH_SITE_NAME'] . "/simplesamlphp";
    }
    

    Add the following lines to a pre-settings.php hook, depending on your installed version of Drupal:

    <?php
    $conf['simplesamlphp_auth_installdir'] = "/var/www/html/" . $_ENV['AH_SITE_NAME'] . "/simplesamlphp";
    
  1. Modify your composer.json file to require version 3.0 or later of the simplesamlphp_auth module in your codebase:

    composer require drupal/simplesamlphp_auth --update-with-all-dependencies
    
  2. Change to your docroot directory, and then create a symbolic link for simplesaml. The symlink should point to the www directory within your vendor folder. This will likely be located at ../vendor/simplesamlphp/simplesamlphp/www.

    cd docroot
    ln -s ../simplesamlphp/www simplesaml
    

    The preceding commands ensure the web interface is publicly accessible at http://[www.example.com]/simplesaml while keeping the configuration outside of a web-accessible directory. When correctly symlinked, your directory should resemble the following example:

    -r--r-----  1 www-data examplesite 5382 Apr  1 21:17 README.txt
    -r--r-----  1 www-data examplesite 1550 Apr  1 21:17 robots.txt
    dr-xr-s---  2 www-data examplesite 4096 Apr  1 21:17 scripts
    lrwxrwxrwx  1 www-data examplesite   20 May 12 18:17 simplesaml -> ../simplesamlphp/www
    
  3. If you are not using BLT:

    1. Create a new directory: ${project.root}/simplesamlphp/config.

    2. Add the following to the scripts section in your composer.json “apply-patches”:

      [
       "mkdir -p vendor/simplesamlphp/simplesamlphp/config; rsync -a simplesamlphp/config/ vendor/simplesamlphp/simplesamlphp/config/",
       "mkdir -p vendor/simplesamlphp/simplesamlphp/metadata; rsync -a simplesamlphp/metadata/ vendor/simplesamlphp/simplesamlphp/metadata/"
      ],
      
    3. Add @apply-patches to the “post-install-cmd” and “post-update-cmd” sections in your composer.json example:

      "post-install-cmd": [
         "@apply-patches"
       ],
      "post-update-cmd": [
         "@apply-patches"
       ],
      
  4. Add the following code to your .htaccess file to prevent your application from displaying a Permission Denied error message when attempting to load the SimpleSAMLphp user interface:

    # Allow access to simplesaml paths
    RewriteCond %{REQUEST_URI} !^/simplesaml
    

    The previous code must be added after the following line in your .htaccess file:

    RewriteCond %{REQUEST_URI} !/core/modules/system/tests/https?.php
    

    For more information, see the README.

  5. Back up your application’s database.

  6. Install and enable the following modules to your codebase:

    Important

    Drupal’s administrative interface will display information on several pages that indicates SimpleSAMLphp isn’t active.

    Do not enable Activate authentication via SimpleSAMLphp until you have completed all other steps in this process. If you enable this option before authentication is completely configured, you won’t be able to sign in to your website.

    If you prematurely enable this setting and are locked out of your website, you can either use the drush uli command to sign in, or you can temporarily disable the simpleSAMLphp Authentication module with Drush. For help, see Disabling modules that block sites on Cloud Platform.

  7. Add the location of your SimpleSAMLphp_auth library to your settings.php file, based on your subscription type:

    Add the following lines to your settings.php file on lines that precede the Acquia require line, depending on your installed version of Drupal:

    if (file_exists('/var/www/site-php')) {
    $settings['simplesamlphp_dir'] = "/var/www/html/" . $_ENV['AH_SITE_NAME'] . "/simplesamlphp";
    }
    

    Add the following lines to a pre-settings.php hook, depending on your installed version of Drupal:

    <?php
    $settings['simplesamlphp_dir'] = "/var/www/html/" . $_ENV['AH_SITE_NAME'] . "/simplesamlphp";
    

After completing these steps, you must next configure your config.php file.