Improve Documentation of Attribute Mapping

For the benefit of others, here's how I was able to get custom attributes/mapping working with drupalauth4ssp.

First, you will need to patch the drupalauth/simplesamlphp-module-drupalauth module required by drupalauth4ssp using this PR. As of Feb 27, 2024 the PR has not yet been integrated. What that PR does is it creates an Event in the drupalauth SSP module to allow for a Drupal EventSubscriber.

Next you will need to create your custom EventSubscriber to subscribe to the SimpleSAML\Module\drupalauth\Event\SetAttributesEvent created with the patch from the PR above.

Below is an example of how I am mapping to First and Last names in Drupal which are created via the 'name' module, which is not accounted for with the out-of-the-box attribute mapping of drupaluth.

 declare(strict_types=1);

namespace Drupal\custom_sso\EventSubscriber;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use SimpleSAML\Module\drupalauth\Event\SetAttributesEvent;

/**
 * @todo Add description for this subscriber.
 */
final class CustomSsoSubscriber implements EventSubscriberInterface
{

  /**
   * {@inheritdoc}
   */
    public static function getSubscribedEvents(): array
    {
        $message = "getSubcribedEvents fired";
        return [
        SetAttributesEvent::EVENT_NAME => ['setAttributes'],
        ];
    }

  /**
   * React to attributes
   *
   * @param \SimpleSAML\Module\drupalauth\Event\SetAttributesEvent $event
   *   Drupalauth setAttributes event.
   */
    public function setAttributes(SetAttributesEvent $event)
    {
        $user = $event->getUser();
        if (!$user->get('field_name')->isEmpty()) {
            $first = isset($user->get('field_name')->given) ? $user->get('field_name')->given : NULL;
            $last = isset($user->get('field_name')->family) ? $user->get('field_name')->family : NULL;
            $attributes = $event->getAttributes();
            $attributes['givenName'] = [$first];
            $attributes['sn'] = [$last];
            $event->setAttributes($attributes);
        }
    }
}