diff --git a/manual/deploy_pro/saml2_in_10.0.md b/manual/deploy_pro/saml2_in_10.0.md index 837e2eca..4237af61 100644 --- a/manual/deploy_pro/saml2_in_10.0.md +++ b/manual/deploy_pro/saml2_in_10.0.md @@ -1,15 +1,17 @@ # SAML 2.0 in version 10.0 -In this document, we use Azure SAML to show the steps to connect Seafile with SAML. Other SAML provider should be similar. +In this document, we use Microsoft Azure SAML single sign-on app and Microsoft on-premise ADFS to show how Seafile integrate SAML 2.0. Other SAML 2.0 provider should be similar. -1\. Install xmlsec1 +## Preparations for SAML 2.0 + +**First**, install xmlsec1 package: ``` $ apt update $ apt install xmlsec1 ``` -2\. Prepare Certs File +**Second**, prepare SP(Seafile) certificate directory and SP certificates: Create certs dir @@ -17,35 +19,67 @@ Create certs dir $ mkdir -p /opt/seafile/seahub-data/certs ``` -You 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 $ openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout sp.key -out sp.crt ``` -3\. Configure Seafile +__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. -Add the following configuration to seahub_settings.py and then restart Seafile: +## Integration with ADFS/SAML single sign-on + +### Integration with Microsoft Azure SAML single sign-on app + +If you use Microsoft Azure SAML app to achieve single sign-on, please follow the steps below: + +**First**, add SAML single sign-on app 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). + +**Second**, setup the _Identifier_, _Reply URL_, and _Sign on URL_ of the SAML app based on your service URL, refer to: [enable single sign-on for saml app](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/saml2/metadata/, https://example.com/saml2/acs/, https://example.com/, e.g.: + +![](../images/auto-upload/72c7b210-4a91-4e86-ba2e-df5ae0a4a0b0.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/417d-a48a-3e10c46b98f0.png) + +**Next**, download the base64 format SAML app's certificate and rename to idp.crt: + +![](../images/auto-upload/0a693563-d511-4c3c-ac30-82a26d10cfab.png) + +and put it under the certs directory(`/opt/seafile/seahub-data/certs`). + +**Next**, copy the metadata URL of the SAML app: + +![](../images/auto-upload/1426318f-0a61-462d-a514-13768ca0b18c.png) + +and paste it into the `SAML_REMOTE_METADATA_URL` option in seahub_settings.py, e.g.: + +```python +SAML_REMOTE_METADATA_URL = 'https://login.microsoftonline.com/xxx/federationmetadata/2007-06/federationmetadata.xml?appid=xxx' # copy from SAML app +``` + +**Next**, add `ENABLE_ADFS_LOGIN`, `LOGIN_REDIRECT_URL` and `SAML_ATTRIBUTE_MAPPING` options to seahub_settings.py, and then restart Seafile, e.g: ```python ENABLE_ADFS_LOGIN = True LOGIN_REDIRECT_URL = '/saml2/complete/' -SAML_REMOTE_METADATA_URL = 'https://login.microsoftonline.com/xxx/federationmetadata/2007-06/federationmetadata.xml?appid=xxx' SAML_ATTRIBUTE_MAPPING = { 'name': ('display_name', ), 'mail': ('contact_email', ), ... } +SAML_REMOTE_METADATA_URL = 'https://login.microsoftonline.com/xxx/federationmetadata/2007-06/federationmetadata.xml?appid=xxx' # copy from SAML app ``` -__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 @@ -57,24 +91,96 @@ __Note__: If certificates are **not placed in** `/opt/seafile/seahub-data/certs` SAML_CERTS_DIR = '/path/to/certs' ``` -4\. Configure Azure SAML +**Finally**, open the browser and enter the Seafile login page, click `Single Sign-On`, and use the user assigned to SAML app to perform a SAML login test. -Add application: +### Integration with on-premise ADFS -Assign users: +If you use Microsoft ADFS to achieve single sign-on, please follow the steps below: -Enable single sign on for saml application: +**First**, please make sure the following preparations are done: -Custom saml Attributes & Claims +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). -Set up SSO with SAML: +2. A valid SSL certificate for ADFS server, and here we use `temp.adfs.com` as the domain name example. -![](../images/auto-upload/1678350584150.jpg) +3. A valid SSL certificate for Seafile server, and here we use `demo.seafile.com` as the domain name example. -5\. Upload Azure AD certificate +**Second**, download the base64 format certificate and upload it: -Download base64 format signing certificate, rename to idp.crt, and then put it under the certs directory. +* Navigate to the _AD FS_ management window. In the left sidebar menu, navigate to **Services** > **Certificates**. -![](../images/auto-upload/1678343483221.jpg) +* Locate the _Token-signing_ certificate. Right-click the certificate and select **View Certificate**. -6\. Log in to the Seafile homepage, click single sign-on, and use the user assigned to Azure SAML to perform a SAML login test. +![](../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 put it under the certs directory(`/opt/seafile/seahub-data/certs`). + +**Next**, add the following configurations to seahub_settings.py and then restart Seafile: + +```python +ENABLE_ADFS_LOGIN = True +LOGIN_REDIRECT_URL = '/saml2/complete/' +SAML_ATTRIBUTE_MAPPING = { + 'name': ('display_name', ), + 'mail': ('contact_email', ), + ... +} +SAML_REMOTE_METADATA_URL = 'https://temp.adfs.com/federationmetadata/2007-06/federationmetadata.xml' # The format of the ADFS federation metadata URL is: `https://{your ADFS domain name}/federationmetadata/2007-06/federationmetadata.xml` + +``` + +**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 metadate url in **Federation metadata address (host name or URL)**, and then click **Next**. Your metadate url format is: `https://example.com/saml2/metadata/`, e.g.: + +![](../images/auto-upload/4d6412ee-009e-42df-b0eb-081735d873c5.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 the Seafile login page, click `Single Sign-On` to perform ADFS login test. diff --git a/manual/images/auto-upload/0a693563-d511-4c3c-ac30-82a26d10cfab.png b/manual/images/auto-upload/0a693563-d511-4c3c-ac30-82a26d10cfab.png new file mode 100644 index 00000000..71b4d407 Binary files /dev/null and b/manual/images/auto-upload/0a693563-d511-4c3c-ac30-82a26d10cfab.png differ diff --git a/manual/images/auto-upload/1426318f-0a61-462d-a514-13768ca0b18c.png b/manual/images/auto-upload/1426318f-0a61-462d-a514-13768ca0b18c.png new file mode 100644 index 00000000..07adf880 Binary files /dev/null and b/manual/images/auto-upload/1426318f-0a61-462d-a514-13768ca0b18c.png differ diff --git a/manual/images/auto-upload/1678343483221.jpg b/manual/images/auto-upload/1678343483221.jpg deleted file mode 100644 index 22e50bb0..00000000 Binary files a/manual/images/auto-upload/1678343483221.jpg and /dev/null differ diff --git a/manual/images/auto-upload/1678350584150.jpg b/manual/images/auto-upload/1678350584150.jpg deleted file mode 100644 index 362f708b..00000000 Binary files a/manual/images/auto-upload/1678350584150.jpg and /dev/null differ diff --git a/manual/images/auto-upload/417d-a48a-3e10c46b98f0.png b/manual/images/auto-upload/417d-a48a-3e10c46b98f0.png new file mode 100644 index 00000000..93c32a34 Binary files /dev/null and b/manual/images/auto-upload/417d-a48a-3e10c46b98f0.png differ diff --git a/manual/images/auto-upload/4d6412ee-009e-42df-b0eb-081735d873c5.png b/manual/images/auto-upload/4d6412ee-009e-42df-b0eb-081735d873c5.png new file mode 100644 index 00000000..21a36152 Binary files /dev/null and b/manual/images/auto-upload/4d6412ee-009e-42df-b0eb-081735d873c5.png differ diff --git a/manual/images/auto-upload/72c7b210-4a91-4e86-ba2e-df5ae0a4a0b0.png b/manual/images/auto-upload/72c7b210-4a91-4e86-ba2e-df5ae0a4a0b0.png new file mode 100644 index 00000000..b39a7e2d Binary files /dev/null and b/manual/images/auto-upload/72c7b210-4a91-4e86-ba2e-df5ae0a4a0b0.png differ