Clarify SAML attribute configuration requirements in documentation for v4.8.0+ (#344)

* Initial plan

* Add SAML attribute configuration clarifications and troubleshooting section

Co-authored-by: nijel <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: nijel <[email protected]>

Author: Copilot

docs/backends/saml.rst

@@ -103,6 +103,25 @@ At a minimum, you must add the following to your project's settings:
   values associated with the attr_* keys correspond to the keys specified as
   attributes in the IDP.
 
+  .. important::
+
+     **Version 4.8.0+ Behavior Change:**
+
+     When you explicitly configure an attribute (e.g., ``attr_first_name``), that
+     attribute **must** be present in the SAML response from the IdP. If it is
+     missing, authentication will fail with an error like:
+     ``Missing needed parameter first_name (configured by attr_first_name)``.
+
+     **Options:**
+
+     1. **Remove the configuration** if the attribute is not provided by your IdP.
+        The backend will automatically try to map using built-in attribute names.
+
+     2. **Ensure your IdP provides the attribute** with the exact name you configured.
+
+     3. **Use the correct attribute name** from your IdP's SAML response (check
+        the actual attribute names sent by your IdP).
+
   Extending on the "testshib" example::
 
       {
@@ -124,6 +143,15 @@ At a minimum, you must add the following to your project's settings:
   Note: testshib does not provide email as an attribute. This was tested using
   Okta and G Suite (formerly Google Apps for Business).
 
+  **Built-in Attribute Mappings:**
+
+  If you omit the ``attr_*`` configuration keys, the backend will automatically
+  try to extract user details using a list of commonly used attribute names,
+  including both namespaced URN variants (like
+  ``http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname``) and
+  simple names (like ``first_name``, ``firstName``, ``given_name``). Missing
+  attributes will be silently ignored when using the built-in mappings.
+
 Basic Usage
 -----------
 
@@ -225,6 +253,51 @@ particular, there are two methods that are designed for subclasses to override:
   inspecting the passed attributes parameter, do nothing to allow the user to
   login, or raise ``social_core.exceptions.AuthForbidden`` to reject the user.
 
+
+Troubleshooting
+---------------
+
+**Error: "Missing needed parameter first_name (configured by attr_first_name)"**
+
+This error occurs when you have explicitly configured an attribute mapping (like
+``attr_first_name``) but your IdP is not providing that attribute in the SAML
+response.
+
+**Solution:**
+
+1. **Check what attributes your IdP actually provides.** Inspect the SAML
+   response from your IdP to see the exact attribute names being sent.
+
+2. **Remove unused attribute configurations.** If your IdP doesn't provide
+   ``first_name``, simply remove ``"attr_first_name": "first_name"`` from your
+   configuration. The backend will try to use built-in mappings instead.
+
+3. **Use the correct attribute name.** If your IdP provides the attribute with
+   a different name (e.g., ``givenName`` or a namespaced URN like
+   ``http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname``), use
+   that name in your configuration::
+
+       "attr_first_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
+
+4. **Configure your IdP** to include the attribute in the SAML response if you
+   need it.
+
+**Example:** For Google G Suite SSO, if you're not receiving ``first_name`` and
+``last_name`` attributes, remove those configurations and let the backend use
+its built-in mappings::
+
+    SOCIAL_AUTH_SAML_ENABLED_IDPS = {
+        "gsuite": {
+            "entity_id": "...",
+            "url": "...",
+            "x509cert": "...",
+            "attr_user_permanent_id": "email",
+            "attr_username": "email",
+            "attr_email": "email",
+            # Remove attr_first_name and attr_last_name if not provided by IdP
+        }
+    }
+
 .. _python3-saml: https://github.com/onelogin/python3-saml
 .. _TestShib: https://www.testshib.org/
 .. _metadata: https://www.testshib.org/metadata/testshib-providers.xml