Difference between revisions of "Plugins/Auth/Saml"

From Mahara Wiki
< Plugins‎ | Auth
Jump to navigation Jump to search
(To customise your SAML IdP Metadata)
 
(7 intermediate revisions by the same user not shown)
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".
+
===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.
+
===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
  
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
+
===Ensure the correct SSPHP files are present===
  
Now we need to perform the institution level configuration.  Within each institution, add the SAML 2.0 Identity Provider:
+
If you are installing/using Mahara via git you will need to install the ssphp module via running the command in the parent to the htdocs directory (where the Makefile file lives)
 +
make cleanssphp && make ssphp
  
[[Image:config_inst_add_saml.png|config_inst_add_saml.png]]
+
This should remove any older version and install the latest version, via composer, for the Mahara version you are using
  
Now, configure the SAML plugin:
+
===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
  
[[Image:config_inst_saml2.png|config_inst_saml2.png]]
+
Click on the configuration for auth SAML (cog) icon to check that the plugin is set up correctly.
  
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.
+
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.  
  
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.
+
===Now we need to perform the institution level configuration===
 +
Within each institution, add the SAML 2.0 Identity Provider:
  
This enables one Identity Provider using varying attribute names, and values, to map users to different Mahara Institutions.
+
See [https://manual.mahara.org/en/18.10/administration/institutions.html#saml-authentication Manual - SAML institution config] for more information
  
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.
+
===To customise your SAML IdP Metadata===
 +
If you site has more than one Identity Provider being used then when a user tries logging into the site via the SSO button they are taken to a 'Identity Provider discovery' page to choose which IdP they should login with.
  
User attribute maps the IdP attribute to the mahara "
+
If the metadata supplied by the IdP is containing the values for
 +
* OrganizationName
 +
* OrganizationDisplayName
 +
* Logo
 +
then these will be used on the discovery page.
  
Username for external authentication
+
If your IdP's metadata doesn't supply them - please ask if they can update things at their end and supply updated metadata.xml file. This will be the best option especially if you are using the metadata refresh url!
  
".
+
If they can't (or won't) then you can add in the changes manually. To do this
  
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.
+
1) Log in as site admin and edit an institution that is using the SAML metadata
  
We auto-create users allows the auto creation of Mahara accounts upon user first contact.
+
2) Edit the SAML auth instance
  
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.
+
3) In the 'Institution Identity Provider SAML metadata' field make the following changes
  
===Files===
+
a) If you want a logo image
 +
Inside the metadata.xml file:
 +
 
 +
Place just before  </IDPSSODescriptor> line
 +
 
 +
    <Extensions>
 +
      <mdui:UIInfo xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">
 +
        <mdui:Logo width="120" height="30" xml:lang="en">[URL to logo]</mdui:Logo>
 +
      </mdui:UIInfo>
 +
    </Extensions>
 +
 
 +
And update the [URL to logo] to point to a logo for the IdP reachable via the Internet, eg https://mahara.org/theme/mahara-org/images/site-logo.svg
 +
and alter height / width values if needed - a 120 x 30px png / svg image works best
 +
 
 +
b) To set the provider details
 +
 
 +
Place just after  </IDPSSODescriptor> line
 +
 
 +
  <Organization>
 +
    <OrganizationName xml:lang="en">[Provider name]</OrganizationName>
 +
    <OrganizationDisplayName xml:lang="en">[Identity provider name]</OrganizationDisplayName>
 +
  </Organization>
 +
 
 +
- Change [Provider name] to the name of the organization the IdP belongs to, eg Mahara.org
 +
 
 +
- Change [Identity Provider name] to the name of the IdP system, eg Mahara Single Sign On
 +
 
 +
'''Note''' Depending on the way your IdP structures it's metadata you may need to prefix the new Extensions and Organization* lines with same prefix as in the </IDPSSODescriptor> line, eg if that line looks like </md:IDPSSODescriptor> then you will need to add 'md:' to the lines that don't start it
  
*[[File:Admin_extn_saml.png]]
 
*[[File:Config_inst_add_saml.png]]
 
*[[File:Config_inst_saml2.png]]
 
  
 
[[Category:plugins]][[Category:Authentication Plugins]]
 
[[Category:plugins]][[Category:Authentication Plugins]]

Latest revision as of 11:53, 15 May 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 correct SSPHP files are present

If you are installing/using Mahara via git you will need to install the ssphp module via running the command in the parent to the htdocs directory (where the Makefile file lives)

make cleanssphp && make ssphp

This should remove any older version and install the latest version, via composer, for the Mahara version you are using

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

To customise your SAML IdP Metadata

If you site has more than one Identity Provider being used then when a user tries logging into the site via the SSO button they are taken to a 'Identity Provider discovery' page to choose which IdP they should login with.

If the metadata supplied by the IdP is containing the values for

  • OrganizationName
  • OrganizationDisplayName
  • Logo

then these will be used on the discovery page.

If your IdP's metadata doesn't supply them - please ask if they can update things at their end and supply updated metadata.xml file. This will be the best option especially if you are using the metadata refresh url!

If they can't (or won't) then you can add in the changes manually. To do this

1) Log in as site admin and edit an institution that is using the SAML metadata

2) Edit the SAML auth instance

3) In the 'Institution Identity Provider SAML metadata' field make the following changes

a) If you want a logo image Inside the metadata.xml file:

Place just before </IDPSSODescriptor> line

   <Extensions>
     <mdui:UIInfo xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">
       <mdui:Logo width="120" height="30" xml:lang="en">[URL to logo]</mdui:Logo>
     </mdui:UIInfo>
   </Extensions>

And update the [URL to logo] to point to a logo for the IdP reachable via the Internet, eg https://mahara.org/theme/mahara-org/images/site-logo.svg and alter height / width values if needed - a 120 x 30px png / svg image works best

b) To set the provider details

Place just after </IDPSSODescriptor> line

 <Organization>
   <OrganizationName xml:lang="en">[Provider name]</OrganizationName>
   <OrganizationDisplayName xml:lang="en">[Identity provider name]</OrganizationDisplayName>
 </Organization>

- Change [Provider name] to the name of the organization the IdP belongs to, eg Mahara.org

- Change [Identity Provider name] to the name of the IdP system, eg Mahara Single Sign On

Note Depending on the way your IdP structures it's metadata you may need to prefix the new Extensions and Organization* lines with same prefix as in the </IDPSSODescriptor> line, eg if that line looks like </md:IDPSSODescriptor> then you will need to add 'md:' to the lines that don't start it