Add PreauthUserDetailsService, remove binaries

README.md

@@ -2,9 +2,27 @@
 
 uw-php-security is a PHP companion to [uw-spring-security](https://git.doit.wisc.edu/adi-ia/uw-spring-security) for Java. Its purpose is to ease development of PHP applications needing details about UW users provided through Shibboleth.
 
+Like uw-spring-security, uw-php-security provides a class called `UWUserDetails` for easily accessing common UW user attributes. This model is provided to applications through a `UserDetailsService`, and uw-php-security provides implementations suitable for both local and preauth (Shibboleth) environments.
+
+```php
+<?php
+
+use edu\wisc\doit\PreauthUserDetailsService; // or LocalUserDetailsService for local development
+...
+$userDetailsService = new PreauthUserDetailsService();
+$user = $userDetailsService->loadUser();
+if ($user == null) {
+    // handle error
+}
+...
+```
+
 ## Developer Requirements
 
 * PHP
+* [Composer](https://getcomposer.org/)
+* [Phing](https://www.phing.info/)
+* [PHPUnit](https://phpunit.de/)
 
 ## Building
 

composer.json

@@ -19,5 +19,10 @@
     "psr-4": {
       "edu\\wisc\\doit\\": "src/main/edu/wisc/doit/"
     }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "edu\\wisc\\doit\\": "src/test/edu/wisc/doit"
+    }
   }
 }

src/main/edu/wisc/doit/LocalUserDetailsAttributeMapper.php

@@ -14,14 +14,12 @@ class LocalUserDetailsAttributeMapper implements UserDetailsAttributeMapper
     public function mapUser()
     {
         $jsonString = file_get_contents(__DIR__ . "/../../../resources/localuser.json");
-        if ($jsonString == false) {
+        if ($jsonString === false) {
             return null;
         }
 
-        // Load user attributes into a standard PHP array (true specifies array)
-        $userAttributes = json_decode($jsonString, true);
-        
-        return $userAttributes;
+        // Return user attributes into a standard PHP array (true specifies array)
+        return json_decode($jsonString, true);
     }
 
 }
\ No newline at end of file

src/main/edu/wisc/doit/LocalUserDetailsService.php

@@ -36,17 +36,17 @@ class LocalUserDetailsService implements UserDetailsService
             return null;
         }
         
-        $userDetails = new UWUserDetails($userAttributes[UserDetailsAttributeMapper::EPPN],
-                                         $userAttributes[UserDetailsAttributeMapper::PVI],
-                                         $userAttributes[UserDetailsAttributeMapper::FULLNAME],
-                                         $userAttributes[UserDetailsAttributeMapper::UDDS],
-                                         $userAttributes[UserDetailsAttributeMapper::EMAIL],
-                                         $userAttributes[UserDetailsAttributeMapper::SOURCE],
-                                         $userAttributes[UserDetailsAttributeMapper::ISIS_EMPLID],
-                                         $userAttributes[UserDetailsAttributeMapper::FIRST_NAME],
-                                         $userAttributes[UserDetailsAttributeMapper::LAST_NAME]);
-        
-        return $userDetails;
+        return new UWUserDetails(
+            $userAttributes[UserDetailsAttributeMapper::EPPN],
+            $userAttributes[UserDetailsAttributeMapper::PVI],
+            $userAttributes[UserDetailsAttributeMapper::FULLNAME],
+            $userAttributes[UserDetailsAttributeMapper::UDDS],
+            $userAttributes[UserDetailsAttributeMapper::EMAIL],
+            $userAttributes[UserDetailsAttributeMapper::SOURCE],
+            $userAttributes[UserDetailsAttributeMapper::ISIS_EMPLID],
+            $userAttributes[UserDetailsAttributeMapper::FIRST_NAME],
+            $userAttributes[UserDetailsAttributeMapper::LAST_NAME]
+        );
     }
     
 }
\ No newline at end of file

src/main/edu/wisc/doit/PreauthUserDetailsAttributeMapper.php

+<?php
+
+namespace edu\wisc\doit;
+
+/**
+ * Default implementation of {@UserDetailsAttributeMapper} for use in preauthenticated (Shibboleth) environments.
+ */
+class PreauthUserDetailsAttributeMapper implements UserDetailsAttributeMapper
+{
+
+    /**
+     * {@inheritdoc}
+     */
+    public function mapUser()
+    {
+        $userAttributes[UserDetailsAttributeMapper::EPPN] = $_SERVER[UserDetailsAttributeMapper::EPPN];
+        $userAttributes[UserDetailsAttributeMapper::PVI] = $_SERVER[UserDetailsAttributeMapper::PVI];
+        $userAttributes[UserDetailsAttributeMapper::FULLNAME] = $_SERVER[UserDetailsAttributeMapper::FULLNAME];
+        $userAttributes[UserDetailsAttributeMapper::FIRST_NAME] = $_SERVER[UserDetailsAttributeMapper::FIRST_NAME];
+        $userAttributes[UserDetailsAttributeMapper::LAST_NAME] = $_SERVER[UserDetailsAttributeMapper::LAST_NAME];
+        $userAttributes[UserDetailsAttributeMapper::EMAIL] = $_SERVER[UserDetailsAttributeMapper::EMAIL];
+        $userAttributes[UserDetailsAttributeMapper::UDDS] = $_SERVER[UserDetailsAttributeMapper::UDDS];
+        $userAttributes[UserDetailsAttributeMapper::SOURCE] = $_SERVER[UserDetailsAttributeMapper::SOURCE];
+        $userAttributes[UserDetailsAttributeMapper::ISIS_EMPLID] = $_SERVER[UserDetailsAttributeMapper::ISIS_EMPLID];
+
+        // Require EPPN, PVI and FULLNAME to be set to consider user loading successful
+        if (empty($userAttributes[UserDetailsAttributeMapper::EPPN]) ||
+            empty($userAttributes[UserDetailsAttributeMapper::PVI]) ||
+            empty($userAttributes[UserDetailsAttributeMapper::FULLNAME])) {
+            return null;
+        }
+        
+        return $userAttributes;
+    }
+
+}

src/main/edu/wisc/doit/PreauthUserDetailsService.php

+<?php
+
+namespace edu\wisc\doit;
+
+/**
+ * Default implementation of {@UserDetailsAttributeMapper} for use in preauthenticated (Shibboleth) environments.
+ */
+class PreauthUserDetailsService implements UserDetailsService
+{
+
+    /** @var UserDetailsAttributeMapper */
+    private $attributeMapper;
+
+    /**
+     * PreauthUserDetailsService constructor.
+     * @param UserDetailsAttributeMapper|null $mapper
+     */
+    public function __construct(UserDetailsAttributeMapper $mapper = null)
+    {
+        if ($mapper == null) {
+            $this->attributeMapper = new PreauthUserDetailsAttributeMapper();
+        } else {
+            $this->attributeMapper = $mapper;
+        }
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function loadUser()
+    {
+        $userAttributes = $this->attributeMapper->mapUser();
+
+        // Return null if attribute reading failed
+        if ($userAttributes == null) {
+            return null;
+        }
+
+        return new UWUserDetails(
+            $userAttributes[UserDetailsAttributeMapper::EPPN],
+            $userAttributes[UserDetailsAttributeMapper::PVI],
+            $userAttributes[UserDetailsAttributeMapper::FULLNAME],
+            $userAttributes[UserDetailsAttributeMapper::UDDS],
+            $userAttributes[UserDetailsAttributeMapper::EMAIL],
+            $userAttributes[UserDetailsAttributeMapper::SOURCE],
+            $userAttributes[UserDetailsAttributeMapper::ISIS_EMPLID],
+            $userAttributes[UserDetailsAttributeMapper::FIRST_NAME],
+            $userAttributes[UserDetailsAttributeMapper::LAST_NAME]
+        );
+    }
+
+}
\ No newline at end of file

src/main/edu/wisc/doit/UserDetailsAttributeMapper.php

@@ -3,7 +3,7 @@
 namespace edu\wisc\doit;
 
 /**
- *
+ * 
  */
 interface UserDetailsAttributeMapper
 {

src/main/edu/wisc/doit/UserDetailsService.php

@@ -3,12 +3,17 @@
 namespace edu\wisc\doit;
 
 /**
- * Interface UserDetailsService
- * @package edu\wisc\doit
+ * 
  */
 interface UserDetailsService
 {
-    
+
+    /**
+     * Return a {@link UserDetails} hydrated by a {@link UserDetailsAttributeMapper}, or null if attribute
+     * mapping failed.
+     *
+     * @return UserDetails|null
+     */
     public function loadUser();
     
 }
\ No newline at end of file

src/test/edu/wisc/doit/LocalUserDetailsAttributeMapperTest.php

@@ -9,7 +9,7 @@ class LocalUserDetailsAttributeMapperTest extends \PHPUnit_Framework_TestCase
 {
 
     /**
-     * 
+     * Test attribute mapping for local development.
      */
     public function testMapLocalUser() {
         $attributeMapper = new LocalUserDetailsAttributeMapper();

src/test/edu/wisc/doit/PreauthTestCase.php

+<?php
+
+namespace edu\wisc\doit;
+
+/**
+ * Class to do basic setup needed to simulate a logged in Shibboleth user.
+ */
+abstract class PreauthTestCase extends \PHPUnit_Framework_TestCase
+{
+
+    /**
+     * Populate $_SERVER with Shib attributes to simulate a logged in user
+     */
+    protected function setUp()
+    {
+        parent::setUp();
+        $jsonString = file_get_contents(__DIR__ . "/../../../resources/testuser.json");
+        if ($jsonString === false) {
+            return null;
+        }
+
+        $attributes = json_decode($jsonString, true);
+        $_SERVER[UserDetailsAttributeMapper::EPPN] = $attributes[UserDetailsAttributeMapper::EPPN];
+        $_SERVER[UserDetailsAttributeMapper::PVI] = $attributes[UserDetailsAttributeMapper::PVI];
+        $_SERVER[UserDetailsAttributeMapper::FULLNAME] = $attributes[UserDetailsAttributeMapper::FULLNAME];
+        $_SERVER[UserDetailsAttributeMapper::FIRST_NAME] = $attributes[UserDetailsAttributeMapper::FIRST_NAME];
+        $_SERVER[UserDetailsAttributeMapper::LAST_NAME] = $attributes[UserDetailsAttributeMapper::LAST_NAME];
+        $_SERVER[UserDetailsAttributeMapper::UDDS] = $attributes[UserDetailsAttributeMapper::UDDS];
+        $_SERVER[UserDetailsAttributeMapper::EMAIL] = $attributes[UserDetailsAttributeMapper::EMAIL];
+        $_SERVER[UserDetailsAttributeMapper::SOURCE] = $attributes[UserDetailsAttributeMapper::SOURCE];
+        $_SERVER[UserDetailsAttributeMapper::ISIS_EMPLID] = $attributes[UserDetailsAttributeMapper::ISIS_EMPLID];
+    }
+
+}
\ No newline at end of file

src/test/edu/wisc/doit/PreauthUserDetailsAttributeMapperTest.php

+<?php
+
+namespace edu\wisc\doit;
+
+/**
+ * Tests for {@link PreauthUserDetailsAttributeMapper}.
+ */
+class PreauthUserDetailsAttributeMapperTest extends PreauthTestCase
+{
+
+    public function testMapUser() {
+        $attributeMapper = new PreauthUserDetailsAttributeMapper();
+        $userAttributes = $attributeMapper->mapUser();
+        $this->assertEquals("bbadger@wisc.edu", $userAttributes[UserDetailsAttributeMapper::EPPN]);
+        $this->assertEquals("UW123A456", $userAttributes[UserDetailsAttributeMapper::PVI]);
+        $this->assertEquals("BUCKINGHAM BADGER", $userAttributes[UserDetailsAttributeMapper::FULLNAME]);
+        $this->assertEquals("bucky.badger@wisc.edu", $userAttributes[UserDetailsAttributeMapper::EMAIL]);
+        $this->assertEquals("a_source", $userAttributes[UserDetailsAttributeMapper::SOURCE]);
+        $this->assertEquals("123456789", $userAttributes[UserDetailsAttributeMapper::ISIS_EMPLID]);
+        $this->assertEquals("BUCKINGHAM", $userAttributes[UserDetailsAttributeMapper::FIRST_NAME]);
+        $this->assertEquals("BADGER", $userAttributes[UserDetailsAttributeMapper::LAST_NAME]);
+        $this->assertEquals(["UW123A456", "UW234A567"], $userAttributes[UserDetailsAttributeMapper::UDDS]);
+    }
+
+}

src/test/edu/wisc/doit/PreauthUserDetailsServiceTest.php

+<?php
+
+namespace edu\wisc\doit;
+
+/**
+ * Tests for {@link PreauthUserDetailsService}.
+ */
+class PreauthUserDetailsServiceTest extends PreauthTestCase
+{
+
+    public function testLoadUser() {
+        $userService = new PreauthUserDetailsService();
+        $user = $userService->loadUser();
+        $this->assertNotNull($user);
+        $this->assertEquals("bbadger@wisc.edu", $user->getEppn());
+        $this->assertEquals("UW123A456", $user->getPvi());
+        $this->assertEquals("BUCKINGHAM BADGER", $user->getFullName());
+        $this->assertEquals("bucky.badger@wisc.edu", $user->getEmailAddress());
+        $this->assertEquals("a_source", $user->getSource());
+        $this->assertEquals("123456789", $user->getIsisEmplid());
+        $this->assertEquals("BUCKINGHAM", $user->getFirstName());
+        $this->assertEquals("BADGER", $user->getLastName());
+    }
+
+}

src/test/resources/testuser.json

+{
+  "eppn": "bbadger@wisc.edu",
+  "eduWisconsinSPVI": "UW123A456",
+  "cn": "BUCKINGHAM BADGER",
+  "eduWisconsinCommonName": "BUCKINGHAM BADGER",
+  "eduWisconsinGivenName": "BUCKINGHAM",
+  "eduWisconsinSurname": "BADGER",
+  "udds": [
+    "UW123A456",
+    "UW234A567"
+  ],
+  "eduWisconsinEmailAddress": "bucky.badger@wisc.edu",
+  "source": "a_source",
+  "isisEmplid": "123456789"
+}
\ No newline at end of file