Building a ZF2 SAML Composer module Part 2

ssplogo-fish-only

Building a ZF2 SAML Composer module

Read Part 1 of Building a ZF2 SAML Composer module

SimepleSAMLphp is a PHP library that helps implement the SAML protocol, but the routing is integrated into the logic. This leads to an interesting design dilemma, we need to expose the SaimpleSAMLphp library to the http stream but we cannot use typical ZF2 routing to do it, at least as fare as I can tell. It should be possible to setup some type of thunk to let routing work; I just don’t have the skill to do it, so we will use a technique I understand well, symbolic linking using the file system. 

According to folklore, the term thunk was coined by the developers of the Algol-60 programming language, who realized late one night that the data type of parameters could be known with a little forethought by the compiler. That is, by the time the compiler processed the parameters, it had already thought of (thunked) the data types. The meaning of the term has changed considerably in recent years. In this case it means integrating an older programming technique into a newer technique.

Getting a copy of the Zend Skeleton Application

Using composer pull a fresh copy of the ZF2 ZendSkeletonApplication.

Open the new website and verity that the skeleton application works.

Screen Shot 2015-06-24 at 2.15.42 PM

Creating your composer package

Next, fork SimpleSAMLphp on GitHub by going forkto https://github.com/simplesamlphp/simplesamlphp and clicking the “Fork” button.

Using GitHub’s edit feature, edit the composer.json file so that it has a unique composer name.  I am going to replace simplesamlphp/simplesamlphp” with “jstormes/simplesamlphp”.

Screen Shot 2015-06-24 at 2.37.47 PM

Commit this back into master, do not create a pull request.

After changing into your application directory, using composer, add your git repository to the composer config file.

You should now be able to search using composer and find your version of SimpleSAMLphp.

Screen Shot 2015-06-24 at 2.55.07 PM

Tell composer to require your new composer package.

If  you look, you should now see the the SimpleSAMLphp package in the /vendor/jstormes/simplesamlphp directory.  You should now be able to work with the SimpleSAMLphp package locally from that directory.

Branching the package

Up to this point we have ben doing all of our modifications in the master branch.  This is was necessary to bootstrap our composer package.  But developing in the master branch is never a good idea.  So now is a good time to make a development branch.

Change into the SimpleSAMLphp directory, in my case it is /vendor/jstormes/simplesamlphp and run the command:

Edit the composer.json file, adding your name to the authors array and your issue tracker to to the support array.

These changes let us take ownership of this fork of SimpleSAMLphp.  While cosmetic in nature, this is the starting point of our code changes to truly integrate with SimpleSAMLphp with Zend Framework 2.

Commit these changes and push our new brach up to the repository:

Our new brach is now committed to the remote repository.

Finally we tell composer to use our development branch of SimpleSAMLphp:

If all went well you should have your own composer ready branch that you can develop locally.

SAML Routing

While we have indeed pulled the SimpleSAMLphp code into a ZF2 Skeleton, there is no way for the SimpleSAMLphp code to run.  At the beginning of the post I talked about how routing the saml related requests using a symbolic link.  This technique is used on Linux/Unix based system.  I have not tried this on a Windows based system, although some similar technique should apply.

From the /public directory run:

Now if you open (website)/saml you should get :

Saml routed inside a ZF2 Skeleton

Autoloading

Now that SimpleSAMLphp is routed, we need to setup autoloading so that the SimpleSAMLphp library can be used from ZF2 and ZF2 can be used from SimpleSAMLphp.

Edit the composer.json file and change the “autoload” array:

After changing the autoload setting you will need to tell composer to regenerate autoloading.

NOTE: Dumping the autoload is done frequently while developing composer modules. If you are having issues with the ZF2 finding code in your modules, start by dumping the current autoload and watch for errors.

Module.php

The file vendor/jstormes/simplesamlphp/Module.php is loaded by the ZF2 Skeleton with every page load.  When the SimpleSAMLphp module is enabled in application.config.php, this file will be called.  This is where SimpleSAMLphp will be linked into ZF2.

_include.php

The file vendor/jstormes/simplessamlphp/www/_include.php is loaded when a SAML IdP request is made.  This is where we will link SimpleSAMLphp back into ZF2 so we can call ZF2 code from SimpleSAMLphp.

At the top of the file include:

Configuring SimpleSAMLphp

Create the configuration directories

Copy the templates

Creating the SSL self signed certificate:

Enable exampleauth module

Configuring the exampleauth module:

Edit the file config/authsources.php and uncomment the following lines, near line 86:

Enabling the Identity Provider functionality

Edit config/config.php and set enable.saml20-idp to true, around line 207.

Setting the baseurlpath

Still in config/config.php change ‘baseurlpath’ to saml.

Configuring the IdP

Edit metadata/saml20-idp-hosted.php, be sure to replace zf2-test1.stormes.net with your server.

Committing into git

We don’t want our cert getting committed back into our git repo so now is a good time to ignore the cert directory before we commit our changes.  Edit the .gitignore file in /vendor/jstormes/simplesamlphp and add cert and optional our config and metadata directories.

From the /vendor/jstormes/simplesamlphp directory commit all your changes back into composer.

Enabling the module in ZF2

In config/application.config.php add the SimpleSAMLphp module to the modules array.

Logging in

Now if you open the website you should get redirected to the SAML login page.

If you use one of the user ids from the config/authsources.php file, you should be able to login. (student, studentpass or employee, employeepass).

SAML Login screen from redirect

SAML Login screen from redirect.

ZF2 Skeleton After SAML login

ZF2 Skeleton After SAML login

Conclusion

This has been a very heavy post, covering allot ground, composer, autoloading, and integrating legacy code into a modern framework.  Admittedly, this took allot longer than expected, but going forward, we have a well testing SAML implementation for ZF2 in composer.

In the next posts we will go over how to build a new web app that uses our single sign on, and will tackle authorization vs authentication and where to store the details on our users.

References

https://simplesamlphp.org/
https://github.com/zendframework/zf2
http://framework.zend.com/
https://getcomposer.org/doc/

No Responses

Leave a Reply