Difference between revisions of "Plugins/Auth/Saml"

From Mahara Wiki
< Plugins‎ | Auth
Jump to navigation Jump to search
m
Line 1: Line 1:
Authentication plugin for SAML 2.0 based SSO integration. This uses the excellent [http://rnd.feide.no/simplesamlphp SimpleSAMLPHP] software as a Service Provider.
+
Authentication plugin for SAML 2.0 based SSO integration. This uses the excellent [https://simplesamlphp.org/ SimpleSAMLPHP] software as a Service Provider.
  
The plugin is available via the Mahara git repository, and can be found [http://git.mahara.org/?p=contrib/plugin/auth/saml.git;a=summary here] .  General plugin help can be found [[Developer Area/Plugins|Plugins]].
+
The plugin is shipped as part of core Mahara.
  
Install the plugin in /auth/saml.
+
To use / test the plugin you will need to do the following:
  
Ensure the plugin is active under "Administer Extensions".
+
1) Have a memcached server running and know what the IP address / port number you can use to connect on
  
Set the global (site wide) configuration for the Saml plugin by selecting the saml [ Config ] link.
+
To install one locally (on linux) go
 +
sudo apt-get install memcached
  
[[Image:admin_extn_saml.png|admin_extn_saml.png]]
+
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
  
The site wide configuration points to the SimpleSAMLPHP library path, and the associated configuration directory.
+
2) Have the php-memcached module installed. to install it go
 +
sudo apt-get install php-memcached
 +
sudo phpenmod memcached
 +
sudo service apache2 restart
 +
 +
3) 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
  
It is necessary to configure SimpleSAMLPHP independently of the setup required for the Auth Plugin.  The details for this can be found at http://rnd.feide.no/content/using-simplesamlphp-service-provider
+
4) Ensure the plugin is active under Administration menu (wrench icon) -> Extensions -> Plugin administration.
  
Now we need to perform the institution level configuration.  Within each institution, add the SAML 2.0 Identity Provider:
+
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.
 +
 
 +
4) 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]]
 
[[Image:config_inst_add_saml.png|config_inst_add_saml.png]]
Line 23: Line 36:
 
[[Image:config_inst_saml2.png|config_inst_saml2.png]]
 
[[Image:config_inst_saml2.png|config_inst_saml2.png]]
  
The Identity Service 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.
+
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.
 
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.

Revision as of 11:53, 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:

1) 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

2) Have the php-memcached module installed. to install it go

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

3) 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

4) Ensure the plugin is active under Administration menu (wrench icon) -> Extensions -> Plugin administration.

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.

4) Now we need to perform the institution level configuration.  Within each institution, add the SAML 2.0 Identity Provider:

config_inst_add_saml.png

Now, configure the SAML plugin:

config_inst_saml2.png

The Identity Service Provider (IdP) is the one that was configured in the SimpleSAMLPHP metadata/saml20-idp-remote.php 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

  • Admin extn saml.png
  • Config inst add saml.png
  • Config inst saml2.png