Make it easy to subclass Saml2Controller

It is normal to want to extend Saml2Controller,
notably to pass your app's own "redirect URL"
to the Saml2Auth login() call, so that the
RelayState will be set accordingly.

This commit makes it easy to do so by adding
an optional config value that lets you specify the controller.
By default, with no value provided, the routes will
be configured as before, with the default Saml2Controller.

Updates the Readme with example of how to do it.

Author: darynmitchell

README.md

@@ -121,7 +121,27 @@ protected function unauthenticated($request, AuthenticationException $exception)
 }
 ```
 
-The $saml2Controller->login('/my/redirect/path') will redirect the user to the IDP and will came back to an endpoint the library serves at /myidp1/acs (or routesPrefix/myidp1/acs). That will process the response and fire an event when ready. The next step for you is to handle that event. You just need to login the user or refuse.
+For login requests that come through redirects to the login route, 'routesPrefix/myidp1/login', the default login call does not pass a redirect URL to the Saml login request. That login argument is useful because the ACS handler can gets that value (passed back from the IDP as RelayPath) and by default will redirect there. To pass the redirect URL from the controller login, extend the Saml2Controller class and implement your own `login()` function. Set the saml2_settings value `saml2_controller` to be your extended class so that the routes will direct requests to your controller instead of the default.  
+E.g.  
+**saml_settings.php**
+```
+    'saml2_controller' => 'App\Http\Controllers\MyNamespace\MySaml2Controller'
+```
+**MySaml2Controller.php**
+```php
+use Aacotroneo\Saml2\Http\Controllers\Saml2Controller;
+
+class MySaml2Controller extends Saml2Controller
+{
+    public function login()
+    {
+        $loginRedirect = '...'; // Determine redirect URL
+        $this->saml2Auth->login($loginRedirect);
+    }
+}
+```
+
+After login is called, the user will be redirected to the IDP login page. Then the IDP, which you have configured with an endpoint the library serves, will call back, e.g. `/myidp1/acs` or `/routesPrefix/myidp1/acs`. That will process the response and fire an event when ready. The next step for you is to handle that event. You just need to login the user or refuse.
 
 ```php
 

src/config/saml2_settings.php

@@ -60,4 +60,12 @@
     // SSL.
     'proxyVars' => false,
 
+    /**
+     * (Optiona) Which class implements the route functions.
+     * If left blank, defaults to this lib's controller (Aacotroneo\Saml2\Http\Controllers\Saml2Controller).
+     * If you need to extend Saml2Controller (e.g. to override the `login()` function to pass
+     * a `$returnTo` argument), this value allows you to pass your own controller, and have
+     * it used in the routes definition.
+     */
+    'saml2_controller' => '',
 );

src/routes.php

@@ -3,29 +3,31 @@
 Route::middleware(config('saml2_settings.routesMiddleware'))
 ->prefix(config('saml2_settings.routesPrefix').'/')->group(function() {
     Route::prefix('{idpName}')->group(function() {
+	$saml2_controller = config('saml2_settings.saml2_controller', 'Aacotroneo\Saml2\Http\Controllers\Saml2Controller');
+
         Route::get('/logout', array(
             'as' => 'saml2_logout',
-            'uses' => 'Aacotroneo\Saml2\Http\Controllers\Saml2Controller@logout',
+            'uses' => $saml2_controller.'@logout',
         ));
 
         Route::get('/login', array(
             'as' => 'saml2_login',
-            'uses' => 'Aacotroneo\Saml2\Http\Controllers\Saml2Controller@login',
+            'uses' => $saml2_controller.'@login',
         ));
 
         Route::get('/metadata', array(
             'as' => 'saml2_metadata',
-            'uses' => 'Aacotroneo\Saml2\Http\Controllers\Saml2Controller@metadata',
+            'uses' => $saml2_controller.'@metadata',
         ));
 
         Route::post('/acs', array(
             'as' => 'saml2_acs',
-            'uses' => 'Aacotroneo\Saml2\Http\Controllers\Saml2Controller@acs',
+            'uses' => $saml2_controller.'@acs',
         ));
 
         Route::get('/sls', array(
             'as' => 'saml2_sls',
-            'uses' => 'Aacotroneo\Saml2\Http\Controllers\Saml2Controller@sls',
+            'uses' => $saml2_controller.'@sls',
         ));
     });
 });