Configuring ONLYOFFICE SP and Shibboleth IdP

Control Panel v3.5 ONLYOFFICE Control Panel changelog

Introduction

Single Sign-on (SSO) is a technology that allows users to sign in only once and then get access to multiple applications/services without re-authentication.

SSO is always ensured by the joint operation of two applications: an Identity Provider and a Service Provider (hereinafter referred to as "IdP" and "SP"). ONLYOFFICE SSO implements the SP only. A lot of different providers can act as an IdP, but this article considers the Shibboleth implementation.

Preparing ONLYOFFICE Workspace for the SSO setup

1. Install ONLYOFFICE Workspace v. 11.0.0 for Docker or any later version with the SSO support.
2. Add a domain name, e.g., myportal-address.com.
3. On your portal, go to the Control Panel -> HTTPS, create and apply the letsencrypt certificate for the traffic encryption (to enable HTTPS on your portal).

Creating Shibboleth IdP

Requirements

• To deploy Shibboleth IDP, a clean CentOS 7 host machine is required.
• Time must be set correctly and the time synchronization service must be installed on the host machine for IDP:

  timedatectl  status
  yum install ntp
  systemctl enable ntpd.service
  ntpdate time.apple.com

• The unzip package must be installed on the machine:

  yum install unzip

• Docker and Docker Compose must be installed on the machine.
• A domain name must be associated with the machine (for example, your-idp-domain.com)

Creating Shibboleth IdP

To create, configure and start Shibboleth IDP, download and execute the install.sh script.

Here's what the script does:

• downloads docker files for creating Shibboleth Idp images and containers from github,
• changes the default idptestbed.edu domain in the configuration files to the domain specified when executing the script,
• adds access via the SAML protocol for the specified ONLYOFFICE SP domain,
• specifies which attributes are required for ONLYOFFICE SP to issue information about users from Shibboleth IDP (the Attribute Mapping setting),
• creates and configures LDAP and creates users for issuing,
• enables dynamic loading of metadata from ONLYOFFICE SP to Shibboleth IDP,
• enables Shibboleth SLO, if necessary.

1. Download the install.sh script:

   curl -L https://bit.ly/3fwo5e6 -o install.sh

2. Make the script executable:

   chmod +x install.sh

3. Execute the script replacing parameters with your own ones:

   ./install.sh -id your-idp-domain.com -sd myportal-address.com --no_slo

   Script parameters:

   • -id - a domain name of the current machine for Shibboleth IDP.
   • -sd - a domain name where ONLYOFFICE SP is deployed.
   • --no_slo - disables Single Logout in Shibboleth IDP (optional parameter).
4. Wait when Shibboleth IDP starts after executing the script.
5. To verify that Shibboleth IDP started correctly, open the https://your-idp-domain.com/idp/shibboleth link in your browser. An xml file should be displayed.
6. Copy the https://{your_idp_domain}/idp/shibboleth link (e.g., https://your-idp-domain.com/idp/shibboleth) and go to the ONLYOFFICE portal signing in as an administrator. Open the Control Panel -> SSO page.

Configuring ONLYOFFICE SP

1. Make sure that you are signed in as an Administrator to your ONLYOFFICE Control Panel and click the SSO tab in the PORTAL SETTINGS section on the left sidebar.
   You can only register one enterprise Identity Provider for your organization on the ONLYOFFICE portal.
   
2. Enable SSO using the Enable Single Sign-on Authentication switcher and paste the link to the Shibboleth IdP into the URL to Idp Metadata XML field.
   
3. Press the button with the upward arrow to load the IdP metadata. The ONLYOFFICE SP Settings form will be automatically filled in with your data from the Shibboleth IdP.

   As we disabled SLO when executing the install.sh script by specifying the --no_slo parameter, the IdP Single Logout Endpoint URL field will be empty.

4. Once the IdP metadata is loaded, two certificates will be added in the IdP Public certificates section. You'll also see the pop-up window with the following text: 'Multiple Idp verification certificates are not supported. Please leave only Primary certificate'.

   You need to delete the second certificate in the list and leave the first certificate only, which is the primary certificate. Use the Delete link next to the second certificate to remove it. If you do not remove the certificate, you'll not be able to save the settings.

5. In the Custom login button caption field, you can enter any text instead of the default one (Single Sign-on). This text will be displayed on the button used to login to the portal with the Single Sign-on service at the ONLYOFFICE authentication page.
   
6. Now you need to create self-signed certificates or add any other certificates in the SP Certificates section.
   Important!In the Use for list, choose the signing and encrypt option as your Shibboleth IdP is automatically configured with the install.sh script to verify that data is digitally signed and encrypted.
   

   You should get nearly the same result:

   
7. In the Attribute Mapping section, set the correspondence of the fields in the ONLYOFFICE People module to the user attributes which will be returned from the Shibboleth IdP.

   First Name	urn:oid:2.5.4.42
   Last Name	urn:oid:2.5.4.4
   Email	urn:oid:0.9.2342.19200300.100.1.3
   Location	urn:oid:2.5.4.7
   Title	urn:oid:2.5.4.12
   Phone	urn:oid:0.9.2342.19200300.100.1.41

   

   In the Advanced Settings section, you can check the Hide auth page option to hide the default authentication page and automatically redirect to the SSO service.

   ImportantIf you need to restore the default authentication page (to be able to access the portal if you your IDP server fails), you can add the /Auth.aspx?skipssoredirect=true key after the domain name of your portal in the browser address bar.
8. Click the Save button.
9. The ONLYOFFICE SP Metadata section should be opened.
10. Verify that our settings are publicly available by clicking the Download SP Metadata XML button. The XML file contents should be displayed.
    

    This xml file is usually used to configure Shibboleth IDP, but because the install.sh script enables DynamicHTTPMetadataProvider, we do not need to do that (Shibboleth IDP will download this xml file at the first request for the login).

Checking the work of the ONLYOFFICE SP with the Shibboleth IdP

The install.sh script created 4 users which can be used for testing the work of the ONLYOFFICE SP with the Shibboleth IdP.

Email	Username	Password	Comment
student1@{your_idp_domain}	student1	password	Standard
student2@{your_idp_domain}	student2	password	Without givenName
student3@{your_idp_domain}	student3	password	With umlauts
staff1@{your_idp_domain}	staff1	password	Obligatory fields only

Logging in to ONLYOFFICE on the SP side

1. Go to the ONLYOFFICE Authentication page (e.g., https://myportal-address.com/Auth.aspx).
2. Click the Single sign-on button (the caption may differ if you have specified your own text when configuring ONLYOFFICE SP). If the button is missing, this means that SSO is not enabled.
   
3. If all the SP and IdP parameters are set correctly, we will be redirected to the Shibboleth IdP login form:
   
4. Enter the username and password of the Shibboleth IdP account (username: student1, password: password) and check the Don't Remember Login box.
5. If the credentials are correct, a new window opens. Allow the provision of information to the service by clicking the Accept button.
   
6. If everything is correct, we will be redirected to the main page of the portal (the user will be created automatically if missing, or the data will be updated if changed in the IDP).
   

Profiles for users added with SSO authentication

The possibility to edit user profiles created using the SSO authentication is restricted. The user profile fields received from the IdP are disabled for editing (i.e. First Name, Last Name, Email, Title and Location). You can edit these fields from your IdP account only.

The figure below shows the Actions menu for an SSO user:

The following figure shows an SSO user profile opened for editing:

The users created using the SSO authentication are marked with the SSO icon in the user list for the portal administrators:

To log out from the Shibboleth IdP (if you have not checked the Don't Remember Login box when logging in), go to the link that looks like this: https://{shibboleth-idp-domain}/idp/profile/Logout