docs(users): Match comments wrt SAML with openHPI

Author: nenock

app/controllers/users/omniauth_callbacks_controller.rb

@@ -131,9 +131,11 @@ def set_flash(type, key, kind: OmniAuth::Utils.camelize(omniauth_provider), reas
     end
 
     def current_user
-      # Check if an existing user is already signed in (passed through the RelayState)
-      # and trying to add a new identity to their account. If so, we load the user information
-      # and set it as the current user. This is necessary to avoid creating a new user.
+      # Check if an existing user is already signed in and trying to add a new identity to their account;
+      # the session ID is passed through the RelayState then (see the `AbstractSaml` strategy).
+      #
+      # If the RelayState contains the ID of the current user, we pass it on, so that the middleware can find the
+      # current user. This is necessary to avoid creating a new user.
       @current_user ||= User.find_by(id: OmniAuth::NonceStore.pop(params[:RelayState])) || super
     end
 

lib/omni_auth/strategies/abstract_saml.rb

@@ -25,10 +25,9 @@ class AbstractSaml < OmniAuth::Strategies::SAML
         want_assertions_encrypted: true, # Invalidate SAML messages without an EncryptedAssertion
       }
 
-      # Our auto-login mechanism passes a desired application state to the request phase.
-      # So far, this is used to store a temporary token for the current user in the RelayState.
-      # If we forward this via SAML's standard "RelayState" parameter, we will
-      # get it back in the callback phase.
+      # During the request phase, we store the ID of the current user in the `request.params`.
+      # It is passed through via SAML's standard `RelayState` parameter, so it will be preserved and can be used in the
+      # callback phase.
       option :idp_sso_service_url_runtime_params, {
         relay_state: 'RelayState',
       }
@@ -81,9 +80,8 @@ def with_settings # rubocop:disable Metrics/AbcSize
         options[:slo_default_relay_state] ||= full_host
 
         if on_request_path? && current_user
-          # We want to store the current user in the SAML RelayState,
-          # so that we can auto-login the user in the callback phase.
-          # This allows a registered user to add further OmniAuth providers.
+          # Store the ID of the current user in the SAML RelayState if a user is logged in, so that it can be accessed
+          # for requesting the current user in the callback phase and to add the new identity to the existing account.
           request.params['relay_state'] = NonceStore.add current_user.id
         end
         super