improve multi-tenancy adfs login (#165)

* improve multi-tenancy adfs login

* optimize docs

* Update multi_tenancy.md

Improve ADFS integration in multi-tenancy

* Update multi_tenancy.md

* Integration with on-premise ADFS

---------

Co-authored-by: Jiaqiang Xu <jonathan.xu@seafile.com>

manual/deploy_pro/multi_tenancy.md

@@ -11,7 +11,7 @@ multi_tenancy = true
 
 #### seahub_settings.py
 
-```
+```python
 CLOUD_MODE = True
 MULTI_TENANCY = True
 
@@ -21,9 +21,11 @@ ORG_ENABLE_ADMIN_CUSTOM_NAME = True  # Default is True, meaning organization nam
 ORG_ENABLE_ADMIN_CUSTOM_LOGO = False  # Default is False, if set to True, organization logo can be customized
 
 ENABLE_MULTI_ADFS = True  # Default is False, if set to True, support per organization custom ADFS/SAML2 login
+LOGIN_REDIRECT_URL = '/saml2/complete/'
 SAML_ATTRIBUTE_MAPPING = {
-    'mail': 'contact_email',
-    'displayName': 'display_name',
+    'name': ('display_name', ),
+    'mail': ('contact_email', ),
+    ...
 }
 ```
 
@@ -35,51 +37,55 @@ Every organization has an URL prefix. This field is *for future usage*. When a u
 
 After creating an organization, the first user will become the admin of that organization. The organization admin can add other users. Note, the system admin can't add users.
 
-## MULTI ADFS
+## ADFS/SAML single sign-on integration in multi-tenancy
 
-1\. Install xmlsec1
+### Preparation for ADFS/SAML
+
+**The _system admin_ has to complete the following works.**
+
+**Fisrt**, install xmlsec1 package:
 
 ```
 $ apt update
 $ apt install xmlsec1
 ```
 
-2\. **Sysadmin** prepares certificate directory for organization and generates SP certificate
+**Second**, prepare SP(Seafile) certificate directory and SP certificates:
 
-Create certs dir
+Create sp certs dir
 
 ```
-$ mkdir -p /opt/seafile/seahub-data/certs/<org_id>
+$ mkdir -p /opt/seafile/seahub-data/certs
 ```
 
-**Sysadmin** can generate them by:
+The SP certificate can be generated by the openssl command, or you can apply to the certificate manufacturer, it is up to you. For example, generate the SP certs using the following command:
 
 ```
-$ cd /opt/seafile/seahub-data/certs/<org_id>
-$ openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout sp.key -out sp.crt
+$ cd /opt/seafile/seahub-data/certs
+$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout sp.key -out sp.crt
 ```
 
-__Note__: The certificates of different organizations need to be put in different _org_id_ sub-directories.
+__Note__: The `days` option indicates the validity period of the generated certificate. The unit is day. The system admin needs to update the certificate regularly.
 
-3\. Configure Seafile
-
-Add the following configuration to seahub_settings.py and then restart Seafile:
+**Finally**, add the following configuration to seahub_settings.py and then restart Seafile:
 
 ```python
-ENABLE_ADFS_LOGIN = True
+ENABLE_MULTI_ADFS = True
+LOGIN_REDIRECT_URL = '/saml2/complete/'
 SAML_ATTRIBUTE_MAPPING = {
-    'mail': 'contact_email',
-    'name': 'display_name',
+    'name': ('display_name', ),
+    'mail': ('contact_email', ),
+    ...
 }
 ```
 
-__Note__: If the xmlsec1 binary is **not situated in** `/usr/bin/xmlsec1`, you need to add the following configuration in seahub_settings.py:
+__Note__: If the xmlsec1 binary is **not located in** `/usr/bin/xmlsec1`, you need to add the following configuration in seahub_settings.py:
 
 ```python
 SAML_XMLSEC_BINARY_PATH = '/path/to/xmlsec1'
 ```
 
-View where the xmlsec1 binary is situated:
+View where the xmlsec1 binary is located:
 
 ```
 $ which xmlsec1
@@ -91,34 +97,136 @@ __Note__: If certificates are **not placed in** `/opt/seafile/seahub-data/certs`
 SAML_CERTS_DIR = '/path/to/certs'
 ```
 
-4\. **Organization admin** Configure Azure SAML
+### Integration with ADFS/SAML single sign-on
 
-Add application: <https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal>
+The _organization admin_ has to complete the following works. The detailed steps depends on which ADFS service you use. We provide integration steps for Azure SAML SSO and on-premise ADFS.
 
-Assign users: <https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-assign-users>
+#### Integration with Microsoft Azure SAML single sign-on app
 
-Set up SSO with SAML: 
+If you use Microsoft Azure SAML app to achieve single sign-on, please follow the steps below:
 
-![](../images/auto-upload/1678350584150.jpg)
+**First**, add SAML application and assign users, refer to: [add an Azure AD SAML application](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal), [create and assign users](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-assign-users)
 
-Your _meradate url_, _acs url_, _service url_ might like this:
+**Second**, setup your SAML login URL in the Seafile organization admin interface. The format of the login URL is: https://example.com/org/custom/{custom-part}/, e.g.:
 
-![](../images/auto-upload/image-1671861383531.png)
+![](../images/auto-upload/8c1988cd-1f66-47c9-ac61-650e8245efcf.png)
 
-__Note__: The _org_n4dhr37woadw9uco06sr_ is a customizable string, you can customize according to your own needs: https://example.com/org/custom/{custom-part}/
+**Then**, setup the _Identifier_, _Reply URL_, and _Sign on URL_ of the SAML app based on your login URL, refer to: [enable single sign on for saml application](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-sso). The format of the _Identifier_, _Reply URL_, and _Sign on URL_ are: https://example.com/org/custom/{custom-part}/saml2/metadata/, https://example.com/org/custom/{custom-part}/saml2/acs/, https://example.com/org/custom/{custom-part}/, e.g.:
 
-5\. Download Azure AD certificate
+![](../images/auto-upload/498c6ae2-9213-4452-9238-676d179c375c.png)
 
-Download base64 format signing certificate, rename to idp.crt.
+__Note__: The {custom-part} of the URL should be 6 to 20 characters, and can only contain alphanumeric characters and hyphens.
 
-![](../images/auto-upload/1678343483221.jpg)
+**Next**, copy the metadata URL of the SAML app:
 
-6\. Configures options related to SAML login
+![](../images/auto-upload/6702c7c7-a205-4b18-91d2-48dd1a1b7b03.png)
 
-**Organization admin** configures options related to SAML login in the organization management interface.
+and paste it into the organization admin interface, e.g:
 
-![](../images/auto-upload/a876234f-dbe8-496b-b447-1ef161ab7c3a.png)
+![](../images/auto-upload/d2252310-0c30-4d88-a553-5711820a65df.png)
 
-![](../images/auto-upload/b4e90b49-e6df-4b11-882c-93aefdb3075c.png)
+**Next**, download the base64 format SAML app's certificate and rename to idp.crt:
 
-7\. Open the browser and enter https://example.com/org/custom/{custom-part}/ for single sign-on.
+![](../images/auto-upload/3aa0b19d-46ac-426e-adcc-b3869b0a95a1.png)
+
+and upload the idp.crt in the organization admin interface:
+
+![](../images/auto-upload/5b3ff455-de3f-4585-93d2-8ecc1c7cc0ea.png)
+
+**Next**, [edit saml attributes & claims](https://learn.microsoft.com/en-us/azure/active-directory/develop/saml-claims-customization). Keep the default attributes & claims of SAML app unchanged, the _uid_ attribute must be added, the _mail_ and _name_ attributes are optional, e.g.:
+
+![](../images/auto-upload/abee9c69-f03d-4735-9231-92bd923b9ceb.png)
+
+**Finally**, open the browser and enter your custom login URL into the browser, e.g.:
+
+![](../images/auto-upload/fc85a75e-fde8-43e0-bd88-541adae6c54c.png)
+
+Click the Enter key will jump to the SAML app login page, e.g.:
+
+![](../images/auto-upload/21dc07ae-89a7-4281-be18-566a64bca922.png)
+
+#### Integration with on-premise ADFS
+
+If you use Microsoft ADFS to achieve single sign-on, please follow the steps below:
+
+**First**, please make sure the following preparations are done:
+
+1. A Windows Server with [ADFS](https://learn.microsoft.com/en-us/windows-server/identity/active-directory-federation-services) installed. For configuring and installing ADFS you can see [this article](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/deployment/deploying-a-federation-server-farm).
+
+2. A valid SSL certificate for ADFS server, and here we use `temp.adfs.com` as the domain name example.
+
+**Second**, setup your ADFS login URL in the Seafile organization admin interface. The format of the login URL is: `https://example.com/org/custom/{custom-part}/`, e.g.:
+
+![](../images/auto-upload/8c1988cd-1f66-47c9-ac61-650e8245efcf.png)
+
+**Next**, setup the federation metadata URL of Microsoft ADFS in the organization admin interface. The format of the federation metadata URL is: `https://{your ADFS domain name}/federationmetadata/2007-06/federationmetadata.xml`, e.g:
+
+![](../images/auto-upload/bde53e1b-dfef-4693-bba8-8ec8801627d6.png)
+
+**Next**, download the base64 format certificate and upload it:
+
+* Navigate to the _AD FS_ management window. In the left sidebar menu, navigate to **Services** > **Certificates**. 
+
+* Locate the _Token-signing_ certificate. Right-click the certificate and select **View Certificate**.
+
+![](../images/auto-upload/7a1eead2-272f-40ec-9768-effc1d4f3273.png)
+
+* In the dialog box, select the **Details** tab.
+
+* Click **Copy to File**.
+
+* In the _Certificate Export Wizard_ that opens, click **Next**.
+
+* Select **Base-64 encoded X.509 (.CER)**, then click **Next**.
+
+* Named it **idp.crt**, then click **Next**.
+
+* Click **Finish** to complete the download.
+
+* And then upload the idp.crt in the organization admin interface:
+
+![](../images/auto-upload/7f2b4010-5f50-4184-9d56-fe60d5a5809e.png)
+
+**Next**, add [relying party trust](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust#to-create-a-claims-aware-relying-party-trust-using-federation-metadata):
+
+* Log into the ADFS server and open the ADFS management.
+
+* Under **Actions**, click **Add Relying Party Trust**.
+
+* On the Welcome page, choose **Claims aware** and click **Start**.
+
+* Select **Import data about the relying party published online or on a local network**, type your organization metadate url in **Federation metadata address (host name or URL)**, and then click **Next**. Your organization metadate url format is: `https://example.com/org/custom/{custom-part}/saml2/metadata/`, e.g.:
+
+![](../images/auto-upload/e343f174-e31c-4aba-8f26-2b78927f625c.png)
+
+* On the **Specify Display Name** page type a name in **Display name**, e.g. `Seafile`, under **Notes** type a description for this relying party trust, and then click **Next**.
+
+* In the **Choose an access control policy** window, select **Permit everyone**, then click **Next**.
+
+* Review your settings, then click **Next**. 
+
+* Click **Close**. 
+
+**Next**, create claims rules:
+
+* Open the ADFS management, click **Relying Party Trusts**.
+
+* Right-click your trust, and then click **Edit Claim Issuance Policy**.
+
+* On the **Issuance Transform Rules** tab click **Add Rules**.
+
+* Click the **Claim rule template** dropdown menu and select **Send LDAP Attributes as Claims**, and then click **Next**. 
+
+* In the **Claim rule name** field, type the display name for this rule, such as **Seafile Claim rule**. Click the **Attribute store** dropdown menu and select **Active Directory**. In the **LDAP Attribute** column, click the dropdown menu and select **User-Principal-Name**. In the **Outgoing Claim Type** column, click the dropdown menu and select **UPN**. And then click **Finish**.
+
+* Click **Add Rule** again. 
+
+* Click the **Claim rule template** dropdown menu and select **Transform an Incoming Claim**, and then click **Next**. 
+
+* In the **Claim rule name** field, type the display name for this rule, such as **UPN to Name ID**. Click the **Incoming claim type** dropdown menu and select **UPN**(It must match the **Outgoing Claim Type** in rule `Seafile Claim rule`). Click the **Outgoing claim type** dropdown menu and select **Name ID**. Click the **Outgoing name ID format** dropdown menu and select **Email**. And then click **Finish**.
+
+* Click **OK** to add both new rules.
+
+__Note__: When creating claims rule, you can also select other LDAP Attributes, such as E-Mail-Addresses, depending on your ADFS service.
+
+**Finally**, open the browser and enter your custom login URL into the browser to perform a ADFS login test.

manual/deploy_pro/saml2_in_10.0.md

@@ -63,6 +63,10 @@ Add application: <https://docs.microsoft.com/en-us/azure/active-directory/manage
 
 Assign users: <https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-assign-users>
 
+Enable single sign on for saml application: <https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-sso>
+
+Custom saml Attributes & Claims <https://learn.microsoft.com/en-us/azure/active-directory/develop/saml-claims-customization>
+
 Set up SSO with SAML: 
 
 ![](../images/auto-upload/1678350584150.jpg)