saml: update doc for elabftw/elabftw#6217

doc/saml.rst

@@ -8,23 +8,18 @@ Configure SAML2 authentication
     :align: center
     :alt: authentication
 
-This page describes the steps necessary to setup SAML2 authentication on eLabFTW with an IDentity Provider (IDP). It assumes that you already know what we're talking about.
-
-The IDP can lookup identity on an LDAP directory and deal with two factors authentication.
+This page describes the steps necessary to setup SAML2 authentication on eLabFTW with an Identity Provider (IdP). Accordingly, this section is meant for users who are already familiar with the process of setting up and running an instance of eLabFTW and the basics of SAML2 authentication.
 
 Setup the Service Provider
 ==========================
 
-The service provider is the elabftw install. Head to the Sysadmin panel, click the SAML tab.
+The Service Provider (SP) is your eLabFTW instance. First, head to the Sysadmin panel and click the SAML tab.
 
-* Debug mode: Set to "No". We don't want to print errors
+* Debug mode: Set to "Yes". We want to print errors during the initial setup. Once everything is working, switch this setting back to "No"
 * Strict mode: Set to "Yes". Otherwise the mechanism is not secure
-* Base url: Where did you install elabftw? Example: https://elabftw.example.edu
-* entityId: The same as base URL
-* SAML protocol binding: basically it can be POST or HTTP-redirect. Depending on your IDP, set the correct value here
-* Single Logout Service: The same as entityId
-* Single Logout Service protocol binding: basically it can be POST or HTTP-redirect. Depending on your IDP, set the correct value here
-* NameIDFormat: match the supported NameIDFormat of the IDP, eLabFTW doesn't use this but it needs to be specified most of the time. Example values:
+* Base url: This is the base URL of your SP, _i.e._, the publicly accessible URL of your eLabFTW instance. Example: https://elabftw.example.edu
+* entityId: The same as the base URL in most cases.
+* NameIDFormat: match the supported NameIDFormat of the IdP, eLabFTW doesn't use this but it needs to be specified most of the time. Example values:
 
   - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress [default]
   - urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
@@ -45,22 +40,48 @@ Use the content of `private.key` and `cert.crt`.
 
 Alternatively you can use `this site <https://developers.onelogin.com/saml/online-tools/x509-certs/obtain-self-signed-certs>`_ to generate a self-signed certificate.
 
-Setup the IDentity Provider
-===========================
+Set up the Identity Provider
+============================
+
+Option A: using an XML file (recommended)
+-----------------------------------------
+
+We recommend that you use a Source XML file to ingest IdP information in eLabFTW. This way, information will be refreshed automatically. It's also much simpler to set up, as all metadata will be populated automagically.
+
+
+.. figure:: img/saml-idp-from-url.png
+    :align: center
+    :alt: saml xml url config
+
+    Use a URL pointing to XML metadata for IdPs
+
+Enter the URL into the input field, click the Save button, and then click the Refresh button so that the content is processed and the IdPs are added into the eLabFTW database. The IdPs will be disabled by default, so you will need to enable them manually.
 
-* Name: Visible to the user logging in. Example: "Institut Curie"
-* entityId: Example: https://idp1.agroparistech.fr/shibboleth
-* SSO url: Single Sign On URL
-* SSO binding: Example: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
-* SLO url: Single Log Out URL
-* SLO binding: Example: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
-* x509 cert: the public key of the IDP
+Example metadata URLs:
+^^^^^^^^^^^^^^^^^^^^^^
 
-The SLO URL that the IDP needs to know to redirect the user to would be `/app/logout.php`.
+Here are some IdP metadata listing URLs that you might want to use in your institution:
 
-Attributes for the IDP
+* France: Renater's federation, use: `https://metadata.federation.renater.fr/renater/main/main-idps-renater-metadata.xml`.
+* Germany: DFN AAI federation: `https://www.aai.dfn.de/metadata/dfn-aai-idp-metadata.xml`
+* Portugal: RCTSaai exported to eduGAIN: `https://registry.rctsaai.pt/rr/signedmetadata/federation/edugain/metadata.xml`
+* Microsoft's Entra ID, the URL will look like this: `https://login.microsoftonline.com/183ad437-6002-47ad-8886-c5185ce9be1a/federationmetadata/2007-06/federationmetadata.xml`
+* Italia: IDEM federation: `https://md.idem.garr.it/metadata/idem-metadata-sha256.xml`
+* Netherlands: SurfConext: `https://metadata.surfconext.nl/idps-metadata.xml`
+* Switzerland: SwithAAI: `https://metadata.aai.switch.ch/metadata.switchaai+idp.xml`
+* Sweden: SWAMID: `https://mds.swamid.se/md/swamid-idp.xml`
+
+Option B: add IdPs manually
+---------------------------
+
+Click the "Add new IDP" button, give it a name and an entityId, and configure the attributes.
+
+Then, from the IdP list, add certificate(s) and endpoint(s).
+
+Attributes for the IdP
 ----------------------
-We need to specify where to look in the attributes sent in the response for email, team and name of the user. You can use the FriendlyName or the Name from the table below. Note that this will depend on your IDP and using the SAML Tracer plugin (see below) to see the response will be helpful in determining what fields you want to use.
+We need to specify where to look in the attributes sent in the response for email, team and name of the user. You can use the FriendlyName or the Name from the table below.
+Note that this will depend on your IdP. You can use the SAML Tracer plugin (see below) to see the response. This will be helpful in determining the fields that you want to use.
 
 .. list-table:: SAML attributes
    :widths: 25 25 25 25
@@ -89,17 +110,17 @@ We need to specify where to look in the attributes sent in the response for emai
 
 If you cannot have information about the team, or do not wish to use it, make sure to have the setting "Let user select a team" when the user is created during first login.
 
-Note that the metadata.xml file (accessible at `/metadata.php`) will contain a section informing the IDP of the requested attributes.
+Note that the metadata.xml file (accessible at `/metadata.php`) will contain a section informing the IdP of the requested attributes.
 
 About the Userid / Internal ID
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you configure the ``uid`` (Userid/Internal ID) parameter for an IDP, the value will be read from the SAML assertion and:
+If you configure the ``uid`` (Userid/Internal ID) parameter for an IdP, the value will be read from the SAML assertion and:
 
 - for user creation on the fly, the ``orgid`` (Organization ID) field of the user will contain the value of the ``uid`` attribute
 - for an existing user logging in, the ``orgid`` will not be modified
 
-If you enable "Fallback to internal id if existing user cannot be matched with email", then the ``uid`` will be used to try and match an existing user if, during login, the match could not be done on the ``email`` field (user changed email for instance). You can then chose to enable "If user is matched with internal id, update the email sent by IDP?" so that the email sent by the IDP is updated in the local database.
+If you enable "Fallback to internal id if existing user cannot be matched with email", then the ``uid`` will be used to try and match an existing user if, during login, the match could not be done on the ``email`` field (user changed email for instance). You can then chose to enable "If user is matched with internal id, update the email sent by IdP?" so that the email sent by the IdP is updated in the local database.
 
 Disable local login/register
 ============================
@@ -109,33 +130,25 @@ Go to the Server tab of the Sysadmin panel. From there you can disable local log
 How does it work?
 =================
 
-When a user successfully logins to the IDP, the email address is looked up. If it doesn't exist, the user is created. If the team doesn't exist either, it is created on the fly. You can configure this behavior from the Sysconfig panel.
+When a user logs in to the IdP, the application searches for an existing account with that user's email address. If that email address is not found, a new user profile is created in the system. If the user's team doesn't exist, a new team is created automatically.
 
-Federation and metadata synchronization
-=======================================
+You can configure these behaviors from the Sysconfig panel.
 
-The application allows you to fetch a list of IDPs from an URL pointing to XML content.
-
-.. figure:: img/sysconfig-saml-idps-xml.png
-   :align: center
-   :alt: Adding IDPs via URL
-
-   Example of adding IDPs via URL
-
-After adding the URL, click the "Refresh" button so the application can synchronize the local list of IDPs with the XML content. The "Auto-refresh" toggle will trigger this synchronization every day (**WARNING**: this means that any manual change you make to the IDP will get overwritten!).
 
 Renewing certificates
 =====================
 
-IDP is changing certs
----------------------
+What to do when the IdP changes certificates
+--------------------------------------------
+
+If the IdP has a Source URL, meaning it was added from an XML file, then the renewal should happen smoothly, especially if the IdP starts advertising the new certificate before using it at least 24 hours before the change.
 
-Go to the Sysconfig panel, edit the corresponding IDP and add the new certificate into the "x509 Certificate" field. Add the old one into "x509 Certificate (additional for rollover)" so the transition is smooth.
+Otherwise, you can add the new certificate manually by editing the corresponding IdP. You can choose to keep the old cert around if it's still in use, or delete it if you know it's not used anymore.
 
-SP is changing certs
---------------------
+Changing the certificate of the service provider (SP)
+-----------------------------------------------------
 
-From the SAML tab of the Sysconfig panel, in the "Service provider" section, change "x509 Certificate in PEM format" and "x509 Certificate private key". Note from the developers: we never used the rollover thingy and have no idea if it even works.
+From the SAML tab of the Sysconfig panel, in the "Service provider" section, change "x509 Certificate in PEM format" and "x509 Certificate private key". Make sure your IdPs are aware of the change. If the IdPs are consuming the SP metadata, add the new cert in the specific rollover section so they have a chance to update their metadata. Then set it in the main x509 section along with the corresponding private key to start using it.
 
 Debugging
 =========