Documentation

src/CUAuth/DataObjects/ShibIdentity.php

@@ -33,6 +33,9 @@ public function __construct(
         public readonly array $serverVars = [],
     ) {}
 
+    /**
+     * Shibboleth server variables will be retrieved from the request if not provided.
+     */
     public static function fromServerVars(?array $serverVars = null): self
     {
         if (empty($serverVars)) {
@@ -59,12 +62,18 @@ public function isWeillIdP(): bool
         return str_contains($this->idp, 'med.cornell.edu');
     }
 
+    /**
+     * Returns the primary email ([email protected]) if available, otherwise the alias email.
+     */
     public function email(): string
     {
         // eduPersonPrincipal name is [email protected], mail is alias email
         return $this->serverVars['eduPersonPrincipalName'] ?? $this->mail;
     }
 
+    /**
+     * Returns the display name if available, otherwise the common name.
+     */
     public function name(): string
     {
         return $this->serverVars['displayName'] ?? $this->serverVars['cn'] ?? '';

src/CUAuth/README.md

@@ -23,7 +23,7 @@ the `CUAuthenticated` event. This listener should take the `$userId` from the ev
 log them in or create as user as needed.
 
 > [AuthorizeUser](./Listeners/AuthorizeUser.php) is provided as a starting point for handling the CUAuthenticated event.
-> It is simplistic and should be replaced with a site-specific implementation in the site code base.
+> It is simplistic and should be replaced with a site-specific implementation in the site code base. It demonstrates retrieving user data from [ShibIdentity](./DataObjects/ShibIdentity.php) and creating a user if they do not exist. 
 
 If the REMOTE_USER server variable is not set or if the CUAuthenticated
 event handling does not result in a user being logged in, the middleware will return an HTTP_FORBIDDEN response.