This wiki page explains how SimpleSAML PHP can be used to enable federated login for the VidyoPortal video conferencing system. Since version 3.0, Vidyo has enabled support for SAML in the VidyoPortal. They do however not rely on existing SAML middleware (such as Shibboleth or SimpleSAMLphp) but they manage SAML directly, which has some drawbackes when it comes to IdP discovery and metadata handling in case users of hundreds of IdPs should be allowed to log in via SAML.
At the time of writing, SAML is supported for a single tenant, ie. one single Identity Provider can be configured in VidyoPortal. This means that in order to make Vidyo as a federated service, a SAML gateway should be configured to provide access for institutional users. In this guide, SimpleSAMLphp will be used as a gateway.
Even though this guide focuses on how to enable SAML login from many IdPs for Vidyo, it can also serve as an example for other applications that "support SAML" but only on a small scale with one IdP at once.
To deploy the SAML proxy, we recommend to use the popular SimpleSAMLphp SAML implementation, which is quite versatile and is frequently used in academic identity federations. The installation of SimpleSAMLphp software is covered in its documentation.
You will need to configure SSP both as an IdP (in the direction of VidyoPortal) and an SP (for the federation). Contrary to what is stated in section 9.1 of the SimpleSAMLphp IdP documentation, both IdP and SP should share the same hostname / virtual host.
Configure the IdP part
Your proxy will be an IdP from the point of view of the VidyoPortal. The IdP will use the SP part for authentication, thus you can login to the proxy by the federation.
Enable SAML2 IdP functionality in
Generate a key and a long-living self-signed certificate for the IdP and place it in the
cert directory as
metadata/saml20-idp-hosted.php as the following:
It is recommended to configure VidyoPortal by using friendly attribute names (you don't want to write OIDs), therefore use the built-in
oid2nameAttributeMap for the transformation of attribute names.
Retrieve VidyoPortal metadata from the portal administration interface and save it as
metadata/vidyo-sp.xml. It needs to be referenced from
Configure VidyoPortal to use SAML
In the portal the following should be set:
- Authentication Type: SAML
- IdP Metadata XML: you can retrieve it from https://path.to.simplesaml.tld/saml2/idp/metadata.php
- SAML Provision type: SAML (automatic provisioning)
Set Vidyo user parameters
Click on Edit IdP Attribute Mapping... for mapping the IdP attributes to Vidyo user parameters
The interface is pretty self-explanatory. You can edit which SAML IdP attributes can be mapped to certain Vidyo parameters.
Be aware that some fields have arbitrarily limited lengths, e.g. the user name is limited by Vidyo to 40 characters. If you map an attribute there whose values for a particular user are longer, than the user will receive misleading error messages ("No AuthenticationProvider found for org.springframework.security.saml.SAMLAuthenticationToken") after successful authentication to your SimpleSAMLphp proxy.
For some attributes it is possible to define value mapping as well. It might be useful for group and type information. You can define static string matches here.
Configure the SP part
In the IdP configuration, you have referenced an authsource called default-sp. If you configure a SimpleSAMLphp SP with this identifier, the IdP settings above will direct your users to their home IdP.
For SP configuration, please follow your federation's guides or use SimpleSAMLphp documentation as a reference. Basically you will need to perform the following:
- generate a key and a certificate for the proxy (SP) and configure SSP to use them;
- register the proxy in your federation:
- you will need to use the SP certificate here;
- your attribute requirements depend on what attributes you have configured in Vidyo previously;
- configure the SP to refresh federation (or eduGAIN) metadata regularly by using metarefresh
First, you need to enable the consent module by creating an empty file in the module directory:
We store the consent information in a database, so that the same user can come with different browsers / machines and his consent will still be recognized if he gave it once. To do that, you need to include the following in your authproc.idp array:
dbname, dbuser and dbuserpassword needs to be adapted to your environment.
In a multi-language environment, the LanguageAdaptor module should be configured in order to display the terms-of-use in the correct language for each user and to store the language information:
The next step is to disable the display of the attribute table on the consent dialogue. For this, you can just comment out lines 97 and 99 of
modules/consent/www/getconsent.php, so that the section looks like this:
In order to change the displayed text, you need to go to the dictionaries folder of the consent module.
consent.definition.json contains the English texts, while
The last step is to limit the languages proposed by SimpleSAMLphp to the relevant ones for your environment. In Switzerland the section of the
config.php looks like the following:
The following image gives an example of the final result (after theming SSP for SWITCH).
In order to have SimpleSAMLphp come in your local look and feel, you can create a theme and exchange logos, favicons, colors, etc. This is documented here.
Vidyo does not support fine-grained authorization of authenticated users. You can use the Authorize module of SimpleSAMLphp. The documentation can be found here.
The authors of this text used the following workarounds to make Vidyo as a production federated service in 2016q1. It is possible that future versions will make the workarounds unnecessary.
Vidyo cannot handle multi-valued attributes. It just takes the first value and ignores the rest. For statistical purposes, SWITCH uses the eduPersonScopedAffiliation mapped to the description field of the user in the Vidyo portal. In order to stay consistent, they build an Authentication Processing Filter that modifies all multi-valued attributes into a single semicolon-seperated string attribute value. The code for this is as follows:
It is configured in config.php with the following line:
Extension number provisioning
Unfortunately the extension numbers provisioned by Vidyo on first login has variable length (4 or 5 digits). This makes dialplans and services like NRENUM hard to deploy. If you need to assign extension numbers from a fixed range, you have to implement custom extension number provisioning, and pass on the extension number from the proxy to Vidyo.
NIIF has implemented an extension number provisioning module that gets a federated identifier as an argument and returns either the previous number assigned to that ID or a fresh extension number, or an error signal. (One possible error is that the number range is exhausted. Therefore the code must be protected from unauthorized access to avoid DoS.)
The provisioning module is hooked into the SimpleSAMLphp proxy by using the more generic attribute from REST API module.