admin/institutions: New SAML affiliation data

New in Mahara 22.04: You can pass in additional
email addresses and roles for different institutions
if you use SAML (Bug #1953411).

source/administration/institutions.rst

@@ -612,6 +612,7 @@ Choose this authentication method for your institution when you have a SAML 2.0
       ``<md:Extensions> <mdui:UIInfo xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui"> <mdui:Logo width="120" height="30" xml:lang="en">linktothelogo</mdui:Logo> </mdui:UIInfo> </md:Extensions>``
 
 #. **Metadata URL for auto-refresh**: :index:`Instead <single: SAML; Auto refresh of SAML metadata>` of adding the metadata directly, you can provide the URL to the metadata, which needs to be in XML format, so that changes to it are pulled automatically via cron. You would not have to update the metadata yourself when it changes.
+#. **Metadata validate signature**: If a valid URL is provided in the 'Metadata URL for auto-refresh' field, you can specify the fingerprint of the certificate used to sign the metadata. You don't need this option if you don't want to validate the signature on the metadata.
 #. **Institution Identity Provider SAML metadata**: :index:`Enter <single: SAML; Add SAML IdP metadata directly in Mahara>` the metadata from your IdP. Make sure that all information in the :ref:`SAML plugin configuration <plugin_saml>` is correct and that there are no server dependencies missing.
 
    .. note::
@@ -648,9 +649,39 @@ Choose this authentication method for your institution when you have a SAML 2.0
 #. **SSO field for avatar icon**: If the IdP contains base64-encoded images for a profile picture, you can enter it here.
 #. **SSO field for roles**: Enter the name of the attribute here that passes in role information.
 #. **SSO field for role prefix**: If the IdP passes in role information for the person logging in, then you can set this 'prefix' field so that only those roles starting with the prefix should be handled by Mahara. This way the IdP can have different roles for different Service Providers (SP). If the person does not have any roles relating to this prefix, they will not be allowed to log in.
+#. |new in Mahara 22.04| **SSO field for affiliation IDs**: :index:`If <single: New in Mahara 22.04; SAML - add affiliation information>` you set this value, the username is checked and then any affiliated IDs until one is found that already exists in the system. If none are found, the username of the main identity is used as username for external authentication (remote username).
+
+   .. note::
+      The IdP can pass in affiliation information for account holders. This is useful if you multiple organisations are in your IdP.
+
+      This field works in conjunction with
+
+      * SSO field for affiliation emails
+      * SSO field for affiliation roles
+      * SSO field for affiliation role delimiter
+
+      If you set these role mapping fields, the account holder will be granted the associated roles in the institutions indicated in the affiliation roles array that are passed in.
+
+#. |new in Mahara 22.04| **SSO field for affiliation emails**: If you set this value, Mahara will check which affiliation role is the highest and set the associated email to be the primary email address when the account holder logs in. If you leave this field blank, the value in 'SSO field for email' will be used instead.
+#. |new in Mahara 22.04| **SSO field for affiliation roles**: If you set this, the 'Role delimiter character', and the required 'Role mapping' fields, the person will be granted the associated roles in the institutions indicated in the affiliation roles array passed in.
+
+   .. note::
+      For example, if the role associations passed in are 'staffmember@institution_a' and 'administrator@institution_b' and the role mapping for 'Institution staff' is 'staffmember' and for 'Institution administrator' is 'administrator', then the person will be an institution staff member in institution_a and an institution administrator in institution_b.
+
+#. |new in Mahara 22.04| **Role delimiter character**: Enter the delimiter value that is used to split the string into the role and the institution components.
+
+   .. note::
+      For example, if the delimiter is '@', it will split 'staffmember@institute_a' into role = staffmember, institution = institute_a.
+
+      That means, if the role associations passed in from the IdP are 'staffmember@institute_a' and 'administrator@institute_b', the following role mappings are made:
+
+      * staffmember@institution_a: Institution staff in institution 'institution_a'
+      * administrator@institution_b: Institution administrator in institution 'institution_b'
+
 #. **Role mapping for 'Site administrator'**: Enter the name of the role that is assigned to people in the IdP who shall have site administrator permissions.
 #. **Role mapping for 'Site staff'**: Enter the name of the role that is assigned to people in the IdP who shall have site staff permissions.
 #. **Role mapping for 'Institution administrator'**: Enter the name of the role that is assigned to people in the IdP who shall have institution administrator permissions.
+#. **Role mapping for 'Institution support administrator'**: Enter the name of the role that is assigned to people in the IdP who shall have institution support administrator permissions.
 #. **Role mapping for 'institution staff'**: Enter the name of the role that is assigned to people in the IdP who shall have institution staff permissions.
 
    .. note::