shibbolethauth Plugin

DokuWiki is a nice wiki. Sympa is a nice mailing list manager. Shibboleth is a nice authentication infrastructure. DokuWiki has its own authentication, group definition and authorization mecanisms. This plugin allows to extends these mecanism to

1. authenticate users via on Shibboleth authentication server (also named Identity Provider) and
2. use list membership notions in DokuWiki's authorization engine.

This plugin has been written by Dominique Launay, Olivier Salaün and Yohann Lecuyer.

This plugin is designed to quickly install or uninstall a new authorization mode based on Shibboleth.

Once the plugin is installed you can set up or unset this mode in the admin menu of DokuWiki, in the subsection related to this plugin.

This plugin is meant to obtain authentication from Shibboleth and authorizations from a Sympa server using the SOAP protocol, for a DokuWiki server.

The different groups with DokuWiki are the same that with Sympa, despite the two authentication/authorization systems are distinct.

Once a user has logged in, the email address is provided by Shibboleth as an attribute. The user attribute in DokuWiki application (the list of groups the user is member of) is the list of the user memberships. DokuWiki authorization engine can refer to these lists as groups to restrict privileges to wiki parts. Suppose a namespace is limited to a group, let's say @sympa-users@cru.fr, when subscribing to this list you automatically gain access to that namespace. Sympa is used as a group manager to control DokuWiki resources access.

To install this plugin, you should follow the steps listed below.

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

• shibbolethauth-1.2.tar.gz

A new item entitled authentication using Shibboleth appears in the admin plugin. Click on this item to install the authentication class at its right place.

If this step fails for some reason, you can copy it manually

% cd //dokuwiki_install_dir//
% cp -p lib/plugins/shibbolethauth/file/shibboleth.class.php inc/auth/

If you are using Sympa group-based access control, you'll also need to install the php-soap module because communications with the Sympa server uses SOAP protocol. If you are on a Fedora Core server, you can run the following command, otherwise find the appropriate one:

% yum install php-soap

Next we'll need to configure DokuWiki to let it know about its Shibboleth and Sympa environments, but we first need to setup these Shibboleth and Sympa environments.

The Service Provider is the Shibboleth component that does protect a web resource; it communicated with a Shibboleth Identity Provider component.The Service Provider needs to be configured, so that the Shibboleth authentication session is initiated whenever the user hits a given URL. Therefore we use the Shibboleth mecanism named lazy sessions; this mecanism allows to trigger Shibboleth authentication whenever the user is redirected to a specially constructed URL named handlerURL.

Installing a Shibboleth SP and configuring it is out of scope of this documentation; we'll just provide you with some configuration elements:

• configure your shibboleth2.xml file (or shibboleth.xml if running Shibboleth 1.3) to enable a so-called Application that represents a Shibboleth context with associated discovery service, metadata, etc. You'll later need the following informations from the Shibboleth configuration file: Sessions/handlerURL, Sessions/SessionInitiator/Location, Sessions/LogoutInitiator/Location.
• add the following configuration to your Apache configuration file

  <Location /wiki>
    AuthType shibboleth
    ShibRequireSession Off
    require shibboleth
  </Location>

This Apache configuration enables the Shibboleth-based authentication on the wiki URL, but it does not trigger the authentication (ShibRequireSession Off).

The Sympa mailing list server provides a SOAP interface to most of its services. This SOAP interface is used by DokuWiki to query the list memberships of a given user.

You'll need to enable the SOAP service on your mailing list server. To do so, your should proceed as follows on the mailing list server:

• add this kind of directive to your Apache configuration file ScriptAlias /soap /home/sympa/bin/sympa_soap_server-wrapper.fcgi
• edit the sympa.conf or robot.conf configuration file and add this soap_url http://your.server/soap

Now that your SOAP server is up and running, you need to build the trust between your DokuWiki server and your Sympa server, so that Sympa SOAP accepts requests from the wiki. This can be configured in the /home/sympa/etc/trusted_applications.conf file as follows

trusted_application
  name myWiki
  md5password adeb1536f480475f7d593219aa1afd74c
  proxy_for_variables USER_EMAIL,remote_host

Note that the md5password is an MD5 hash for 'myPassword'; it was generated using the sympa.pl --md5_digest=password command. Of course you should use a different password

You'll use the name and password defined here later on while configuring Shibboleth authentication plugin for DokuWiki.

Once you have set the Shibboleth authentication mode up and configured your Shibboleth authentication, you can set it as the default authentication system through the admin configuration menu. You must complete the following parameters:

• Sympa SOAP server wsdl URL,
• Sympa SOAP server login and password,
• Shibboleth login URL based on the handlerURL+SessionInitiator/Location,
• Shibboleth logout URL based on the handlerURL+LogoutInitiator/Location,
• Name of the environment variable set by Shibboleth that contains the user email address,
• Boolean variable that enables use of Sympa-based groups (note that you can also use local DokuWiki groups).

You can also add these configuration parameters in the DokuWiki directory /conf/local.php file as follows:

$conf['authtype']                                             = 'shibboleth';
$conf['plugin']['shibbolethauth']['shibbolethEmailAttribute'] = 'mail';
$conf['plugin']['shibbolethauth']['useSympa']                 = 1;
$conf['plugin']['shibbolethauth']['sympaSoapService']         = 'http://mysympaserver.mydomain/skins/wsdl.xml';
$conf['plugin']['shibbolethauth']['sympaApplicationId']       = 'myWiki';
$conf['plugin']['shibbolethauth']['sympaApplicationPwd']      = 'myPassword';
$conf['plugin']['shibbolethauth']['shibbolethLoginURL']       = 'https://myserver.mydomain/Shibboleth.sso/wayf';
$conf['plugin']['shibbolethauth']['shibbolethLogoutURL']      = 'https://myserver.mydomain/Shibboleth.sso/Logout';

• The WSDL description page of the SOAP interface must be: http://you-sympa-server-address/wsdl
• The plugin requires SOAP enabled in php (if its shared, be sure to install all relevant packages)
• You must use a version of DokuWiki higher than DokuWiki-2006-03-09
• to disable native password sending $conf['resendpasswd'] must be filled to 0 in 'local.php''
• this plugin logs into normal apache erreor_log file with shibbolethauth prefix

DokuWiki requires the user email address; therefore both Shibboleth Identity Provider and Service Provider should be configured to carry the user email address. You should check the Shibboleth configuration (attribute release policy at the identity provide and attribute acceptance policy at the service provider).

The name of the HTTP header field containing the email address user attribute might also be wrong. Check both shibbolethEmailAttribute DokuWiki configuration parameter and the Shibboleth service provider configuration.

You can report bugs via the tracker: https://sourcesup.renater.fr/tracker/?group_id=439

Have a look to Sympa and DokuWiki farm integration for Virtual Organizations, and enjoy Sympa server + DokuWiki farm + SSO authentication (Shibboleth)!