helpcenter/Web/Controls/Help/Server/ControlPanel/ConfigureShibboleth/ConfigureShibboleth.ascx

276 lines
24 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<%@ Control Language="C#" Inherits="BaseContentUserControls" %>
<%@ Register Namespace="TeamLab.Controls" Assembly="__Code" TagPrefix="cc" %>
<script runat="server">
protected override void Init()
{
PageTitle = PageCaption = "Configuring ONLYOFFICE SP and Shibboleth IdP";
MetaKeyWords = "Control Panel, SSO, Single sign-on, Shibboleth";
MetaDescription = "Learn how to configure ONLYOFFICE SP and Shibboleth IdP.";
}
</script>
<div class="main_buscall_container dataBackup">
<div class="MainHelpCenter">
<h1 class="subHeaderFeaturesCaption TipsCaption">Configuring ONLYOFFICE SP and Shibboleth IdP</h1>
<cc:LocalizeContent runat="Server" ControlName="~/Controls/Help/VariousControls/Versions/ControlPanel/ControlPanel_Current.ascx" />
<div class="keyword_block">
<ul>
<li><cc:LocalizeContent runat="Server" ControlName="~/Controls/Help/Tags/server-version/server-version.ascx" /></li>
<li><cc:LocalizeContent runat="Server" ControlName="~/Controls/Help/Tags/local-server/local-server.ascx" /></li>
<%--<li>
<span class="enterprise_display">
<cc:LocalizeContent runat="Server" ControlName="~/Controls/Help/Tags/enterprise-edition/enterprise-edition.ascx" />
</span>
</li>--%>
<li><cc:LocalizeContent runat="Server" ControlName="~/Controls/Help/Tags/control-panel/control-panel.ascx" /></li>
<li><cc:LocalizeContent runat="Server" ControlName="~/Controls/Help/Tags/sso/sso.ascx" /></li>
<li><cc:LocalizeContent runat="Server" ControlName="~/Controls/Help/Tags/shibboleth/shibboleth.ascx" /></li>
</ul>
</div>
<h2 id="Introduction">Introduction</h2>
<p><b>Single Sign-on</b> (SSO) is a technology that allows users to sign in only once and then get access to multiple applications/services without re-authentication.</p>
<div class="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.</div>
<p>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"). <b>ONLYOFFICE SSO</b> implements the <b>SP only</b>. A lot of different providers can act as an IdP, but this article considers the <a target="_blank" href="https://www.shibboleth.net/">Shibboleth implementation</a>.</p>
<div class="notehelp enterprise_display">If you want to use SSO when connecting <b>ONLYOFFICE Desktop Editors</b> to your <b><%= ((BasePage)Page).EditionVersion %></b>, disable <b>Private Rooms</b> in the <b>Control Panel</b>.</div>
<h2 id="Prepare">Preparing <%= ((BasePage)Page).EditionVersion %> for the SSO setup</h2>
<ol>
<li>Install <%= ((BasePage)Page).EditionVersion %> <b>v. 11.0.0</b> for Docker or any later version with the SSO support.</li>
<li>Add a domain name, e.g., <span class="param-type">myportal-address.com</span>.</li>
<li>On your portal, go to the <b>Control Panel</b> -> <b>HTTPS</b>, create and apply the <a target="_blank" href="https://letsencrypt.org/">letsencrypt</a> certificate for the traffic encryption (to enable HTTPS on your portal).</li>
</ol>
<h2 id="CreateIdP">Creating Shibboleth IdP</h2>
<h5>Requirements</h5>
<ul>
<li>To deploy Shibboleth IDP, a clean CentOS 7 host machine is required.</li>
<li>Time must be set correctly and the time synchronization service must be installed on the host machine for IDP:
<pre><code>timedatectl status
yum install ntp
systemctl enable ntpd.service
ntpdate time.apple.com</code></pre>
</li>
<li>The <code>unzip</code> package must be installed on the machine:
<pre><code>yum install unzip</code></pre>
</li>
<li><a target="_blank" href="https://docs.docker.com/engine/install/">Docker</a> and <a target="_blank" href="https://docs.docker.com/compose/install/">Docker Compose</a> must be installed on the machine.</li>
<li>A domain name must be associated with the machine (for example, <span class="param-type">your-idp-domain.com</span>)</li>
</ul>
<h5>Creating Shibboleth IdP</h5>
<p>To create, configure and start Shibboleth IDP, download and execute the <a target="_blank" href="https://bit.ly/3fwo5e6">install.sh</a> script.</p>
<p>Here's what the script does:</p>
<ul>
<li>downloads docker files for creating Shibboleth Idp images and containers from <a target="_blank" href="https://github.com/UniconLabs/dockerized-idp-testbed">github</a>,</li>
<li>changes the default <span class="param-type">idptestbed.edu</span> domain in the configuration files to the domain specified when executing the script,</li>
<li>adds access via the SAML protocol for the specified ONLYOFFICE SP domain,</li>
<li>specifies which attributes are required for ONLYOFFICE SP to issue information about users from Shibboleth IDP (the <b>Attribute Mapping</b> setting),</li>
<li>creates and configures LDAP and creates users for issuing,</li>
<li>enables dynamic loading of metadata from ONLYOFFICE SP to Shibboleth IDP,</li>
<li>enables Shibboleth SLO, if necessary.</li>
</ul>
<ol>
<li>Download the install.sh script:
<pre><code>curl -L https://bit.ly/3fwo5e6 -o install.sh</code></pre>
</li>
<li>Make the script executable:
<pre><code>chmod +x install.sh</code></pre>
</li>
<li>Execute the script replacing parameters with your own ones:
<pre><code>./install.sh -id your-idp-domain.com -sd myportal-address.com --no_slo</code></pre>
<p>Script parameters:</p>
<ul>
<li><b>-id</b> - a domain name of the current machine for Shibboleth IDP.</li>
<li><b>-sd</b> - a domain name where ONLYOFFICE SP is deployed.</li>
<li><b>--no_slo</b> - disables Single Logout in Shibboleth IDP (<b>optional parameter</b>).</li>
</ul>
</li>
<li>Wait when Shibboleth IDP starts after executing the script.</li>
<li>To verify that Shibboleth IDP started correctly, open the <span class="param-type">https://your-idp-domain.com/idp/shibboleth</span> link in your browser. An xml file should be displayed.</li>
<li>Copy the <span class="param-type">https://{your_idp_domain}/idp/shibboleth</span> link (e.g., <span class="param-type">https://your-idp-domain.com/idp/shibboleth</span>) and go to the ONLYOFFICE portal signing in as an administrator. Open the <b>Control Panel</b> -> <b>SSO</b> page.</li>
</ol>
<h2 id="ConfigureSP">Configuring ONLYOFFICE SP</h2>
<ol>
<li>Make sure that you are signed in as an Administrator to your ONLYOFFICE <b>Control Panel</b> and click the <b>SSO</b> tab in the <b>PORTAL SETTINGS</b> section on the left sidebar.
<div class="notehelp">You can only register one enterprise Identity Provider for your organization on the ONLYOFFICE portal.</div>
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img1_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide93/shibboleth_1.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img1_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide93/shibboleth_1.png")%>" />
<div target="img1_eventcom_guides" class="screenphoto magnifier"></div>
</div>
</li>
<li>Enable SSO using the <b>Enable Single Sign-on Authentication</b> switcher and paste the link to the Shibboleth IdP into the <b>URL to Idp Metadata XML</b> field.
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img2_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide93/shibboleth_2.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img2_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide93/shibboleth_2.png")%>" />
<div target="img2_eventcom_guides" class="screenphoto magnifier"></div>
</div>
</li>
<li>Press the button with the upward arrow to load the IdP metadata. The <b>ONLYOFFICE SP Settings</b> form will be automatically filled in with your data from the Shibboleth IdP.
<p>As we disabled SLO when executing the install.sh script by specifying the <code>--no_slo</code> parameter, the <b>IdP Single Logout Endpoint URL</b> field will be empty.</p>
</li>
<li>Once the IdP metadata is loaded, two certificates will be added in the <b>IdP Public certificates</b> 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'.
<p>You need to delete the <b>second certificate in the list</b> and leave the first certificate only, which is the primary certificate. Use the <b>Delete</b> 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.</p>
</li>
<li>In the <b>Custom login button caption</b> field, you can enter any text instead of the default one (<em>Single Sign-on</em>). 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.
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img113_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide95/adfs_4-1.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img113_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide95/adfs_4-1.png")%>" />
<div target="img113_eventcom_guides" class="screenphoto magnifier"></div>
</div>
</li>
<li>Now you need to create self-signed certificates or add any other certificates in the <b>SP Certificates</b> section.
<div class="notehelp nh_important"><span class="important_notice_label">Important!</span>In the <b>Use for</b> list, choose the <b>signing and encrypt</b> option as your Shibboleth IdP is automatically configured with the install.sh script to verify that data is digitally signed and encrypted.</div>
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img3_1_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide94/onelogin_11.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img3_1_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide94/onelogin_11.png")%>" />
<div target="img3_1_eventcom_guides" class="screenphoto magnifier"></div>
</div>
<p>You should get nearly the same result:</p>
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img3_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide93/shibboleth_3.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img3_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide93/shibboleth_3.png")%>" />
<div target="img3_eventcom_guides" class="screenphoto magnifier"></div>
</div>
</li>
<li>In the <b>Attribute Mapping</b> section, set the correspondence of the fields in the ONLYOFFICE People module to the user attributes which will be returned from the Shibboleth IdP.
<table class="table_parameters">
<tbody>
<tr>
<th>First Name</th>
<td><span class="param-type">urn:oid:2.5.4.42</span></td>
</tr>
<tr>
<th>Last Name</th>
<td><span class="param-type">urn:oid:2.5.4.4</span></td>
</tr>
<tr>
<th>Email</th>
<td><span class="param-type">urn:oid:0.9.2342.19200300.100.1.3</span></td>
</tr>
<tr>
<th>Location</th>
<td><span class="param-type">urn:oid:2.5.4.7</span></td>
</tr>
<tr>
<th>Title</th>
<td><span class="param-type">urn:oid:2.5.4.12</span></td>
</tr>
<tr>
<th>Phone</th>
<td><span class="param-type">urn:oid:0.9.2342.19200300.100.1.41</span></td>
</tr>
</tbody>
</table>
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img5_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide93/shibboleth_5.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img5_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide93/shibboleth_5.png")%>" />
<div target="img5_eventcom_guides" class="screenphoto magnifier"></div>
</div>
<p>In the <b>Advanced Settings</b> section, you can check the <b>Hide auth page</b> option to hide default authentication page and automatically redirect to SSO service.</p>
</li>
<li>Click the <b>Save</b> button.</li>
<li>The <b>ONLYOFFICE SP Metadata</b> section should be opened.</li>
<li>Verify that our settings are publicly available by clicking the <b>Download SP Metadata XML</b> button. The XML file contents should be displayed.
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img6_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide93/shibboleth_6.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img6_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide93/shibboleth_6.png")%>" />
<div target="img6_eventcom_guides" class="screenphoto magnifier"></div>
</div>
<p>This xml file is usually used to configure Shibboleth IDP, but because the install.sh script enables <code>DynamicHTTPMetadataProvider</code>, we do not need to do that (Shibboleth IDP will download this xml file at the first request for the login).</p>
</li>
</ol>
<h2 id="CheckWork">Checking the work of the ONLYOFFICE SP with the Shibboleth IdP</h2>
<p>The install.sh script created 4 users which can be used for testing the work of the ONLYOFFICE SP with the Shibboleth IdP.</p>
<table class="table_parameters">
<thead>
<tr>
<th>Email</th>
<th>Username</th>
<th>Password</th>
<th>Comment</th>
</tr>
</thead>
<tbody>
<tr>
<th>student1@{your_idp_domain}</th>
<td>student1</td>
<td>password</td>
<td>Standard</td>
</tr>
<tr>
<th>student2@{your_idp_domain}</th>
<td>student2</td>
<td>password</td>
<td>Without givenName</td>
</tr>
<tr>
<th>student3@{your_idp_domain}</th>
<td>student3</td>
<td>password</td>
<td>With umlauts</td>
</tr>
<tr>
<th>staff1@{your_idp_domain}</th>
<td>staff1</td>
<td>password</td>
<td>Obligatory fields only</td>
</tr>
</tbody>
</table>
<h5>Logging in to ONLYOFFICE on the SP side</h5>
<ol>
<li>Go to the ONLYOFFICE Authentication page (e.g., <span class="param-type">https://myportal-address.com/Auth.aspx</span>).</li>
<li>Click the <b>Single sign-on</b> 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.
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img112_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide95/authenticationpage.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img112_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide95/authenticationpage.png")%>" />
<div target="img112_eventcom_guides" class="screenphoto magnifier"></div>
</div>
</li>
<li>If all the SP and IdP parameters are set correctly, we will be redirected to the Shibboleth IdP login form:
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img7_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide93/shibboleth_7.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img7_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide93/shibboleth_7.png")%>" />
<div target="img7_eventcom_guides" class="screenphoto magnifier"></div>
</div>
</li>
<li>Enter the username and password of the Shibboleth IdP account (username: <span class="param-type">student1</span>, password: <span class="param-type">password</span>) and check the <b>Don't Remember Login</b> box.</li>
<li>If the credentials are correct, a new window opens. Allow the provision of information to the service by clicking the <b>Accept</b> button.
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img11_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide93/shibboleth_7-1.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img11_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide93/shibboleth_7-1.png")%>" />
<div target="img11_eventcom_guides" class="screenphoto magnifier"></div>
</div>
</li>
<li>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).
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img17_2_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide93/startpage.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img17_2_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide93/startpage.png")%>" />
<div target="img17_2_eventcom_guides" class="screenphoto magnifier"></div>
</div>
</li>
</ol>
<h5>Profiles for users added with SSO authentication</h5>
<p>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. <code>First Name</code>, <code>Last Name</code>, <code>Email</code>, <code>Title</code> and <code>Location</code>). You can edit these fields from your IdP account only.</p>
<p>The figure below shows the Actions menu for an SSO user:</p>
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img8_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide93/shibboleth_8.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img8_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide93/shibboleth_8.png")%>" />
<div target="img8_eventcom_guides" class="screenphoto magnifier"></div>
</div>
<p>The following figure shows an SSO user profile opened for editing:</p>
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img9_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide93/shibboleth_9.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img9_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide93/shibboleth_9.png")%>" />
<div target="img9_eventcom_guides" class="screenphoto magnifier"></div>
</div>
<p>The users created using the SSO authentication are marked with the <span class="sso_icon">SSO</span> icon in the user list for the portal administrators:</p>
<div class="screen_block">
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" target="img10_eventcom_guides" class="screenphoto screen_guides" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/small/guide93/shibboleth_10.png")%>" />
<img alt="How to configure Shibboleth IdP and ONLYOFFICE SP" id="img10_eventcom_guides" class="bigphoto_screen" src="<%=VirtualPathUtility.ToAbsolute("~/images/Help/Guides/big/guide93/shibboleth_10.png")%>" />
<div target="img10_eventcom_guides" class="screenphoto magnifier"></div>
</div>
<p>To log out from the Shibboleth IdP (if you have not checked the <b>Don't Remember Login</b> box when logging in), go to the link that looks like this: <span class="param-type">https://{shibboleth-idp-domain}/idp/profile/Logout</span></p>
</div>
</div>