CONTENTS OF THIS FILE
---------------------

 * Introduction
 * Requirements
 * Installation
 * Configuration
 * Troubleshooting

INTRODUCTION
------------

This module provides Basic Shibboleth Authentication. Shibboleth is a
single-sign-on (SSO) solution part of the InCommon Federation. The module
delegates several more complex tasks to plugins. The plugins used in
this module are:
    * UserProvider- loads users.
    * AuthFilter- applies additional authentication rules.
    * Grouper- assigns Role permissions based on user's Grouper group.

For a full description of the module, visit the project page:
https://www.drupal.org/project/basicshib

For a description of Shibboleth SSO, visit the InCommon site:
https://www.incommon.org/software/shibboleth/

For a description of Grouper software, visit the InCommon site:
https://incommon.org/software/grouper/

REQUIREMENTS
------------

* This module requires no modules outside of Drupal core.

INSTALLATION
------------

* Install as you would normally install a contributed Drupal module. Visit
https://www.drupal.org/project/basicshib/releases/3.0 for more details.

* A PHPUnit version of 6.5 may be required for unit testing compatibility.

CONFIGURATION
-------------

* Enable Basic Shibboleth Authentication in Home >> Extend >> Authentication.
Then configure the Shibboleth Login/Out access. This is achieved in one of two ways.

    - Create a Login Link on a menu similar format to the one shown below:
      '/shibboleth.sso/login?target=https://<SITE NAME>/basicshib/login
    or
    - From 'admin/structure/block', add the 'Shibboleth Login Block' in the
      appropriate 'Region' for your site.

* All the configuration for BasicShib can be accessed from '/admin/config/basicshib'

    - The first tab 'BasicShib settings', is prepopulated with the common Shibboleth
      settings. They can be modified to meet your particular need.

        * Create new user at login
          If checked if a new user logs into the site, via Shibboleth, they will be
          assigned tha authenticated role. if Grouper authorization is enabled, extra
          roles that correspond the user's defined grouper groups will also be
          assigned.

        * Handlers
          The default login and logout handlers are pre-populated, if your's are
          different, enter the values that match your requirements.

        * Attributes
          Contains three fields; User Name, Email and Session, modify the default
          values as needed to match your Shibboleth implementation.

        * User Interface
          Contains field titles that are displayed on forms and the messages displayed
          on errors generated when a user tries to login.

    - Second tab shows the Grouper specific configuration

      Overview:
      Grouper allows Drupal Roles to be automatically added or removed from a user when
      they login to a site. A user is assigned one or more Roles in Drupal. Each Role
      has a Grouper Authorization. An Authorization can have multiple Grouper Groups.
      On Logging in via Shibboleth with Grouper enabled the user's groups are compared
      to all Authorizations. If the user has a Grouper Group defined in the
      Authorization they are granted that Drupal Role assigned to that Authorization.
      If however they do not have a Grouper Group that is defined in one of their
      previously assigned Drupal Roles. That Role will be removed from their Account.

        * if Grouper is disabled there is only one checkbox, to enable Grouper
          authorizations. If Grouper is enabled there are options that define how
          roles are provisioned.

          - Remove non-Grouper roles
            If checked the user's Drupal roles that do not have a corresponding
            Grouper Groups. Those Drupal roles will be removed when the User logs in
            next.

          - Remove Administrator Role
            If checked when logging in if the User has the Administrator Drupal role
            but not a Grouper Group that would assign the Administrator role. Then
            the Administrator Role would be removed from the User.

            NOTE: If there are no Grouper policies mapped to a Drupal role checking
            this option could result in no users on the site having Administrator
            access.

        * Upon saving this form with the Grouper Enabled checkbox checked. Two more
        Grouper related tabs appear on the page, Policies and Authorization.

    - There are two steps to configure Grouper Integration.

      1. Policies
        Clicking the Policies Tab displays a list of all the entered Grouper policies. A
        button at the top of the form allows you to 'Add a New Policy'. In the Operations
        field on the Policy List are the options to edit and delete that Grouper Policy.

        Clicking 'Add Policy' displays the following form.
          - Label: The human readable name of the Grouper Policy. When creating a new
            policy you are presented with an option to alter the automatically
            generated machine name for the group.
          - Enabled: A checkbox showing the status of the Policy
          - Authorization Policy: The actual Grouper Policy, Grouper paths are ':'
            delimited strings. Multiple paths should be separated by a semicolon.
          - Description: An optional field where notes about the Policy can be
            entered.

        Usage:
          Enter a Human Readable name in Label. Naming it similar to the Drupal Role
          it is associated with may make it easier understand its relationship.
          In Policy enter the name of the Grouper Policy. If some extra notes on who
          is in this policy can be entered in the Description field. Clicking Save
          will save the Policy and return you to the Policy list.

          You can enter all the policies at one time by clicking 'Add Policy' after
          saving each Policy.

        NOTE: Policies need to be added before Drupal Roles can be assigned Grouper
        Authorizations -- Outlined below (Authorizations)

      2. Authorizations
        Authorizations can contain one or more Grouper Policies. This allows a single
        Drupal role be assigned multiple Grouper Policies.

        Authorizations can be entered in two ways.
         a. Clicking 'Add Authentication' displays the following form.
           - Label: The Drupal Role that should be assigned the Policies.
           - Enabled: A checkbox showing the status of the Authorization
           - Policies: The list of Policies assigned to this Authentication.
           - Description: An optional field where notes about the Authorization can be
              entered.

           Usage:
             Enter the Drupal Role these Policies are attached to. In Policies enter the
             name of the Grouper Policies that is to be used in this Authorization,
             multiple policies can be added. They can be entered separated
             by commas, or one Policy per line. If some notes on what users the policies
             refer to can be entered in Description. Once the form is complete click Save
             to save the Authorization.

             You can enter all the Authorizations at one time by clicking 'Add Authorization'
             after saving each Authorization.

         b. Open The Drupal Roles form '/admin/people/roles' and select the Role you wish to
            assign Authorizations. At the bottom of the Edit Role form there is a list of
            checkboxes. The list displays the available Authorizations. Checking the
            Authorizations you want to assign to Role and clicking Save will assign the
            selected Authorizations to the Role.

            The Authorizations assigned to Roles can easily be viewed by visiting
            '/admin/config/basicshib/authorization',

TROUBLESHOOTING
---------------

* The Grouper plugin assumes an HTTP_ISMEMBEROF user attribute is being released by the SP.
Should any errors arise, ensure that your SP is configured properly.
