Added by Sebastian Gonzalez Oyuela, last edited by Sebastian Gonzalez Oyuela on Mar 09, 2012  (view change)

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

Introduction

This How-To will explain how to build, install, configure and deploy the JOSSO Agent for the Apache Httpd Web Server.

Prerequisites

  • Unix Operating System
  • Apache 2.2.x Httpd Server binaries
  • Apache 2.2.x Httpd Development artifacts
  • Apache Portable Runtime 1.x
  • Working autoconf in the path
  • Working libtool in the path
  • JOSSO Apache 2.2 Agent

Install Apache Development package dependencies

Install the Apache Development package

Install the Apache Development package in case its missing by issuing the following command as root :

$ yum install httpd-devel

Install Apache Portable Runtime

Install the Apache Portable Runtime (APR) package in case its missing by issuing the following command as root :

$ yum install apr-devel

Building

Once the prerequisites are satisfied you can start building the JOSSO Agent for Apache by invoking the autoconf configure script from the josso-apache22-agent-1.8.0 directory. This sources can be found in JOSSO distribution: josso-1.8.0/dist/agents/src/josso-apache22-agent-1.8.0.tar.gz.

First of all, install the required dependencies for the configure shell script to run properly :

$ ./makemake

Generate the build system for the specific operating system :

$ ./configure --with-apache-include=/usr/include/httpd --with-apr-include=/usr/include/apr-1

The --with-apache-include argument should be set to the parent folder of apache include files while the --with-apr-include should point to the APR home folder.

Enable SSL support
In order to use SSL for soap calls, use --enable-openssl as argument to configure.
User can also define following optional arguments:

--with-openssl-includes=/path/to/ssl/includes
--with-openssl-libs=/path/to/ssl/libs
--with-openssl=/path/to/ssl/base
--with-pkg-config='/path/to/pkg-config

If successful, run the building process for creating the Apache module binaries from the corresponding sources :

$ make

Installing

After successfully building the JOSSO Agent Apache Module install it in the Apache Httpd Server directory defined used with the configure script :

$ $APACHE_HOME/bin/apxs -i -a -n auth_josso mod_auth_josso/.libs/libmod_auth_josso.so

Enabling the JOSSO Agent for Apache

In case of using a single file for storing modules configuration, add the following row to the httpd.conf file of the target Apache Httpd Server for loading the JOSSO authentication module :

LoadModule auth_josso_module modules/libmod_auth_josso.so

In case of using a separate directory for storing configuration files for individually packaged modules add a file named josso.conf in the httpd modules configuration directory (e.g. /etc/httpd/conf.d) with this content :

LoadModule auth_josso_module modules/libmod_auth_josso.so

Protect a Web Resource

The Agent configuration and web access control rules should be placed within the configuration file where directory and domain definitions are located (e.g. httpd.conf) .
Let's see an example :

<Directory "/usr/local/apache2/htdocs/protected">
    AuthType JOSSO
    AuthName "MyApacheWeb"
    Require user "user1"
    Require role "role2"
    GatewayLoginUrl "http://localhost:8080/josso/signon/login.do"
    GatewayLogoutUrl "http://localhost:8080/josso/signon/logout.do"
    GatewayEndpoint "localhost" 8080

    SessionAccessMinInterval 60000

    IgnoredResource "images/.*"
    IgnoredResource "css/.*"
    ...
    ...
</Directory>

This directive restricts access to the "/protected" URI and enables the Single Sign-On capability for user "user1" with the "role2" role.

Define public resource
If you want to define public resource (directory) just add
Require sso-session-or-anonymous
to directory element. This will bypass josso security check for that resource.
This is used if you want automatic login for public resource
or you want to access user information from public resource.
Josso 2 configuration
Let's presume you have created appliance named as ApacheTest, service provider sp1 and your execution environment is named Apache20.
If all of these prerequisite are satisfied your configuration should look like:
#define public resource
<Directory "/srv/http/partnerapp/">
    AuthType JOSSO
    AuthName "MyApacheWeb"
    Require sso-session-or-anonymous
    GatewayEndpoint "localhost" 8081
    GatewayLoginUrl "https://localhost:8081/IDBUS/APACHETEST/APACHE20/JOSSO/SSO/REDIR"
    GatewayLogoutUrl "https://localhost:8081/IDBUS/APACHETEST/APACHE20/JOSSO/SSO/REDIR"
    SessionManagerServicePath "IDBUS/APACHETEST/APACHE20/JOSSO/SSOSessionManager/SOAP
    IdentityManagerServicePath "IDBUS/APACHETEST/APACHE20/JOSSO/SSOIdentityManager/SOAP"
    IdentityProviderServicePath "IDBUS/APACHETEST/APACHE20/JOSSO/SSOIdentityProvider/SOAP"
    PartnerApplicationID "sp1"
</Directory>
#define protected resource
<Directory "/srv/http/partnerapp/protected">
    AuthType JOSSO
    AuthName "MyApacheWeb"
    Require user "user1"
    Require role "role2"
    GatewayEndpoint "localhost" 8081
    GatewayLoginUrl "https://localhost:8081/IDBUS/APACHETEST/APACHE20/JOSSO/SSO/REDIR"
    GatewayLogoutUrl "https://localhost:8081/IDBUS/APACHETEST/APACHE20/JOSSO/SSO/REDIR"
    SessionManagerServicePath "IDBUS/APACHETEST/APACHE20/JOSSO/SSOSessionManager/SOAP
    IdentityManagerServicePath "IDBUS/APACHETEST/APACHE20/JOSSO/SSOIdentityManager/SOAP"
    IdentityProviderServicePath "IDBUS/APACHETEST/APACHE20/JOSSO/SSOIdentityProvider/SOAP"
    PartnerApplicationID "sp1"
</Directory>

In case of using a separate directory for storing configuration files for individually packaged modules add the aforementioned definition onto the josso.conf in the httpd modules configuration directory (e.g. /etc/httpd/conf.d).

Running

Run apache httpd server:

$ $APACHE_HOME/bin/apachectl start

When attempting to access "http://myapacheserverhost/protected/" you should be redirected to the configured authentication form for the credentials (e.g. user1/user1pwd).
On successful authentication, you should be redirected back and given access to the requested resource.

Enabling SSL support for back channel transport

This How-To will explain how to enable encrypting of back channel transport.

Create (or provide) certificates

/srv/certificates
keytool -genkey -keyalg RSA -alias server -keystore server.jks -storepass testtest -validity 3600 -keysize 2048
keytool -certreq -alias server -keystore server.jks -file server.csr
keytool -export -alias server -keystore server.jks -file server.crt
keytool -export -alias server -keystore server.jks -rfc -file server.cacert -storepass testtest
keytool
Java Keytool is a key and certificate management utility provided with JDK package.

Turn on SSL on gateway

SSL support on josso1 gateway (tomcat)

$TOMCAT_HOME/conf/server.xml
<!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
<Connector port="8443"
     maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
     enableLookups="false" disableUploadTimeout="true"
     acceptCount="100" debug="0" scheme="https" secure="true"
     clientAuth="false" sslProtocol="TLS" keystoreType="JKS"
     keystoreFile="/srv/certificates/server.jks" keystorePass="testtest"/>
$TOMCAT_HOME/bin/setenv.sh
JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=$CATALINA_HOME/conf/server.jks"
JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStorePassword=testtest"
JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStoreType=jks"

SSL support on josso2 gateway

$JOSSO2_HOME/etc/org.ops4j.pax.web.cfg
#
# SSL Support
#

org.osgi.service.http.secure.enabled=true
org.ops4j.pax.web.ssl.keystore.type=JKS
org.ops4j.pax.web.ssl.keystore=/srv/certificates/server.jks
org.ops4j.pax.web.ssl.password=testtest
org.ops4j.pax.web.ssl.keypassword=testtest
org.osgi.service.http.port.secure=8443

Enable SSL on Josso Apache agent

/etc/httpd/conf/httpd.conf
<Directory "/srv/http/partnerapp/">
   Require sso-session-or-anonymous
   ...
   GatewayEndpoint "localhost" 8443
   ...
   GatewayEndpointSSLEnable On
   EnableGatewayAuthentication On

   SSLServerCertFile "/srv/certificates/server.cacert"
   SSLServerCertDir "/srv/certificates/"
</Directory>

<Directory "/srv/http/partnerapp/protected">
    ...
   GatewayEndpoint "localhost" 8443
   ...
   GatewayEndpointSSLEnable On
   EnableGatewayAuthentication On

   SSLServerCertFile "/srv/certificates/server.cacert"
   SSLServerCertDir "/srv/certificates/"
</Directory> 

Enabling PHP5-specific Security Context Creation

PHP Web Applications relying upon the PHP 5.x-specific security context, realized through the PHP_USER and PHP_PWD apache server variables instead of the apache-specific security context, realized through the REMOTE_USER server variable, are not capable of recognizing the user as authenticated even if a valid SSO session has been established.
Since the password that the user used for authenticating is not available to partner applications, the PHP_PWD value is set to the JOSSO token for the single sign-on session which may be used for obtaining further information about the user through the Gateway's web services.

In order to avoid changing PHP partner applications relying upon the PHP 5.x-specific security context, enable PHP5 security context creation by using the 'PHP5SecurityContext' directive :

<Directory "/usr/local/apache2/htdocs/protected">
    ...
    PHP5SecurityContext On
    ...
</Directory>

In order to verify that this is working deploy and run the following PHP script to the protected resource :

<html>
  <body>
    <table>
    <?
    echo '<tr><td>'.'(PHP_AUTH_USER) is '.$_SERVER['PHP_AUTH_USER'].''.'</td></tr>';
    echo '<tr><td>'.'(PHP_AUTH_PW) is '.$_SERVER['PHP_AUTH_PW'].''.'</td></tr>';
    ?>
    </table>
  </body>
</html>

Comments

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