update saml.md (#86)

manual/config/enterprise/saml.md

@@ -8,7 +8,7 @@ Create certs dir
 
 ```
 docker exec -it seatable bash
-cd /opt/seatable
+cd /opt/seatable/seahub-data
 mkdir certs
 cd certs
 ```
@@ -33,55 +33,52 @@ Set user attributes: <https://docs.microsoft.com/en-us/azure/active-directory/de
 
 ![](../../images/auto-upload/004.png)
 
-Download base64 format signing certificate and metadata XML file, put them under the certs(/opt/seatable/certs) directory.
+Download base64 format signing certificate and metadata XML file, put them under the certs(/opt/seatable/seahub-data/certs) directory.
 
 ![](../../images/auto-upload/001.png)
 
 ## Configure SeaTable
 
 Add the following configuration to dtable_web_settings.py
 
-```
+```python
 ENABLE_SAML = True
-SAML_METADATA_REMOTE_URL = 'https://login.microsoftonline.com/xxx/federationmetadata/2007-06/federationmetadata.xml?appid=xxx'
-SAML_PROVIDER_DOMAIN = 'Azure_saml2'
+SAML_PROVIDER_DOMAIN = 'azure.saml'
+# 'Key' is the user attribute of Azure SAML, 'value' is the user attribute of SeaTable. The uid attribute of SeaTable is required.
 SAML_ATTRIBUTE_MAP = {
     'uid': 'uid',
-    'ContactEmail': 'contact_email',
-    'DisplayName': 'name',
+    'mail': 'contact_email',
+    'name': 'name',
     'employeeid': 'employee_id',   # Syncing user's employee ID from SAML
     'jobtitle': 'user_role',   # Syncing user's role from SAML
 }
-SAML_ENTITY_ID = 'https://test.seatable.cn/saml2/metadata/'
-
-# The following configuration is to generate SP metadata
 from os import path
 import saml2
 import saml2.saml
-
-CERTS_DIR = '/opt/seatable/certs/'
+CERTS_DIR = '/opt/seatable/seahub-data/certs/'
 SP_SERVICE_URL = 'https://test.seatable.cn'
-XMLSEC_BINARY = '/usr/bin/xmlsec1'
+XMLSEC_BINARY = '/usr/bin/xmlsec1'   # full path to the xmlsec1 binary programm
+ATTRIBUTE_MAP_DIR = '/opt/seatable/seatable-server-latest/dtable-web/seahub/saml/attribute-maps'
 SAML_CONFIG = {
-    'xmlsec_binary': XMLSEC_BINARY,   # full path to the xmlsec1 binary programm
-    'allow_unknown_attributes': True,
     'entityid': SP_SERVICE_URL + '/saml2/metadata/',   # your entity id
+    'xmlsec_binary': XMLSEC_BINARY,
+    'allow_unknown_attributes': True,
+    'attribute_map_dir': ATTRIBUTE_MAP_DIR,
     # this block states what services we provide
     'service': {
         # we are just a lonely SP
-        'sp' : {
-            "allow_unsolicited": True,
-            'name': 'Federated Seafile Service',
+        'sp': {
+            'allow_unsolicited': True,
+            'required_attributes': ['uid'],   # attributes that this SP need to identify a user
+            'name': 'Federated SeaTable Service',
             'name_id_format': saml2.saml.NAMEID_FORMAT_EMAILADDRESS,
-            'required_attributes': ["uid"],   # attributes that this project need to identify a user
-            'optional_attributes': ['eduPersonAffiliation', ],   # attributes that may be useful to have but not required
             'endpoints': {
                 'assertion_consumer_service': [
                     (SP_SERVICE_URL + '/saml/acs/', saml2.BINDING_HTTP_POST),
                 ],
             },
             'idp': {
-                # SAML_METADATA_REMOTE_URL
+                # App Federation Metadata URL
                 'https://login.microsoftonline.com/xxx/federationmetadata/2007-06/federationmetadata.xml?appid=xxx': {
                     'single_sign_on_service': {
                         # SingleSignOnService
@@ -90,21 +87,21 @@ SAML_CONFIG = {
                     'single_logout_service': {
                         # SingleLogoutService
                         saml2.BINDING_HTTP_REDIRECT: 'https://login.microsoftonline.com/xxx/saml2',
-                  },
+                    },
                 },
             },
         },
     },
     'metadata': {
-        'local': [path.join(CERTS_DIR, 'idp_federation_metadata.xml')],   # where the remote metadata is stored
+        'local': [path.join(CERTS_DIR, 'idp_federation_metadata.xml')],   # where the idp metadata is stored
     },
     'debug': 1,   # set to 1 to output debugging information
     'cert_file': path.join(CERTS_DIR, 'idp.crt'),   # Signing from IdP
     'encryption_keypairs': [{
-        'key_file': path.join(CERTS_DIR, 'sp.key'),  # private part
-        'cert_file': path.join(CERTS_DIR, 'sp.crt'),  # public part
+        'key_file': path.join(CERTS_DIR, 'sp.key'),   # private part
+        'cert_file': path.join(CERTS_DIR, 'sp.crt'),   # public part
     }],
-    'valid_for': 24,  # how long is our metadata valid
+    'valid_for': 24*365,   # how long is our metadata valid
 }
 
 ```
@@ -116,3 +113,32 @@ Restart SeaTable, enter the entity id URL of SeaTable in the browser, e.g. <http
 ![](../../images/auto-upload/002.png)
 
 Log in to the SeaTable homepage, click single sign-on, and use the user assigned to Azure SAML to perform a SAML login test.
+
+## FAQ
+
+### Login abnormal
+
+Please check the dtable_web.log log file. If there are errors such as `Signature missing for assertion` or `Signature missing for response` in the log, it means that the certificate signature method of the IdP (ie Azure SAML) does not match the configuration of the SP (ie SeaTable) , you need to add the following options in the SAML_CONFIG:
+
+```python
+SAML_CONFIG = {
+    ...
+
+    'service': {
+        'sp': {
+            ...
+
+            'want_response_signed': False,
+            'want_assertions_signed': False,
+            'want_assertions_or_response_signed': True,
+
+            ...
+        },
+    },
+
+    ...
+}
+
+```
+
+Reference: <https://pysaml2.readthedocs.io/en/latest/howto/config.html#want-assertions-or-response-signed>