PERMIS SAAM Installation Cookbook

PERMIS Shibboleth Apache Authorisation Module (SAAM) Installation Cookbook

Part 2 - Apache Instructions

Authors: David W. Chadwick, Wensheng Xu, Alexander Otenko

Release Number	Date	Comments
1.0	23 November 2004	Initial public release
1.1	6 July 2006	Release with Modular PERMIS
1.2	15 July 2006	Step 7 modified
1.3.0	18 July 2006	Windows support is added
1.3.1	28 July 2006	PE is used for policy instead of ACM; mod_permis should be recompiled
1.3.2	14 August 2006	Policy in a plain text XML file is used
1.4	11 August 2008	Using the o=PERMISv5,c=GB entry in the Kent LDAP

Table of Contents

· Introduction

· 1 Before you start

· 2 Installation steps

· 3 For advanced users

· 4 For Windows users

· 5 Using SAAM with policy files stored in LDAP

· 6 Possible problems for SAAM

· Appendix B - The configuration file for LDAP at Kent University

· Appendix C - Test Policy

· Support and Contact Points

Introduction

The PERMIS Shibboleth Apache Authorisation Module (SAAM) is essentially an Apache module that uses PERMIS to control access to websites that use either Apache or Shibboleth to provide user authentication. Part 1 of this cookbook shows you how to implement the PERMIS SAAM with Shibboleth authentication. Part 2 shows you how to implement the PERMIS SAAM with Apache authentication. On completion of this cookbook, you will be able to install and setup all the necessary components for using the PERMIS SAAM with either Shibboleth or Apache.

In this Part 2 of the cookbook, PERMIS will work in pull mode to retrieve the X.509 attribute certificates (ACs) of a user from one or more specified LDAP servers and make an access decision based on these ACs. The PERMIS policy may be stored either in the LDAP entry of the policy writer (who is called the Source of Authority or SoA) as a digitally signed policy AC, or in the filestore of the Shibboleth target machine as a simple text file containing the XML policy. The PERMIS Policy Editor is able to create both of these policy formats.

1 Before you start

You will need to have the following components before you start to install PERMIS with Apache.

Running systems

The following systems should be installed and working prior to installing PERMIS:

1.      An Apache web server (version 1.3 or 2.0) with DSO support.

2.      An LDAP server that you have write access to (this is needed to hold PERMIS policy ACs and user X.509 ACs). The public LDAP server at Kent ldap://sec.cs.kent.ac.uk can be used for testing purposes but you will only have read access to this.

3.      Java Runtime Environment - required to run the PERMIS software. The version of JRE you need is 1.4. JRE is available from:
http://java.sun.com/

PERMIS Policy Management System

In order to create and manage PERMIS policies, you will need the following:

1.      An XML policy creating tool. The PERMIS Policy Editor tool can be used for this. A test policy policy1.xml is provided with the installation kit but you will need to modify this after installation to suit your own operational environment.

2.      An optional X.509 private signing key for signing your policies. The key file permisv5.p12 is provided in the installation kit and can be used for testing purposes, but it should be replaced by your own key pair before your system goes live. The password for this p12 file is (starts with lowercase "L", not number "1"):

l3tM3InNow

If you are without an X.509 private signing key, you can still use PERMIS policies in plain XML text format.

X.509 Attribute Certificate Handling System

In order to create and manage user X.509 attribute certificates you will need the following:

1.      A tool for creating user attribute certificates. The PERMIS Attribute Certificate Manager (ACM) tool can be used for this.

2.      Optionally a tool for bulk loading lots of user attribute certificates into an LDAP directory. The PERMIS Bulk Loader can be used for this. 

The SAAM Installation kit

The Kent SAAM Installation kit comprises the following items:

1.      The PERMIS Java classes library saam.jar for the Apache server site

2.      The source code for the mod_permis modules in the sub directory <mod_permis_src>:

o        C++ source code mod_apache_permis.cpp for both mod_permis_13.so and mod_permis_20.so

o        C++ source code mod_permis_13.cpp for mod_permis_13.so

o        C++ source code mod_permis_20.cpp for mod_permis_20.so

o        C source code permisJNI.c for the JNI interface

o        header file permis.h for the above files

o        Make file make13.sh for making mod_permis_13.so

o        Make file make20.sh for making mod_permis_20.so

o        Run make13.sh (for Apache 1.3) or make20.sh (for Apache 2.0) in it, then you'll get 2 new files: mod_permis_13.so (for Apache 1.3) or mod_permis_20.so (for Apache 2.0). Modifications to scripts make13.sh (for Apache 1.3) or make20.sh (for Apache 2.0) may be needed according to your local operating systems (e.g. paths to headers that Apache or JRE need should match those on your system).

3.      A modified Apache authentication module mod_auth_ldap mod_auth_ldap.tar.gz is provided separately at http://sec.cs.kent.ac.uk/permis/downloads/mod_auth_ldap.tar.gz. We have modified the original mod_auth_ldap so it can output the DN of a user to the HTTP header with the header name of "User-Distinguished-Name". Please note that though we provide mod_auth_ldap for your convenience, it's not our software and it is developed by the Apache Group for use in the Apache HTTP server project (http://www.apache.org/). The original mod_auth_ldap and its manuals can be obtained from:
http://www.muquit.com/muquit/software/mod_auth_ldap/mod_auth_ldap.html.

4.      A digitally signed PERMIS Test Policy, the file name is policy1.ace. (This is a digitally signed version of the PERMIS Test Policy.) It is also stored in the Kent LDAP server at ldap://sec.cs.kent.ac.uk/  in the entry of the policy issuer. The policy issuer is: cn=A Permis Test User,o=permisv5,c=gb, the policy identifier is: 1.2.826.0.1.3344810.6.0.0.11 ^[1] ; and a signature verification X.509 Public Key Certificate APermisTestUser.cer which is signed by RootCA for cn=A Permis Test User,o=permisv5,c=gb, it can be used to validate policy1.ace.

5.      The raw (unsigned) PERMIS Test Policy. It's source filename is policy1.xml.

6.      An X.509 signing key pair, filename permisv5.p12, private key password l3tM3InNow. The subject name of the X.509 public key certificate is cn=A Permis Test User,o=permisv5,c=gb.

7.      A signature verification X.509 Public Key Certificate cacert.cer. It is needed to validate the PKC used to sign the test policy.

8.      Two test users' X.509 attribute certificates User0.ace and User1.ace. They are also stored in the Kent LDAP server in the attrbuteCertificateAttribute attribute of entries cn=User0,o=permisv5,c=gb and cn=User1,o=permisv5,c=gb

9.  A ldif file ldif.zip for the entries of User0, User1, A PERMIS Test User for the test LDAP.

10.  One IAIK library iaik_jce.jar. This library is needed for running PERMIS. Please note that though this library is included in this package for your convenience, it is not our software and belongs to IAIK.

11. One log4j library log4j-1.2.13.jar. This library is needed for running PERMIS. Please note that though this library is included in this package for your convenience, it is not our software and belongs to the Apache Software Foundation.

12. One Apache AXIS library axis.jar. This library is needed for running PERMIS. Please note that though this library is included in this package for your convenience, it is not our software and belongs to the Apache Software Foundation.

13. LDAP support iPlanet C SDK 5.08 DLL files in subdirectory <SunDLLs> necessary for the running of mod_auth_ldap in Windows. Please note that though these library files are included in this package for your convenience, it is not our software and belongs to Sun Microsystem.

14.  Two text files in accordance with the Apache licence: LICENSE and NOTICE.

15.  The Installation Cookbook (this document)

The following items are also available in this PERMIS SAAM installation package, but they are only used for Part 1 of this cookbook and not used here.

16.  Two modified Shibboleth origin module JNDIDirectoryDataConnector.class and Base64ValueHandler.class

17.  Three Shibboleth configuration files for Shibboleth attribute release and acceptance policies used in our testing environment for your reference: AAP.xml, arp.site.xml, resolver.ldap.xml in the sub directory </confExample>.

The SAAM installation kit is available at:

http://sec.cs.kent.ac.uk/permis/private/saam/saam.zip

Download the SAAM installation kit, unzip saam.zip to a directory in the target computer, say </home/target/saam> then you'll see the items listed above.

2 Installation steps

Installation will proceed as follows:

Install PERMIS using the default policies and systems provided by Kent

In this stage you will install the PERMIS software on your system, using a test policy and attribute certificates provided by Kent on its LDAP server.

Step 0. Make sure that Apache server is installed and working correctly on your machine.

DSO needs to be enabled for the Apache server. For enabling DSO in the Apache server, see the Apache DSO documentation at http://httpd.apache.org/docs/1.3/dso.html or http://httpd.apache.org/docs/2.0/dso.html. After Apache is working correctly on your machine, in your Internet browser, try to access http://localhost, it will display the default Apache homepage. 

Tips:

For compiling and installation of the Apache server, please refer to the Apache documentation in the Apache release package. For your reference, the commands we used to compile and install Apache are: 

For Apache 2.0:

./configure --prefix=APACHE_HOME --enable-so --enable-mods-shared=all --enable-proxy
make 
make install

For Apache 1.3:

./configure --prefix=APACHE_HOME --enable-rule=SHARED_CORE --enable-module=proxy --enable-shared=proxy
make
make install

  APACHE_HOME should be your intended Apache home directory. You may need to change the above directives in your own system.  

Step 1. Install the modified mod_auth_ldap provided in this installation kit

Please make sure now the two system environment variables JAVA_HOME and APACHE_HOME are correctly configured to refer to your Java home directory and Apache home directory respectively. (Tips: To find APACHE_HOME on your computer, type 'whereis apache' for Apache 1.3 or 'whereis apache2' for Apache 2.0. To find the LDAP_DIR, type 'whereis openldap').

Unzip mod_auth_ldap.tar.gz, then enter the mod_auth_ldap3.0 sub directory and run the following 3 commands:

./configure --with-apxs=APACHE_HOME/bin/apxs --with-ssl=no --with-ldap-dir=LDAP_DIR --with-apache-dir=APACHE_HOME --with-apache-ver=2 (For Apache 2.0)
or
./configure --with-apxs=APACHE_HOME/bin/apxs --with-ssl=no --with-ldap-dir=LDAP_DIR --with-apache-dir=APACHE_HOME --with-apache-ver=1 (For Apache 1.3)
make
make install

In the above commands APACHE_HOME should be your Apache server home directory, and LDAP_DIR is the home directory for your LDAP header files and libraries, we assume your LDAP headers and libraries are in <LDAP_DIR/include> and < LDAP_DIR /lib> respectively. Normally LDAP_DIR is /usr in the Linux system, but it may differ in your system. If you install your LDAP in other directory, then edit the above command accordingly.

If you are using Apache 2.0, then this command will compile and install the mod_auth_ldap to your Apache 2.0 server system.

About the installation and configuration of mod_auth_ldap, please refer to the original author's website.

Expected result:

If you want to make sure this step is done correctly, you can do the following steps:

(1) In the directory <APACHE_HOME/htdocs>, make a location <apachesecure> in it; copy the file APACHE_HOME/htdocs /index.html.en to APACHE_HOME/htdocs/apachesecure/index.html;

(2) Insert the following directives into the Apache configuration file httpd.conf.

<Location /apachesecure>
 AuthType Basic
 AuthName "Protected only by Apache authn"
 LDAP_Server 129.12.3.197 -------------- Note: This is the IP address of ldap://sec.cs.kent.ac.uk at Kent University.
 LDAP_Port 389
 Base_DN "c=gb"
 UID_Attr uid 
require valid-user
 Options Indexes FollowSymLinks
 AllowOverride None
 order allow,deny
 allow from all
</Location>

(3) Restart Apache server, in your browser, visit http://localhost/apachesecure, you will be prompted to input your user name and password. Input 'User0' and 'User0' respectively, if you can see the apache homepage, then you can make sure mod_auth_ldap has been correctly installed.

Step 2. Copy files in your computer

a.       In your computer, for Apache 1.3 users, copy the file mod_permis_13.so to <APACHE_HOME/libexec/>;
for Apache 2.0 users, copy mod_permis_20.so to <APACHE_HOME/modules/>, where <APACHE_HOME> is the directory, to which your Apache is installed.

b.      Copy the file saam.jar to <JAVA_HOME/jre/lib/ext/>, where JAVA_HOME is your Java home directory.

c.       Copy the file iaik_jce.jar into <JAVA_HOME/jre/lib/ext/>.

d. Copy the file log4j-1.2.13.jar into <JAVA_HOME/jre/lib/ext/>.

e. Copy the file axis.jar into <JAVA_HOME/jre/lib/ext/>.

f.      Copy the file cacert.cer into <APACHE_HOME/conf/>

g. Copy the file policy1.xml into <APACHE_HOME/conf/>

Please make sure the above files are readable on your system. If not, you need to change their file permissions by performing:

chmod 644  *.jar 

or 

chmod 644 *.so 

Step 3: Update the Computer Environment Variables LD_LIBRARY_PATH

On your computer, run the following command to update the environment variable: LD_LIBRARY_PATH

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JAVA_HOME/jre/lib/i386/client:$JAVA_HOME/jre/lib/i386

This will allow the Java virtual machine and the JNI support classes to be found by JNI when they are called by the mod_permis module. In this command JAVA_HOME is the environment variable of the computer system referring to the Java home directory.

Step 4. Change the Apache configuration file in the computer.

Insert the following directives into the Apache configuration file httpd.conf.

LoadModule mod_permis APACHE_HOME/libexec/mod_permis_13.so ---------------[directive N1,1 for Apache 1.3 only]
PermisPolicyLocation APACHE_HOME/conf/policy1.xml ----------------[directive SN4]
PermisRootCA APACHE_HOME/conf/cacert.cer ---------------------------------[directive N5]
PermisJavaClass “.:JAVA_HOME/jre/lib/ext/saam.jar:JAVA_HOME/jre/lib/ext/iaik_jce.jar:JAVA_HOME/jre/lib/ext/axis.jar:JAVA_HOME/jre/lib/ext/ log4j-1.2.13.jar “-----[directive N8]
PermisACAttribute attributeCertificateAttribute---------------------------[directive N9]
PermisPKCAttribute userCertificate;binary ---------------------------------------[directive N10]
<Location /public>
</Location>
<Location /secure2>
 AuthType Basic
 AuthName "Protected by both Apache authn and PERMIS authz"
 PermisAuthorization --------------------------------------------------[directive N6]
 PermisPullMode -------------------------------------------------------[directive N7]
 LDAP_Server 129.12.3.197 -------------- Note: This is the IP address of ldap://sec.cs.kent.ac.uk at Kent University.
 LDAP_Port 389
 Base_DN "c=gb"
 UID_Attr uid
 require valid-user
 Options Indexes FollowSymLinks
 AllowOverride None
 order allow,deny
 allow from all
</Location>

Also insert the following directive into the Apache configuration file httpd.conf. if you have not done so in Step 2.

<Location /apachesecure>
 AuthType Basic
 AuthName "Protected only by Apache authn"
 LDAP_Server 129.12.3.197 -------------- Note: This is the IP address of ldap://sec.cs.kent.ac.uk at Kent University.
 LDAP_Port 389
 Base_DN "c=gb"
 UID_Attr uid
 require valid-user
 Options Indexes FollowSymLinks
 AllowOverride None
 order allow,deny
 allow from all
</Location>

Please note if you are using Apache 1.3, then you should use [directive N1.1] with mod_permis_13.so; but if you are using Apache 2.0, then you should use [directive N1.2] with mod_permis_20.so to replace [directive N1.1]:

LoadModule mod_permis APACHE_HOME/modules/mod_permis_20.so ---------------[directive N1.2 for Apache 2 only]

PermisPolicyLocation is the location of the XML file which contains the PERMIS policy. PermisRootCA is the root authority public key certificate for authenticating attribute certificates that are signed by this root authority.  PermisJavaClass is to tell the SAAM module where to find the SAAM Java classes.

You may also need to add or remove PermisACAttribute and PermisPKCAttribute directives. They specify the attribute types for X.509 Attribute Certificate and X.509 Public Key Certificate respectively. You may need to change the type from the default one, since some OpenLDAP versions require ";binary" suffix, some refuse to handle attributes with this suffix for attributeCertificateAttribute and userCertificate attributes. For example, you may need to specify:

PermisACAttribute attributeCertificateAttribute
PermisPKCAttribute userCertificate

If PermisACAttribute or PermisPKCAttribute is missing from httpd.conf, then the default value for them is attributeCertificateAttribute;binary or userCertificate;binary respectively.

In the above configurations APACHE_HOME should be your Apache home directory.

In the directory <APACHE_HOME/htdocs>, please create three locations <public>, <secure2> and <apachesecure> and copy the file APACHE_HOME/htdocs /index.html.en to them respectively for testing purposes. The above configurations set up three locations </public>, </secure2> and </apachesecure>. </public> is a public access location, </apachesecure> is only protected by the Apache authentication provided by mod_auth_ldap, but </secure2> is protected by both Apache authentication and PERMIS authorisation because [directive N6] exists for this location. [directive N1] to [directive N5] are configurations for the PERMIS SAAM and apply to all locations protected by PERMIS. Because PERMIS needs to work in pull mode when integrated with Apache, the directive PermisPullMode must exist in the Apache configuration file in the locations that need to be protected by PERMIS.

Introduction to the Kent LDAP:

The Kent University LDAP server (ldap://sec.cs.kent.ac.uk, IP address 129.12.3.197 ) is used for authentication in this example for testing purposes. There are 3 test users in the LDAP for this cookbook. (The LDIF of the entries is provided in ldif.zip). Each user has the following attributes:

cn, sn, uid, userPassword, attributeCertificateAttribute, objectClass: person, objectClass: pmiUser, objectClass: top.

The attributes for user User0 are shown in Figure 1. For User0:

dn: cn=User0,o=permisv5,c=gb
cn: User0
uid: User0
sn: User0
userPassword: User0
attributeCertificateAttribute: the contents of User0.ace

So for User0, the username/password is: User0/User0.

For User1:

dn: cn=User1,o=permisv5,c=gb
cn: User1
sn: User1
uid: User1
userPassword: User1
attributeCertificateAttribute: the contents of User1.ace

So for User1, the username/password is: User1/User1.

For A PERMIS Test User:

dn: cn=A PERMIS Test User,o=permisv5,c=gb
attributeCertificateAttribute: the contents of policy1.ace

Please note that the third user A PERMIS Test User in this LDAP can be used for holding the PERMIS access control policy (policy1.ace) as the attribute attributeCertificateAttribute.

Figure 1. Viewing the User0 entry in LDAP

Step 5. Testing

You have set up an Apache-PERMIS protected location </secure2> and an Apache protected location </apachesecure> in the above Step 4. So now you have got altogether 3 locations:

*         /public: without any authentication and authorisation

*         /apachesecure: with Apache mod_auth_ldap authentication and authorisation

*         /secure2: with Apache mod_auth_ldap authentication and PERMIS authorisation

Note that the above configuration is for installation and testing purposes only, to ensure that all components are working as expected, without interfering unexpectedly with each other.

Now you will need to restart Apache on the computer. Using a web browser, attempt to access the following URLs in turn:

*         http://your_target_website/public: You should find that this is publicly available and that no authentication or authorization is needed to access it.

*         http://your_computer_website/apachesecure: This is your Apache module mod_auth_ldap protected location. You will then be asked to log in and you can use the username/password User0/User0 or User1/User1 to be authenticated, and you will be given access to this location because your current Apache configuration for this location is "require valid-user".

*         http://your_target_website/secure2: You should be able to access the page by first logging in using the username/password User0/User0. In the background the system will have

                                 i.            checked that you are authenticated

                               ii.            retrieved your X.509 attribute certificates and

                              iii.            checked that these credentials are sufficient for you to have access to the protected page according to the PERMIS policy stored inside the XML policy file. You will not be able to access this location by using User1/User1 according to the PERMIS policy.

You have now correctly installed the PERMIS authorization components on your system.

Migrate to using your own PERMIS system

In this stage you will migrate to using your own Authentication System, your own policy store (LDAP server or filestore), your own PERMIS policy, and your own attribute certificates.

Step 6. Firstly migrate to your own authentication system and LDAP.

You are using the Apache server and the Apache authentication module, so do the following.

6.1 Configure the httpd.conf for Apache in your computer to authenticate users

Change the directives in httpd.conf for Apache in the computer as follows:

<Location /secure2>
 Options Indexes FollowSymLinks
 AllowOverride None
 Order allow,deny
 Allow from all
 PermisAuthorization --------------------------------------------------[directive N6]
 PermisPullMode -------------------------------------------------------[directive N7]
 AuthName "Protected by both Apache authn and PERMIS authz"
 AuthType Basic
 LDAP_Server 129.12.3.197 ---------- Note: Change this to the IP address of your own ldap server, say the IP address of ldap.myuniv.ac.uk
 LDAP_Port 389
 Base_DN "c=gb" ------------------------- Note: You may need to change this depending upon your own LDAP 
tree structure 
UID_Attr uid ---------------------Note: You may need to change this depending upon the attribute you use for authentication
 Require valid-user
</Location>

6.2 Configure your own authentication ldap

For your authentication LDAP server, you should set 3 testing users: User0, User1, A PERMIS Test User. Each user has the following attributes:

cn, sn, uid, userPassword, attributeCertificateAttribute (optional), objectClass: person, objectClass: pmiUser (optional), objectClass: top.

For User0:

dn: cn=User0,o=permisv5,c=gb
cn: User0
uid: User0
userPassword: User0
attributeCertificateAttribute: the contents of User0.ace

So for User0, the username/password is: User0/User0.

For User1:

dn: cn=User1,o=permisv5,c=gb
cn: User1
uid: User1
userPassword: User1
attributeCertificateAttribute: the contents of User1.ace

So for User1, the username/password is: User1/User1.

For A PERMIS Test User:

dn: cn=A PERMIS Test User,o=permisv5,c=gb
attributeCertificateAttribute: the contents of policy1.ace

You can change the userPassword for both User0 and User1 to anything you like.

About how to create attribute certificates and input them into LDAP, please download and use the PERMIS Attribute Certificate Manager software.

About how to configure mod_auth_ldap, please refer to http://httpd.apache.org/docs-2.0/mod/mod_auth_ldap.html.

The LDAP configuration file for our LDAP server at Kent is in Appendix B.

Replay the testing step 5 above. You should have now authenticated with your own LDAP server, using usernames and passwords stored in it, and gained access to the protected pages. But you are still using the PERMIS policy stored in the policy1.xml file at the moment.

Step 7. Secondly replace the test XML policy with your own.

In order to change your policy you should first create/modify an XML text policy file. You can either edit the XML by hand or use the PERMIS Policy Management GUI. Once the policy is complete change the PermisPolicyLocation directive in the Apache configuration to point towards your policy file and restart the Apache server.

Step 8. Finally, create new user attribute certificates so that users can gain access to the resources protected by your new PERMIS policy.

About how to create attribute certificates and input them into your LDAP server, please use the PERMIS Attribute Certificate Manager (ACM) tool.

3 For advanced users

Once you are familiar with the PERMIS SAAM, you can set advanced directives in the Apache configuration file or modify the PERMIS policy file to let the PERMIS SAAM work in advanced mode.

Debug Mode

You can set a debug directive in the Apache configuration file to let the PERMIS SAAM output debug information. There are six different levels of Debug statements OFF,FATAL,ERROR,WARN,INFO and DEBUG. In order to use debug mode you should insert one of the following directives

PermisDebug off,
PermisDebug fatal,
PermisDebug error,
PermisDebug warn,
PermisDebug info

or

PermisDebug debug

into the Apache configuration file after [directive N4]. This will switch on different levels of PERMIS debugging. The debug information for the mod_permis module will be outputed to a file called mod_permis.log and the debug information for the Java SAAM module will be outputed to permis.log in Apache’s logs directory. Unless specifically stated by the user then the logging of debug statements is always enabled.

The six levels of debugging are as follows:

off ﾨC Debugging is turned off

fatal ﾨC prints out serious error messages that will lead to the program terminating

error ﾨC prints out serious non fatal errors

warn ﾨC prints outs less important errors 

info - prints out some intermediate results in the PERMIS SAAM;

debug - prints out all the verbose debug information in the PERMIS SAAM. 

Debug information

The SAAM software currently uses two log files APACHE_HOME/logs/mod_permis.log for logs originating from the mod_permis apache module and the PERMIS log APACHE_HOME/logs/permis.log for logs originating from saam.jar. If you encounter some problems in installing saam then you may see the following error messages in the APACHE_HOME/logs/mod_permis.log.

  (1) "JNI_CreateJavaVM failed, returned value -1"

This error message indicates that your Java virtual machine is not correctly configured to your Apache server. You may need to check that the following command is correctly executed.

  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JAVA_HOME/jre/lib/i386/client:$JAVA_HOME/jre/lib/i386

  Then you need to make sure you have correctly set PermisJavaClass in httpd.conf:

PermisJavaClass “.:JAVA_HOME/jre/lib/ext/saam.jar:JAVA_HOME/jre/lib/ext/iaik_jce.jar:JAVA_HOME/jre/lib/ext/axis.jar:JAVA_HOME/jre/lib/ext/ log4j-1.2.13.jar “-----[directive N8]

(2) "Class ShibPermisRBAC was not found"

If you see this error message, then you need to make sure that saam.jar is correctly placed in <JAVA_HOME/jre/lib/ext>.

You may also see the following error messages in the Permis error log APACHE_HOME/logs/permis.log, if you encounter some problems in installing saam.

(3) "Failed to initialise:  Could not initialise

Embedded: issrg.pba.PbaException: No Policy with OID 1.2.826.0.1.3344810.6.0.0.11 has been found for CN=A Permis Test User,O=permisv5,C=gb SOA (No ACs have been retrieved) "

  This problem could be caused by several possible reasons.

  a. Some LDAP systems support, but some do not support the LDAP name suffix. So in the following directive in httpd.conf:

  PermisPolicyLocation ldap://sec.cs.kent.ac.uk ---------------------------------------------------------[directive N4]

  try to add the suffix (for the Kent LDAP, it is /c=gb) to it (i.e. ldap://sec.cs.kent.ac.uk/c=gb).

  b. You have not correctly specified the Policy ID in the following directive in httpd.conf:

PermisPolicyIdentifier 1.2.826.0.1.3344810.6.0.0.11 -------------------------------------------------[directive N2] 

PERMIS AC Repositories

When working in PERMIS pull mode, PERMIS needs to be told where to fetch attribute certificates from. There are two methods in the PERMIS SAAM to configure the AC LDAP locations.

(1) To configure AC LDAP locations in the Apache configuration file.

In the Apache configuration file, add the directive PermisACLocation to define the AC LDAP locations:

LoadModule mod_permis APACHE_HOME/libexec/mod_permis_13.so --[directive N1,1 for Apache 1.3 only]
PermisPolicyLocation APACHE_HOME/conf/policy1.xml ------------------------------------[directive N4]
PermisRootCA APACHE_HOME/conf/cacert.cer -----------------------------------------[directive N5]
PermisJavaClass ".:JAVA_HOME/jre/lib/ext/saam.jar:JAVA_HOME/jre/lib/ext/iaik_jce.jar"--[directive N8]
PermisACAttribute attributeCertificateAttribute------------------------------------[directive N9]
PermisPKCAttribute userCertificate ------------------------------------------------[directive N10]
PermisACLocation ldap://site1.ac.uk/ ----------------------------------------------[directive N11]
PermisACLocation ldap://siteN.ac.uk/ -----------------------------------------------[directive N12]

Please note if you are using Apache 1.3, then you should use [directive N1.1] with mod_permis_13.so; but if you are using Apache 2.0, then you should use [directive N1.2] with mod_permis_20.so to replace [directive N1.1]:

LoadModule mod_permis APACHE_HOME/modules/mod_permis_20.so ---------------[directive N1.2 for Apache 2 only]

Multiple LDAP locations can be specified by using the directive PermisACLocation multiple times. PERMIS will now fetch (pull) X.509 attribute certificates from the locations specified in the PermisACLocation directive [directives N8 and N9].

Note. If the PermisACLocation directive is not specified with the PermisPullMode directive and a X.509 policy file stored in LDAP is used, then PERMIS will try to pull the X.509 Attribute Certificates from the same repository as the PermisPolicyLocation [directive N4] , or from the repositories specified by the PERMIS repository sub policy. If both the PermisACLocation directive and the PERMIS repository sub policy are specified, then PERMIS will fetch ACs from all the locations.

(2) To configure AC LDAP locations in the PERMIS policy file.

In the PERMIS policy file, add a new repository policy section to it:

<RepositoryPolicy>
 <Repository URL="ldap://site1.ac.uk"/>
 <Repository URL="ldap://site2.ac.uk"/>
</RepositoryPolicy>

PERMIS will now fetch (pull) X.509 attribute certificates from the locations specified by the repository policy in the PERMIS policy file.

Note when PERMIS SAAM works with the Apache authentication module, the PermisPullMode directive in the Apache configuration file should always exist in the locations to be protected. If the PermisPullMode directive is missing, then PERMIS will not protect that location.  

4 For Windows users

We assume that you are working in Linux environment in the above manual. But if you are using the Apache server 2.0 in Windows environment, you need to follow the instructions as follows.

1. From the SAAM package, copy mod_auth_ladp20.dll, mod_permis_20.dll and all the dll files in the sub directory <SunDLLs> to <APACHE_HOME/modules>; copy rootca.cer and policy1.xml to <APACHE_HOME/conf>; copy saam.jar, axis.jar, log4j-1.2.13.jar and iaik_jce.jar to <JAVA_HOME\jre\lib\ext>. The Sun DLL files are necessary for the loading of mod_auth_ldap in the Apache server in Windows.

2. For testing with the Kent LDAP, add the following directives into httpd.conf:

LoadModule mm_auth_ldap_module modules\mod_auth_ladp20.dll
LoadModule mod_permis modules\mod_permis_20.dll --[directive N1.1 for Apache 2]
PermisPolicyLocation APACHE_HOME\conf\policy1.xml ----------------------------------[directive N4]
PermisRootCA APACHE_HOME\conf\cacert.cer ---------------------------------------[directive N5]
PermisJavaClass ".;JAVA_HOME\lib\ext\saam.jar;JAVA_HOME\lib\ext\iaik_jce.jar"-----[directive N8]
PermisACAttribute attributeCertificateAttribute----------------------------------[directive N9]
PermisPKCAttribute userCertificate ----------------------------------------------[directive N10]
<Location /public>
</Location>
<Location /apachesecure>
 AuthType Basic
 AuthName "Protected only by Apache authn"
 LDAP_Server 129.12.3.197 -------------- Note: This is the IP address of ldap://sec.cs.kent.ac.uk at Kent University.
 LDAP_Port 389
 Base_DN "c=gb"
 UID_Attr uid
 require valid-user
 Options Indexes FollowSymLinks
 AllowOverride None
 order allow,deny
 allow from all
</Location>
<Location /secure2>
 AuthType Basic
 AuthName "Protected by both Apache authn and PERMIS authz"
 PermisAuthorization --------------------------------------------------[directive N6]
 PermisPullMode -------------------------------------------------------[directive N7]
 LDAP_Server 129.12.3.197 -------------- Note: This is the IP address of ldap://sec.cs.kent.ac.uk at Kent University.
 LDAP_Port 389
 Base_DN "c=gb"
 UID_Attr uid
 require valid-user
 Options Indexes FollowSymLinks
 AllowOverride None
 order allow,deny
 allow from all
</Location>

3. Now you need to set three environment variables correctly in your Windows system:

JAVA_HOME: point to the Java home directory in your Windows system
APACHE_HOME: point to the Apache home in your Windows system
PATH: point to <JAVA_HOME\bin; JAVA_HOME\bin\client>;

You can set these variables in the system control panel (in Control Panel->System->Advanced->Environment Variables);

4. Now you can follow Step 5 above to continue with your testing.

If you want to compile Apache modules in Windows by yourself, please refer to http://www.muquit.com/muquit/software/mod_auth_ldap/mod_auth_ldap.html.

5 Using SAAM with policy files stored in LDAP

In the above Section 2 Installation Steps, in Step 4, we assume that you were using a plain XML file to store the PERMIS policy, and the configurations in the Apache server for the PERMIS policy in the policy XML file were as follows:

PermisPolicyLocation /home/target/saam/policy1.xml ----------------[directive SN4]
PermisRootCA APACHE_HOME/conf/cacert.cer ---------------------------------[directive N5]
PermisJavaClass “.:JAVA_HOME/jre/lib/ext/saam.jar:JAVA_HOME/jre/lib/ext/iaik_jce.jar:JAVA_HOME/jre/lib/ext/axis.jar:JAVA_HOME/jre/lib/ext/ log4j-1.2.13.jar “-----[directive N8]
PermisACAttribute attributeCertificateAttribute---------------------------[directive N9]
PermisPKCAttribute userCertificate ---------------------------------------[directive N10]

If you would prefer to use an LDAP server for holding the PERMIS policy, then this can be accomplished by altering the PermisPolicyLocation and adding PermisPolicyIdentifier and PermisPolicyIssuer directives. The PermisPolicyLocation directive should be changed so that it points to the LDAP server where the policy is stored. The other two directives allow the system to find the policy in the LDAP and should contain the policy’s OID in the PermisPolicyIdentifier and the policy’s SOA in the PermisPolicyIssuer. The example below should allow you to access the test policy stored in Kent’s LDAP server:

PermisPolicyIdentifier 1.2.826.0.1.3344810.6.0.0.11 ----------------------[directive N2]
PermisPolicyIssuer cn=A Permis Test User,o=permisv5,c=gb -------------------[directive N3]
PermisPolicyLocation ldap://sec.cs.kent.ac.uk ----------------------------[directive N4]
PermisRootCA APACHE_HOME/conf/cacert.cer ---------------------------------[directive N5]
PermisJavaClass “.:JAVA_HOME/jre/lib/ext/saam.jar:JAVA_HOME/jre/lib/ext/iaik_jce.jar:JAVA_HOME/jre/lib/ext/axis.jar:JAVA_HOME/jre/lib/ext/ log4j-1.2.13.jar “-----[directive N8]
PermisACAttribute attributeCertificateAttribute---------------------------[directive N9]
PermisPKCAttribute userCertificate;binary ---------------------------------------[directive N10]

Please Note that in order to use policy certificates stored in LDAP you will require the OID and SOA of the policy stored in the LDAP server

Replace Kent's LDAP policy store server with your own.

Take a copy of the PERMIS policy (policy1.ace) provided in the Installation kit and insert it into your own policy store; either in the LDAP server as the attribute of attributeCertificateAttribute in entry cn=A PERMIS Test User,o=permis,c=gb or in the filestore /home/target/saam/policy1.ace. Also copy the PKC file APermisTestUser.cer to /home/target/saam/APermisTestUser.cer. Edit the Apache configurations parameter PermisPolicyLocation to point to your own policy store e.g. ldap://ldap.myuniv.ac.uk/ (for LDAP server) or /home/target/saam/policy1.ace (for filestore repository). Edit the Apache configurations parameter PermisRootCA to point to APermisTestUser.cer. So the parameters PermisPolicyLocation and PermisRootCA in the Apache configuration file will look like:

PermisPolicyLocation ldap://ldap.myuniv.ac.uk (for LDAP server)
PermisRootCA /home/target/saam/APermisTestUser.cer 

or

PermisPolicyLocation /home/target/saam/policy1.ace (for filestore repository)
PermisRootCA /home/target/saam/APermisTestUser.cer 

Note APermisTestUser.cer is the public key certificate issued by RootCA, which is used to verify that policy1.ace is signed by A Permis Test User. Because APermisTestUser.cer is present within the entry of "A Permis Test User" at the Kent LDAP, so you do not need to specify it explicitly when using the Kent LDAP; but when using your own filestore, it must be specified explicitly.

Replay the testing step 5 above. You should have accessed the protected location </secure2> using PERMIS authorization and a policy stored in your own LDAP server.

Modify the PERMIS policy for use with LDAP.

This will entail modifying the policy XML file, then signing the policy and storing it in the policy store. Note you should change the policy identifier (OID) in your new policy, and then edit the httpd.conf parameter PermisPolicyIdentifier to hold your new identifier. You can either edit the XML by hand or use the PERMIS Policy Management GUI.

About the format of the PERMIS policy, please refer to http://sec.cs.kent.ac.uk/download/Sec2002Final.pdf.

Once the policy has been edited, you will need to digitally sign it. You can use the PERMIS Policy Management GUI for this or alternatively the PERMIS Attribute Certificate Manager (ACM) tool.

For testing purposes you can use the key pair provided in the SAAM Installation Kit, but you should obtain your own key pair before the system goes live and sign your policy with this.

You will also have to replace the Root CA certificate with the certificate of the Root CA that signed the Public Key Certificates of the Policy Issuer and of the issuers of the Attribute Certificates. If you change the name or location of the Root CA certificate file, you have to change the PermisRootCA directive to point to your file. 

6 Possible problems for SAAM

(1) The most possible frequent problem for SAAM is that the Java virtual machine could not be correctly invoked within SAAM from the Apache server. To avoid this problem, you need to make sure that LD_LIBRARY_PATH is correctly set for Linux system, i.e.:

 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JAVA_HOME/jre/lib/i386/client:$JAVA_HOME/jre/lib/i386

or PATH is correctly set for Windows system, i.e.:

 PATH=JAVA_HOME\jre\bin;JAVA_HOME\jre\bin\client

Then you need to make sure that PermisJavaClass in httpd.conf  has been set correctly:

PermisJavaClass ".:JAVA_HOME/jre/lib/ext/saam.jar:JAVA_HOME/jre/lib/ext/iaik_jce.jar:JAVA_HOME/jre/lib/ext/axis.jar:JAVA_HOME/jre/lib/ext/ log4j-1.2.13.jar "-----[directive N8, for Linux]
or
 PermisJavaClass ".:JAVA_HOME\jre\lib\ext\saam.jar:JAVA_HOME\jre\lib\ext\iaik_jce.jar:JAVA_HOME\jre\lib\ext\axis.jar:JAVA_HOME\jre\lib\ext\ log4j-1.2.13.jar "-----[directive N8, for Windows]

(2) In the configurations for SAAM in httpd.conf:

<Location /secure2>
 AuthType Basic
 AuthName "Protected by both Apache authn and PERMIS authz"
 PermisAuthorization
 PermisPullMode
 LDAP_Server 129.12.3.197 LDAP_Port 389
 Base_DN "c=gb"
 UID_Attr uid
 require valid-user
 Options Indexes FollowSymLinks
 AllowOverride None
 order allow,deny
 allow from all
</Location>

Please make sure you always add the Base_DN directive in it and the Base_DN cannot be empty, otherwise mod_auth_ldap cannot work properly.

(3) In the following directive for SAAM in httpd.conf:

PermisPolicyLocation ldap://sec.cs.kent.ac.uk ----------------------------------[directive N4]

For some LDAP systems, you should always append the suffix (such as c=gb) to the end of the LDAP address; but for some other LDAP systems, you should always remove the suffix (such as c=gb) from it. So please consult your LDAP administrator about your LDAP's configuration.

(4) If you get a segmentation fault in Apache (by checking the Apache error log file), please make sure you recompile the mod_permis_src source code to get the binary  mod_permis Apache module on your machine. 

Support and Contact Points

If you have any further queries regarding PERMIS SAAM, please contact either:

Wensheng Xu at w.xu@kent.ac.uk

or

Alexander Otenko at: o.otenko@kent.ac.uk

---

[1] Note that our LDAP contains other ACs, too, so you need to find the right one if you want to download it. Look for the AC with the policy with the OID 1.2.826.0.1.3344810.6.0.0.11.