Enabling Single Sign-on for SaaS version

Introduction

If your SaaS service plan includes this feature, the Single Sign-on section allows you to enable third-party authentication using SAML, thereby providing a quicker, simpler, and more secure way to access the portal for users.

Generally, the Single Sign-on technology allows users to sign in only once and then get access to multiple applications/services without re-authentication. For example, if a web portal includes several large independent sections (forum, chat, blogs, etc.), a user can undergo the authentication procedure within one of the services and automatically get access to all other services without entering credentials several times.

Registering your Identity Provider in the ONLYOFFICE Service Provider

An Identity Provider (IdP) is a service that creates, maintains, and manages user identity information and provides user authentication to other Service Providers within a federation. Services such as OneLogin, AD FS, etc. act as Identity Providers. A Service Provider (SP) is an entity that provides web services and relies on a trusted Identity Provider for user authentication. In this case, the Service Provider is ONLYOFFICE.

SSO can be enabled using SAML for the exchange of authentication and authorisation data between an Identity Provider and a Service Provider:

SAML (Security Assertion Markup Language) - an XML standard that allows the transmission of user authentication/authorization data between an identity provider and a service provider through security tokens that contain assertions.

Enhanced security is enabled by the fact that ONLYOFFICE does not store user passwords; it uses the results of the authentication on the Identity Provider side instead. All required user information is transmitted via an authentication token. If the user information changes on the Identity Provider side, it will be automatically updated on the portal during the next SSO authentication (note that the data can only be synchronized in one direction: from the Identity Provider to ONLYOFFICE Workspace).

After the Identity Provider and the ONLYOFFICE Workspace are mutually configured to ensure SSO, the user SSO authentication process will be performed on the Identity Provider side. The ONLYOFFICE Workspace will receive an authentication token (SAML) from the Identity Provider. After the token is validated (by using digital signatures and the token lifetime), the ONLYOFFICE Workspace allows the user to access the portal.

Enabling SSO

To enable and configure SSO authentication for your portal, proceed as follows:

Verify the Identity Provider configuration before adjusting the Service Provider.

Click the icon in the upper-right corner to open Settings.
In the Integration section of the left sidebar, click Single Sign-on.
Enable the Enable Single Sign-on Authentication toggle under the Single Sign-on caption.
Complete the required fields in the ONLYOFFICE SP Settings section. The necessary information can be specified in several different ways:
- Enter the URL address to the metadata file. If your IdP metadata is accessible from outside by the link, enter the link into the URL to IdP Metadata XML field and click the arrow button to load the data. When the data is loaded, all the required parameters will be automatically displayed in the extended form.
- Upload the metadata file. If your IdP provides a metadata file, click Select file to browse for the file on your computer. When the file is uploaded, all the required parameters will be automatically displayed in the extended form.
- Specify the required parameters manually. If the metadata file is not available, enter the necessary parameters manually. To obtain the required values, contact your IdP administrator.

The following parameters are available:

IdP Entity Id (mandatory field) - the Identity Provider identifier or URL address that will be used by the Service Provider to unequivocally identify the IdP.
E.g., https://example.com/idp/shibboleth

where example.com is your SSO service domain name.
IdP Single Sign-On Endpoint URL (mandatory field) - the URL used for the single sign-on on the Identity Provider side. It is the endpoint address in your IdP to which SP sends authentication requests.
Set the Binding type by selecting one of the corresponding radio buttons. Bindings specify the way in which authentication requests and responses are transmitted between the IdP and SP over the underlying transport protocol: using the HTTP POST or HTTP Redirect binding.
IdP Single Logout Endpoint URL - the URL used for the single logout on the Service provider side. It is the endpoint address in your IdP to which SP sends logout requests/responses.
Set the Binding type selecting one of the corresponding radio buttons. Bindings specify the way in which logout requests and responses are transmitted between the IdP and SP over the underlying transport protocol: using the HTTP POST or HTTP Redirect binding.
NameId Format - the NameID parameter allows SP to identify a user. Select one of the available formats from the list.

It is possible to customize the button used to sign in to the portal with the Single Sign-on service at the ONLYOFFICE authentication page. You can do it using the Custom login button caption field in the ONLYOFFICE SP Settings section.

You can also add the IdP and SP certificates.

IdP Public Certificates

IdP Public Certificates - this section allows you to add the Identity Provider public certificates used by the SP to verify the requests and responses from the IdP.

If you have loaded the IdP metadata, these certificates will be added to your portal automatically. Otherwise, the certificates can be found in your IdP account. To add a certificate manually, click the Add certificate button. The New Certificate window opens. Enter the certificate in the Public Certificate field and click the OK button.

Set additional parameters for certificates by selecting the corresponding checkboxes.

Specify which signatures of requests/responses sent from IdP to SP should be verified:

Verify Auth Responses Sign - to verify signatures of the SAML authentication responses sent to SP.
Verify Logout Requests Sign - to verify signatures of the SAML logout requests sent to SP.
Verify Logout Responses Sign - to verify signatures of the SAML logout responses sent to SP.

Select the appropriate algorithm from the Default Sign Verifying Algorithm list: rsa-sha1, rsa-sha256 or rsa-sha512.

Default settings are used only in cases where the IdP metadata does not specify which algorithm should be used.

Added certificates can be edited or deleted using the corresponding link.

SP Certificates

SP Certificates - this section allows you to add the Service Provider certificates used to sign and encrypt the requests and responses from the SP.

If your IdP requires that input data be signed and/or encrypted, create or add corresponding certificates in this section.

Click the Add certificate button. The New Certificate window opens. You can generate a self-signed certificate or add an existing certificate in the Public Certificate field and the corresponding private key in the Private Key field. In the Use for list, select one of the available options: signing, encrypt, signing and encrypt. When ready, click the OK button.

Depending on the certificate purpose selected in the Use for list when uploading/generating the certificate, the certificate additional parameters are specified. The following parameters define which requests/responses sent from SP to IdP should be signed:

Sign Auth Requests - to have SP sign the SAML authentication requests sent to IdP.
Sign Logout Requests - to have SP sign the SAML logout requests sent to IdP.
Sign Logout Responses - to have SP sign the SAML logout responses sent to IdP.

If you have selected the encrypt or signing and encrypt option in the Use for list, the Decrypt Assertions parameter is also checked. The decryption is performed using the corresponding Private Key.

Select the necessary algorithms from the lists:

Signing Algorithm: rsa-sha1, rsa-sha256 or rsa-sha512.
Default Decrypt Algorithm: aes128-cbc, aes256-cbc or tripledes-cbc.

You can edit or delete the added certificates using the corresponding link.

Attribute Mapping

Attribute Mapping - this section allows you to map the fields in the ONLYOFFICE People module to the user attributes that will be returned from the IdP. When a user signs in to the ONLYOFFICE SP using the SSO credentials, ONLYOFFICE SP receives the required attributes and populates the full name and email address fields in the user account with the values received from the IdP. If the user does not exist in the People module, it will be created automatically. If the user information has been changed on the IdP side, it will be updated in SP as well.

The available attributes are:

First Name (mandatory field) - an attribute in a user record that corresponds to the user's first name.
Last Name (mandatory field) - an attribute in a user record that corresponds to the user's second name.
Email (mandatory field) - an attribute in a user record that corresponds to the user's email address.
Location - an attribute in a user record that corresponds to the user's location.
Title - an attribute in a user record that corresponds to the user's title.
Phone - an attribute in a user record that corresponds to the user's phone number.

Advanced Settings

The Hide auth page option allows you to hide the default authentication page and automatically redirect to the SSO service.

Important If 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.

Once all settings have been configured, click Save. The ONLYOFFICE SP Metadata section will open.

Registering ONLYOFFICE as a trusted Service Provider in your Identity Provider

Add ONLYOFFICE as a trusted Service Provider in your IdP account by specifying the ONLYOFFICE SP metadata in the IdP.

To receive the required data, refer to the ONLYOFFICE SP Metadata section of the SSO page. Verify that the SP data is publicly accessible. To do that, click Download SP Metadata XML. The XML file contents will be displayed in a new browser tab. Save the data as an XML file to be able to upload it to the IdP.

Alternatively, individual parameters can be copied manually by clicking Copy to clipboard in the corresponding fields.

The following parameters are available:

SP Entity ID (link to metadata XML) - the Service Provider XML URL address, which can be downloaded and used by the Identity Provider to unequivocally identify the SP. By default, the file is located at the following address: http://example.com/sso/metadata, where example.com is your ONLYOFFICE portal domain name or public IP.
SP Assertion Consumer URL (supports POST and Redirect binding) - the Service Provider URL address where it receives and processes assertions from the Identity Provider. By default, the following address is used: http://example.com/sso/acs, where example.com is your ONLYOFFICE portal domain name or public IP.
SP Single Logout URL (supports POST and Redirect binding) - the URL used for the single logout on the Identity Provider side. It is the endpoint address in your SP where it receives and processes logout requests/responses from the Identity Provider. By default, the following address is used: http://example.com/sso/slo/callback where example.com is your ONLYOFFICE portal domain name or public IP.

These parameters and XML contents differ depending on your portal configuration, e.g., if you switch your portal to HTTPS or specify a domain name, the parameters will also be changed, and you will need to reconfigure your IdP.

Logging in to the ONLYOFFICE SP

Once SSO is enabled and configured, the sign-in in process proceeds as follows:

A user requests access to ONLYOFFICE by clicking the Single Sign-on button (the caption may differ if you have specified your own text when configuring ONLYOFFICE SP) at the ONLYOFFICE portal Authentication page (SP-initiated SSO).
If all IdP and SP settings are configured correctly, ONLYOFFICE sends the authentication request to the IdP and redirects the user to the IdP page where credentials are requested..
If the user is not already signed in to the IdP, the user provides credentials on the IdP side.
IdP creates the authentication response that contains user data and sends it to ONLYOFFICE.
ONLYOFFICE receives the authentication response from the Identity Provider and validates it.
If the response is validated, ONLYOFFICE grants the user access to the portal. The user account will be created automatically if it does not yet exist, or updated if any data has changed in the IdP.

It is also possible to use the sign-in page on the Identity Provider side (IdP-initiated SSO), enter credentials, and then access the ONLYOFFICE portal without re-authentication.

Logging out from the ONLYOFFICE SP

Logout can be performed in two ways:

From the ONLYOFFICE portal using the Sign Out menu (in this case, a logout request will be sent to the IdP). The user should also be automatically signed out from the IdP when signed out from all other applications previously accessed via SSO.
From the IdP logout page.

Editing user profiles created using SSO

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

Editing such user profiles in the People module is restricted. "User profile fields populated via SSO authentication cannot be edited from the People module. User data can only be modified on the IdP side.