Prerequisites

You should first setup JOSSO for one of the supported platforms such as Tomcat and JBoss. Check the specific Setup HOW-TO corresponding to the platform where JOSSO is going to be installed.

Once you're done with the initial setup make sure that the JOSSO web application is accessible.

Note
In case of using PHP5 be sure of disabling the native SOAP support in order to avoid conflicts with the SOAP API used by JOSSO.

Introduction

This How-To will explain how to integrate a PHP application with JOSSO Single Sign-On.

It will show how to configure the PHP runtime in order to integrate the PHP Single Sign-On Agent.

It will explain how to develop a PHP JOSSO partner application capable of accessing authenticated user information like username, roles and custom properties.

Configuring

PHP

Next, you should install the JOSSO PHP Agent. In this guide the PHP 4.3.9 version is used, but JOSSO should also work with other PHP releases as well.

To make the integration with PHP as straightforward as possible, you should place the JOSSO files in the PHP include path, and configure the PHP runtime so that JOSSO Agent's files are prepended to every PHP page.

For Win32 systems edit the php.ini file as follows :

...
; Enable php includes
; Windows: "\path1;\path2"
include_path = ".;c:\php\includes"
...
; Automatically add Josso PHP agent before any PHP document.
auto_prepend_file = "josso-lib\josso.php"
auto_append_file =
...

For Unix systems edit the php.ini file as follows :

...
; Enable php includes
; UNIX: "/path1:/path2"
include_path = ".:/php/includes"
...
; Automatically add Josso PHP agent before any PHP document.
auto_prepend_file = "josso-lib/php/josso.php"
auto_append_file =
...

You may have to change the 'include_path' property value if the PHP runtime is installed in a different directory.

Josso PHP Agent

After configuring PHP you must install the JOSSO core files in the include path. The PHP_INCLUDE environment variable must be set to the include_path property value used in the php.ini file.

For Unix systems you can use :

$ export PHP_INCLUDE=/php/includes
$ ./build.sh install-php

For Win32 systems you can use :

set PHP_INCLUDE=c:\php\includes
build.bat install-php

Now we have to install JOSSO PHP pages, copy the files josso-login.php,josso-logout.php and josso-security-check.php to the server content directory, for example /var/www/php/php-partnerapp

For Unix systems you can use :

$ copy $JOSSO_HOME/src/plugins/php/josso-login.php /var/www/php/php-partnerapp
$ copy $JOSSO_HOME/src/plugins/php/josso-logout.php /var/www/php/php-partnerapp
$ copy $JOSSO_HOME/src/plugins/php/josso-security-check.php /var/www/php/php-partnerapp

For Win32 systems you can use :

copy %JOSSO_HOME%\src\plugins\php\josso-login.php C:\Apache\php\php-partnerapp
copy %JOSSO_HOME%\src\plugins\php\josso-logout.php C:\Apache\php\php-partnerapp
copy %JOSSO_HOME%\src\plugins\php\josso-security-check.php C:\Apache\php\php-partnerapp

Make sure to use your partner application content directory instead of the examples above This procedure, which must be executed only once, will copy the necessary files to the $PHP_INCLUDE/josso-lib directory.

The JOSSO PHP Agent configuration file is located in the $PHP_INCLUDE/josso-lib directory.

Let's have a look at the josso-cfg.inc configuration file :

<?php
...

// Josso agent configuration
$josso_gatewayLoginUrl = 'http://localhost/josso/signon/login.do';
$josso_gatewayLogoutUrl = 'http://localhost/josso/signon/logout.do';

...
// This could be also "/", it points to the path where JOSSO code is found, for example for [http://myhost.com/php-partnerapp/josso-security-check.php] use /php-partnerapp.
$josso_agentBasecode = "/php-partnerapp";

// WS client configuration :
$josso_endpoint = 'http://localhost:8080';
...
?>

If you're running Apache in the same host as JOSSO, you should only need to update the josso_gatewayLoginUrl and josso_gatewayLogoutUrl properties, using the PHP server host name instead of 'localhost'.

If JOSSO is located on a different host, you should update the josso_endpoint property as well, setting its value to the JOSSO Gateway host name.

Using this configuration you can set :

• The Gateway Login URL, which represents the URL where the user should be redirected to on protected resource access, so that he has a chance to authenticate itself.
• The Gateway Logout URL, which represents the URL where the user should be redirected on logout request.
• The Gateway endpoint, which represents where the JOSSO Web Services are listening.
• The PHP Agent code base : It should point to the JOSSO agent code, for example for http://myhost.com/php-partnerapp/josso-security-check.php use /php-partnerapp.

Running

Start Apache as usual, and run JOSSO as specified in the Running section of the Setup HOW-TO. After both started succesfully, test your configuration by accessing the JOSSO login form using Apache, i.e. http://myapachehost/josso/signon.do, or, in case you deployed the java samples, try to access the java sample partner application at http://myapachehost/partnerapp/index.jsp .

Developing

Check the PHP Developer HOW-TO here

Comments

Care to comment on this How-To? Help keep this document relevant by passing along any constructive feedback to the josso-docs