Configuring ONLYOFFICE SP and OneLogin IdP

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 facilitated 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. Many different providers can act as an IdP, but this article considers the OneLogin 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 Control Panel > HTTPS, create and apply the letsencrypt certificate for the traffic encryption (to enable HTTPS on your portal).

Creating an IdP in OneLogin

1. Sign up for OneLogin if you have not yet registered.
2. Sign in to OneLogin as an administrator.
3. Go to the Administration section.
4. Click the Applications menu. Click the Add App button.
   
5. In the Find Application search field, type in the following text: SAML Custom Connector (Advanced):
   
6. Select the found option.
7. In the window that opens, enter a Display Name, for example, IDP OneLogin Onlyoffice v11 Test - to distinguish this application from others. Optionally, replace the default icons with your own and click Save.
   
8. Go to the Configuration submenu and complete the fields according to the table below:
   Please specify your own domain name or public IP where your ONLYOFFICE SP is hosted instead of myportal-address.com.
   

   Application Details
   RelayState	https://myportal-address.com
   Audience (EntityID)	https://myportal-address.com/sso/
   Recipient	https://myportal-address.com/sso/acs
   ACS (Consumer) URL Validator*	^https:\/\/myportal-address\.com\/sso\/acs\/$
   ACS (Consumer) URL*	https://myportal-address.com/sso/acs
   Single Logout URL	https://myportal-address.com/sso/slo/callback
   SAML initiator	Service Provider
   SAML nameID format	Email
   SAML issuer type	Specific
   SAML signature element	Assertion
   Encrypt assertion	(check this box)
   SAML encryption method	AES-128-CBC
   Sign SLO Request	(check this box)
   Sign SLO Response	(check this box)

   
9. Click the Save button and go to the Parameters submenu.
   
10. Use the + button to create 5 parameters (givenName, sn, mail, title, mobile). Select the Include in SAML assertion option and specify a value from the Value list, appropriate for the field catalogue of the LDAP directory, for all of them:
    
11. all fields for SAML assertion attributes have been completed in the IdP, the result should be similar to the following. Click the Save button.
    
12. Go to the SSO submenu. Select a valid certificate from the list by clicking Change, if you have more than one certificate. In the SAML Signature Algorithm field, leave the SHA-1 option and click the Save button:
    
13. Copy the link from the Issuer URL field (e.g., https://app.onelogin.com/saml/metadata/4d87973f-629d-4a52-812e-bde45eff92b8) and go to the ONLYOFFICE portal, signing in as an administrator. Open the Control Panel -> SSO page.

Configuring ONLYOFFICE SP

1. Ensure 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 by clicking Enable Single Sign-on Authentication toggle and paste the link copied from the OneLogin issuer URL into the URL to Idp Metadata XML field.
   

   Click the upload button to load the IdP metadata. OneLogin IdP will automatically populate the ONLYOFFICE SP Settings form fields.

3. 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 sign in to the portal with the Single Sign-on service at the ONLYOFFICE authentication page.
   
4. Now you need to create a certificate in the SP Certificates section. To do that, click the Add certificate button in the corresponding section.
   
5. In the opened modal window, click the Generate New Self-Signed Certificate link, and choose the signing and encrypt option in the Use for list. Before you save the certificate, copy the Public Certificate text to the clipboard (it is needed for OneLogin), then click OK.
   
6. You should get nearly the same result:
   
7. It is not necessary to adjust the Attribute Mapping form since we specified the same parameters when creating OneLogin IdP. The following values are used:

   First Name	givenName
   Last Name	sn
   Email	mail
   Location	l
   Title	title
   Phone	mobile

   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 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. The ONLYOFFICE SP Metadata section should be opened. Verify that our settings are publicly available by clicking the Download SP Metadata XML button. The XML file contents should be displayed.
9. Return to OneLogin, open your application, and go to the Configuration tab. Scroll down the page - the SAML Encryption field should appear. Paste the copied Public Certificate text from step 4 of this instruction into this field and click the Save button:
   

Creating users in OneLogin and giving them access to ONLYOFFICE

To create users in OneLogin and grant them access to the ONLYOFFICE SP, perform the following steps:

1. go to the OneLogin All Users page, signing in as an administrator,
   
2. create a new user or edit an existing one,
3. go to the Applications submenu and click the + button,
4. select the newly created application from the list and click CONTINUE,
   
5. in a new window that opens, add the missing data and click the SAVE button,
   
6. now the user is able to work in ONLYOFFICE SP.

Verifying the ONLYOFFICE SP configuration with the OneLogin IdP

Signing 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 SP and IdP parameters are configured correctly, you will be redirected to the OneLogin IdP login form:
   
4. Enter the login and password of the user who has been granted access to the ONLYOFFICE SP and click the LOG IN button.
5. If the credentials are correct, you will be redirected to the portal home page. The user account will be created automatically if it does not yet exist, or updated if any data has changed in the IdP.
   

Logging out from ONLYOFFICE SP

1. An SSO user can log out from the ONLYOFFICE portal using the Sign Out menu. The user should also be automatically signed out from the OneLogin IdP if they have signed out from all other OneLogin applications to which they have been granted access.
   
2. If you signed out successfully, you will be redirected to the portal authentication page.
   
3. If you click the Single Sign-on button once again, you will be redirected to the OneLogin login page, confirming that you have successfully signed out from the portal:
   

Profiles for users added with SSO authentication

Editing user profiles created via SSO authentication is restricted. The user profile fields received from the IdP cannot be edited (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: