Plugins/Auth/Saml: Difference between revisions

Revision as of 13:03, 12 February 2019

Authentication plugin for SAML 2.0 based SSO integration. This uses the excellent SimpleSAMLPHP software as a Service Provider.

The plugin is shipped as part of core Mahara.

To use / test the plugin you will need to do the following:

Have a memcached server running

And know what the IP address / port number you can use to connect on.

To install one locally (on linux) go

sudo apt-get install memcached

This should set you up with one running on port 11211 - to test that this is correct you can go

telnet 127.0.0.1 11211

and you should get a connection

Have the php-memcached module installed

To install it go

sudo apt-get install php-memcached
sudo phpenmod memcached
sudo service apache2 restart

Update your config.php file so that it knows to use memcached for SAML sessions

Add the following settings

$cfg->ssphpsessionhandler = 'memcached';
$cfg->memcacheservers = '127.0.0.1:11211'; // change if your memcached server is on different IP/port

Ensure the plugin is active in Mahara

Under Administration menu (wrench icon) -> Extensions -> Plugin administration. See Manual - SAML config for more information

Click on the configuration for auth SAML (cog) icon to check that the plugin is set up correctly.

Follow the 'View metadata' link to fetch the Service Provider (SP) metadata that you will need to provide to the IdPs that you wish to authenticate against.

Now we need to perform the institution level configuration

Within each institution, add the SAML 2.0 Identity Provider:

See Manual - SAML institution config for more information

@@ Line 5: / Line 5: @@
 To use / test the plugin you will need to do the following:
-) Have a memcached server running and know what the IP address / port number you can use to connect on
+===Have a memcached server running===
+And know what the IP address / port number you can use to connect on.
 To install one locally (on linux) go
@@ Line 14: / Line 15: @@
 and you should get a connection
-) Have the php-memcached module installed. to install it go
+===Have the php-memcached module installed===
+To install it go
   sudo apt-get install php-memcached
   sudo phpenmod memcached
   sudo service apache2 restart
-) Update your config.php file so that it knows to use memcached for SAML sessions - add the following settings
+===Update your config.php file so that it knows to use memcached for SAML sessions===
+Add the following settings
   $cfg->ssphpsessionhandler = 'memcached';
   $cfg->memcacheservers = '127.0.0.1:11211'; // change if your memcached server is on different IP/port
-) Ensure the plugin is active under Administration menu (wrench icon) -> Extensions -> Plugin administration.
+===Ensure the plugin is active in Mahara===
+Under Administration menu (wrench icon) -> Extensions -> Plugin administration.
+See [https://manual.mahara.org/en/18.10/administration/extensions.html#authentication-saml Manual - SAML config] for more information
 Click on the configuration for auth SAML (cog) icon to check that the plugin is set up correctly.
 Follow the 'View metadata' link to fetch the Service Provider (SP) metadata that you will need to provide to the IdPs that you wish to authenticate against.
-) Now we need to perform the institution level configuration.  Within each institution, add the SAML 2.0 Identity Provider:
+===Now we need to perform the institution level configuration===
+Within each institution, add the SAML 2.0 Identity Provider:
-[[Image:config_inst_add_saml.png|config_inst_add_saml.png]]
-Now, configure the SAML plugin:
-[[Image:config_inst_saml2.png|config_inst_saml2.png]]
-The Identity Service Provider (IdP) is the one that was configured in the SimpleSAMLPHP <code>metadata/saml20-idp-remote.php </code>file, stripped of the URL decoration down to the hostname like above.
-When a user authenticates using SAML 2.0, the Service Provider (SP) negotiates access to a certain list of attributes, that are then made available to the service being accessed (in this case, Mahara).  One of these attributes must hold the institution name/id of this institution being configured against.  In this case the Mahara institution has an id of "wahoodle", and thie "o" user attribute is the institution attribute allocated to the user that we are expecting to find the institution name in - namely "wahoodle" in this instance.
-This enables one Identity Provider using varying attribute names, and values, to map users to different Mahara Institutions.
-Typically the Identity Provider (IdP) is backed by an LDAP directory for the user attribute store, so in the above example the attribute names being mapped look just like common LDAP ones.
-User attribute maps the IdP attribute to the mahara "
-Username for external authentication
-".
-Update user details on login will mean that the following 3 attribute mappings get updated from the values supplied by the IdP, everytime a user logs in.
-We auto-create users allows the auto creation of Mahara accounts upon user first contact.
-In order to trigger the use of SAML based authentication, point the browser at http://[mahara service location]/auth/saml/ - this is the launch URL that you would use as the navigation integration point for other services to connect to Mahara.
-===Files===
-*[[File:Admin_extn_saml.png]]
+See [https://manual.mahara.org/en/18.10/administration/institutions.html#saml-authentication Manual - SAML institution config] for more information
-*[[File:Config_inst_add_saml.png]]
-*[[File:Config_inst_saml2.png]]
 [[Category:plugins]][[Category:Authentication Plugins]]