PERMIS SAAM Installation Cookbook
PERMIS Shibboleth Apache Authorisation Module (SAAM) Installation Cookbook
Part 1 - Shibboleth Instructions
Authors: David W. Chadwick,
|
Release Number |
Date |
Comment |
|
1.0 |
23 November 2004 |
Initial public release |
|
1.1.0 |
13 July 2006 |
Release with Modular PERMIS |
|
1.1.1 |
28 July 2006 |
PE is used instead of ACM for policy; mod_permis should be recompiled |
|
2.0 |
31 October 2006 |
Complete rewrite to use plain XML policies and no ACs initially. |
|
2.1 |
11 August 2008 |
Using the O=PERMISv5,C=GB entry
in the Kent LDAP |
Table of Contents
Appendix A - The Apache server configurations
Appendix B - The configuration file for LDAP at Kent University
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 1 of the cookbook, PERMIS will normally be configured to work in push mode where Shibboleth is used to push the user’s attributes from the user’s Identity Provider (or Attribute Authority) to the service provider. (PERMIS can also be configured to work in pull mode to retrieve the user’s X.509 attribute certificates (ACs) from one or more specified LDAP servers and make an access decision based on these ACs, but this is an advanced mode of use with Shibboleth.) 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 file store of the Shibboleth service provider’s 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 and Shibboleth.
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. Apache authentication module mod_auth_ldap at the Shibboleth origin side to serve as the user authentication service.
3. Shibboleth target and origin sites should be installed and interoperating.
4. An optional LDAP server that you have write
access to (this can be used to hold plain text role values, PERMIS policy ACs and user X.509 ACs). The
public LDAP server at
5. 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.
The SAAM Installation kit
The Kent SAAM Installation kit comprises the following items:
1. The PERMIS Java classes library saam.jar for the Shibboleth target site
2. The source code for the mod_permis modules mod_permis_13.so and mod_permis_20.so 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
In order to run mod_permis on linux systems you will need to compile the above source codes to get your own binaries:
Run make13.sh (for Apache 1.3) or make20.sh (for Apache 2.0) , which will create one of 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 Apache or JRE should match those on your system).
We strongly suggest you always recompile the mod_permis module on your system whenever you update your operating system to make sure the binary is compatible with your platform.
3. A digitally signed PERMIS Test Policy certificate, 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 and can be used to validate policy1.ace.
4. The raw (unsigned) PERMIS Test Policy. It's source filename is policy1.xml.
5. 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.
6. A signature verification X.509 Public Key Certificate cacert.cer. It is needed to validate the PKC used to sign the test policy certificate.
7. Two test users' X.509 attribute certificates User0.ace and User1.ace. These are only needed for advanced use. They are also stored in the Kent LDAP server in the attributeCertificateAttribute attribute of entries cn=User0,o=permisv5,c=gb and cn=User1,o=permisv5,c=gb
8. A ldif file ldif.zip for the entries of User0, User1, A PERMIS Test User for your optional LDAP service.
9. Two modified Shibboleth origin modules JNDIDirectoryDataConnector.class and Base64ValueHandler.class
10. Three Shibboleth configuration files for Shibboleth attribute release and acceptance policies which are used in our testing environment and are provided for your reference: AAP.xml, arp.site.xml, resolver.ldap.xml in the sub directory </confExample>.
11. One IAIK library iaik_jce.jar. This library is needed for running PERMIS when you use signed policy ACs or pull user ACs from Shibboleth IdPs. Please note that though this library is included in this package for your convenience, it is not our software and belongs to IAIK.
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. 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.
14. Two text files in accordance with the Apache licence: LICENSE and NOTICE.
15. The Installation Cookbook (this document)
The following items are also provided in the SAAM installation kit, but are only used for Part 2 of this cookbook and are not used here.
16. A modified Apache authentication module mod_auth_ldap, whichis
also available separately from http://sec.cs.kent.ac.uk/permis/downloads/mod_auth_ldap.tar.gz.
We have modified the original mod_auth_ldap
so that 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 in our package 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.
17. 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 Microsystems.
The SAAM installation kit is available at:
http://sec.cs.kent.ac.uk/permis/integrationProjects/Shibboleth.shtml
Download the SAAM installation kit which will be in a zip file named saam_[version no].zip. Unzip this into a directory in the Shibboleth target computer, say </home/target/saam> then you'll see the items listed above.
2 Installation steps
Installation will proceed as follows:
You will install PERMIS using a default XML text policy file with attributes pushed by the Shibboleth origin site.
Then under Advanced Use you may install PERMIS using a default signed policy AC, and optionally pull or push user ACs from a Shibboleth IdP.
Install PERMIS using the default policy and systems provided by Kent
In this stage you will install the PERMIS software on your
system, using a test XML policy stored on the local file system and plain text
attributes provided by
Step 0. Make sure that Apache and Shibboleth are installed and working correctly.
Step 1. Copy files in the Shibboleth target computer
a. In the Shibboleth target computer, if you are using Apache 1.3, copy the file mod_permis_13.so to <APACHE_HOME/libexec/>; if you are using Apache 2.0, copy mod_permis_20.so to <APACHE_HOME/modules/>, where <APACHE_HOME> is the directory, in which your Apache is installed.
b. In the Shibboleth target computer, 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 rootca.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 will need to change their file permissions by performing:
chmod 644 *.jar
or
chmod 644 *.so
Step 2: Update the Shibboleth Target Site Computer Environment Variable LD_LIBRARY_PATH
On the target site computer, run the following command to update the environment variable: LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/shibboleth-target-1.2/lib: $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 apache module. In this command JAVA_HOME is the environment variable of the computer system referring to the Java home directory. Please make sure 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.
Step 3. Change the Shibboleth-Apache configuration file in the Shibboleth target computer.
The order in which the modules appear in the configuration file and the names of the shared libraries are different for Apache 1.3 and Apache 2.0, so we provide instructions for both versions of web-servers.
(1) If you are using Apache 1.3:
a. Before modifications:
Modify the Shibboleth configuration file for Apache: apache.config. This file is included by the Apache configuration file httpd.conf so it is part of the Apache configurations and can be found in the following directory: </opt/Shibboleth-target-1.2/etc/Shibboleth/>. Before modification, the apache.config file may look like the following:
LoadModule mod_shib /opt/shibboleth-target-1.2/libexec/mod_shib_13.so----[directive 1]
... ... (other directives)
<Location /secure2>
AuthType shibboleth----------------------------------------------------[directive
2]
ShibRequireSession On
require valid-user
</Location>
So location </secure2> is protected by Shibboleth.
b. Modifications:
Insert the following directives into this configuration file immediately AFTER directive 1: (Please pay attention to AFTER)
LoadModule mod_permis
APACHE_HOME/libexec/mod_permis_13.so---------------[directive N1]
PermisPolicyLocation APACHE_HOME/conf/policy1.xml----------------[directive N4]
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]
Insert the following directive immediately after directive 2:
PermisAuthorization------------------------------------------------------[directive N6]
c. After modifications:
After the above modifications, the configuration file will look like the following:
LoadModule mod_shib
/opt/shibboleth-target-1.2/libexec/mod_shib_13.so----[directive 1]
LoadModule mod_permis
APACHE_HOME/libexec/mod_permis_13.so---------------[directive N1]
PermisPolicyLocation APACHE_HOME/saam/policy1.xml----------------[directive N4]
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]
... ... (other directives)
<Location /secure2>
AuthType shibboleth --------------------------------------------------[directive
2]
PermisAuthorization --------------------------------------------------[directive
N6]
ShibRequireSession On
require valid-user
</Location>
In the above configurations APACHE_HOME should be your Apache home directory and JAVA_HOME should be your Java SDK home directory.
Please note: if you add [directive N6] to a Shibboleth protected location, then this location and all its subordinate directories will be protected by the PERMIS SAAM. If you delete this directive from the Shibboleth protected location in the configuration file, then this location will no longer be protected by the PERMIS SAAM.
(2) If you are using Apache 2.0:
a. Before modifications:
Modify the Shibboleth configuration file for Apache: apache2.config. This file is included by the Apache configuration file httpd.conf so it is part of the Apache configurations and it can be found in this directory: </opt/Shibboleth-target-1.2/etc/Shibboleth/>. Before modification, the apache2.config may look like the following:
LoadModule mod_shib /opt/shibboleth-target-1.2/libexec/mod_shib_20.so----[directive 1]
... ... (other directives)
<Location /secure2>
AuthType shibboleth---------------------------------------------------[directive
2]
ShibRequireSession On
require valid-user
</Location>
So location </secure2> is protected by Shibboleth.
b. Modifications:
Insert the following directives into this configuration file immediately BEFORE directive 1: (Please pay attention to BEFORE)
LoadModule mod_permis APACHE_HOME/modules/mod_permis_20.so---------------[directive N1]
Insert the following directives immediately after directive 1:
PermisPolicyLocation
APACHE_HOME/conf/policy1.xml----------------[directive N4]
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]
Insert the following directive immediately after directive 2:
PermisAuthorization------------------------------------------------------[directive N6]
c. After modifications:
After the above modifications, the configuration file will look like the following:
LoadModule mod_permis
APACHE_HOME/modules/mod_permis_20.so---------------[directive N1]
LoadModule mod_shib
/opt/shibboleth-target-1.2/libexec/mod_shib_20.so----[directive 1]
PermisPolicyLocation APACHE_HOME/conf/policy1.xml----------------[directive N4]
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]
... ... (other directives)
<Location /secure2>
AuthType shibboleth---------------------------------------------------[directive
2]
PermisAuthorization---------------------------------------------------[directive
N6]
ShibRequireSession On
require valid-user
</Location>
In the above configurations APACHE_HOME should be your Apache home directory and JAVA_HOME should be your Java SDK home directory.
Please note: if you add [directive N6] to a Shibboleth protected location, then this location and all its subordinate directories will be protected by the PERMIS SAAM. If you delete this directive from the Shibboleth protected location in the configuration file, then this location will no longer be protected by the PERMIS SAAM.
Step 4: Change Shibboleth Target Configuration File AAP.xml
AAP.xml can be found at </opt/Shibboleth-target-1.2/etc/Shibboleth/> on the Shibboleth target computer. In this file, add one new entry into it:
<AttributeRule Name="urn:mace:dir:attribute-def:permisRole"
Header="permisRole">
<AnySite>
<AnyValue/>
</AnySite>
</AttributeRule>
This will allow the Shibboleth target site to accept one new plain text attribute permisRole from the Shibboleth origin site.
Please note: for attribute permisRole, the Header must be set as "permisRole". This is required by the PERMIS test policy. The attribute name sent to the shibboleth service provider for authorization with SAAM can take any value as long as it is either the same name as the attribute used in the policy or uses the Header variable to remap the received variable to the attribute used in the policy.
Step 5: Change Shibboleth Origin Configuration File resolver.ldap.xml
This file can be found at <$TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/> in the Shibboleth origin site computer. Add the following entry into it:
<SimpleAttributeDefinition id="urn:mace:dir:attribute-def:permisRole"
smartScope="kent.ac.uk">
<DataConnectorDependency requires="directory"/>
</SimpleAttributeDefinition>
Please note the smartScope is needed for the example PERMIS policy used in this cookbook. If it is absent here, then the origin site host name will be used as the domain name which may not be recognized by the example PERMIS policy. In this case you should modify the PERMIS policy to allow the origin site host domain name to be recognized.
In the same file, modify the JNDIDirectoryDataConnector entry as follows:
<JNDIDirectoryDataConnector id="directory">
<Search filter="uid=%PRINCIPAL%">
<ControlssearchScope="SUBTREE_SCOPE"returningObjects="false"/>
</Search>
<Property name="java.naming.factory.initial"
value="com.sun.jndi.ldap.LdapCtxFactory"
/>
<Property name="java.naming.provider.url"
value="ldap://sec.cs.kent.ac.uk/c=gb"/>
</JNDIDirectoryDataConnector>
Note
in the above entry that uid should be
used as the search filter and the LDAP should be ldap://sec.cs.kent.ac.uk/c=gb so that the LDAP server at the
Step 6: Change Shibboleth Origin Configuration File arp.site.xml
This file arp.site.xml can be found at <$TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/arps/> in the Shibboleth origin site computer. Add the following entry into it:
<Attribute
name="urn:mace:dir:attribute-def:permisRole">
<AnyValue release="permit"/>
</Attribute>
Step 5 and Step 6 will allow the Shibboleth origin site to release the permisRole attribute to the target site.
Step 7: Configure httpd.conf for Apache at the Shibboleth Origin site to authenticate users
We assume you are using a mod_auth_ldap Apache module to authenticate users at the Shibboleth origin site. So the directives for the Shibboleth Handle Service in httpd.conf for Apache at the origin site may look like the following.
<Location
/shibboleth/HS>
Options Indexes FollowSymLinks
AllowOverride None
Order allow,deny
Allow from all
AuthName "Shibboleth
Handle Service"
AuthType Basic
LDAP_Server 129.12.3.197
-------------- Note: This is the IP address of ldap://sec.cs.kent.ac.uk at
LDAP_Port 389
Base_DN "c=gb"
UID_Attr uid
Require valid-user
</Location>
Note
that during this installation step, you will be using user names and passwords
configured into
For this test authentication LDAP, there are 2 test users (LDIF of the entries is provided in ldif.zip). Each user has the following attributes: cn, sn, uid, userPassword, attributeCertificateAttribute, permisRole, 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
permisRole: Role0
userPassword: User0
So for User0, the username/password is: User0/User0.
For User1:
dn: cn=User1,o=permisv5,c=gb.
cn: User1
uid: User1
permisRole: Role1
userPassword: User1
So for User1, the username/password is:
User1/User1.
Figure 1. Viewing the User0 entry in LDAP
Step 8 Testing
You have set up a Shibboleth-PERMIS protected location </secure2> in the above Step 3. Now edit the httpd.conf file as described in Appendix A to create another 3 separate locations on your web site: a public page at </public>, and a page that requires authentication only at </simple>, and a location that is protected only by Shibboleth at </shibsecure>. So now you have got 4 locations altogether:
/public: without any authentication or authorisation
/simple: with basic Apache authentication
/shibsecure: with Shibboleth authentication and authorisation
/secure2: with Shibboleth 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 tomcat and Apache on the Shibboleth origin site computer, and Apache on the Shibboleth target site 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 authorisation is needed to access it.
*http://your_target_website/simple: You should find that you are prompted for a user name and password, and then you can access the page. Enter the user name User0 and password User0.
*http://your_target_website/shibsecure: This is your normal Shibboleth protected location. You will then be asked to log in at the origin site and you can use the username/password User0/User0 and User1/User1 to be authenticated, and you will be given access to this location because your current Shibboleth configuration at the target site for this location is "Require valid-user".
*http://your_target_website/secure2: You should be able to access the page by first logging in at the Shibboleth origin site using the username/password User0/User0 and then being returned automatically back to this page. In the background the system will have
i. checked that you are still authenticated
ii. retrieved your attributes
iii. checked that these attributes are sufficient for you to have access to the protected page according to the PERMIS policy. 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 systems
In this stage you will migrate to using your own Authentication System, your own PERMIS policy, and your own attributes.
Step 10. Firstly migrate to your own authentication system and LDAP.
You are using Apache and Shibboleth, so do the following. Here we assume you are using the same LDAP server as the authentication server and the Shibboleth attribute server.
Please note that if you have already configured your Shibboleth IdP to authenticate a user and return a plain text attribute that you wish to use as a role attribute then you should move straight to Step 11 and configure your policy to recognise the new role attribute's name and role values.
10.1 Configure httpd.conf for Apache at the Shibboleth Origin site to authenticate users
Change the directives for Shibboleth Handle Service in httpd.conf for Apache at the origin site as follows:
<Location
/shibboleth/HS>
Options IndexesFollowSymLinks
AllowOverride None
Orderallow,deny
Allow from all
AuthName "Shibboleth Handle
Service"
AuthType Basic
LDAP_Server 11.11.11.11 ----------
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_Attruid ---------Note: You may
need to change this depending upon the attribute you use for authentication
Require valid-user
</Location>
10.2 Configure your own authentication ldap
For your authentication LDAP server, you should set 2 testing users: User0 and User1. Each user should have the following attributes: dn, cn, uid, userPassword and permisRole.
For User0:
dn: cn=User0,o=permisv5,c=gb
cn: User0
uid: User0
userPassword: User0
permisRole: Role0
For User1:
dn: cn=User1,o=permisv5,c=gb
cn: User1
uid: User1
userPassword: User1
permisRole: Role1
You can change the userPassword for both User0 and User1 to anything you like.
Note: If you would prefer to use X.509 ACs to hold user attributes please refer to the PERMIS API cookbook for more details. To run PERMIS SAAM using attribute certificates, please read Section 3 of this cookbook. If you would like to create attribute certificates and add them to an LDAP server, please download and use the PERMIS Attribute Certificate Manager software.
10.3 Change the Shibboleth configuration for JNDI data connector
Modify the file
$TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/resolver.ldap.xml in the Shibboleth origin site computer:
<JNDIDirectoryDataConnector id="directory">
<Search filter="uid=%PRINCIPAL%">
<ControlssearchScope="SUBTREE_SCOPE"
returningObjects="false"/>
</Search>
<Property name="java.naming.factory.initial"
value="com.sun.jndi.ldap.LdapCtxFactory"/>
<Property name="java.naming.provider.url"
value="ldap://sec.cs.kent.ac.uk/c=gb"/>
</JNDIDirectoryDataConnector>
Change
the ldap://sec.cs.kent.ac.uk/c=gb in the above JNDIDirectoryDataConnector
entry to your own LDAP. Also change the search filter uid
in the above entry if you use a different attribute for authentication in your
LDAP.
For information on how to use 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
Replay the testing step 9 above. You should have now authenticated with your own LDAP server, using user names and passwords stored inside it, and gained access to the protected pages using permisRole plain text attributes stored in your LDAP server.
Step 11. Thirdly modify the PERMIS policy.
This
will entail:
i) modifying the policy XML file and
ii) editing the httpd.conf parameter PermisPolicyLocation to point
towards your new XML policy file.
You can either edit the XML by hand or use the PERMIS Policy Management GUI.. Information about the format of the PERMIS policy can be found in the document http://sec.cs.kent.ac.uk/download/Sec2002Final.pdf..
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.
3.1 Debug 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 in increasing order of information that is output: 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
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 output to a file called mod_permis.log and the debug information for the Java SAAM module will be output 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
- Debugging is turned off
fatal - prints out serious fatal error messages that will lead to the
program terminating
error - prints out serious non fatal errors
warn - prints out less important errors
info - prints out statements to show which users are accessing your site
via the PERMIS SAAM, and the results of their attempted access
debug - prints out all the verbose debug information in the PERMIS SAAM.
Debug information and possible problems for SAAM
Please refer to the Section Debug information and the Section Possible problems for SAAM in the SAAM Apache User Guide.
3.2 X.509 Attribute Certificate Handling
In order to create and manage user X.509 ACs 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.
3.3 Using User X.509 Attribute Certificates with the PERMIS SAAM
For added security, you may want to use X.509 ACs with Shibboleth instead of plain attributes. Using X.509 ACs ensures that the user attributes are tamperproof since they are digitally signed by the issuer. Instead of doing the above Step 4 to Step 6 in the installation process, you should first edit the Apache configuration file as described below before following steps M4 to M6:
In
order to use X.509 Attribute certificates you should add the following
attributes in the Apache configuration file where you defined your original
policy details
PermisRootCA APACHE_HOME/conf/rootca.cer
PermisACAttribute attributeCertificateAttribute
PermisPKCAttribute userCertificate
After the above modifications, the configuration file will look like the
following:
LoadModule mod_shib
/opt/shibboleth-target-1.2/libexec/mod_shib_20.so----[directive 1]
LoadModule mod_permis
APACHE_HOME/libexec/mod_permis_13.so---------------[directive N1]
PermisPolicyLocation APACHE_HOME/conf/policy1.xml----------------[directive N4]
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]
PermisRootCA APACHE_HOME/conf/cacert.cer
PermisACAttribute attributeCertificateAttribute
PermisPKCAttribute userCertificate
... ... (other directives)
<Location
/secure2>
AuthType shibboleth---------------------------------------------------[directive
2]
PermisAuthorization---------------------------------------------------[directive
N6]
ShibRequireSession On
require valid-user
</Location>
The
PermisRootCA directive points to a PKC certificate that can be used to verify
if an X.509 certificate has been signed by the correct certificate issuing
authority (CA).
The PermisACAttribute directive contains the String name for an LDAP or
Shibboleth attribute that contains an X.509 attribute certificate.
The PermisPKCAttribute directive contains the String name for an LDAP or
Shibboleth attribute that contains an X.509 public key certificate.
The PermisACAttribute and PermisPKCAttribute values are used to parse and
verify the signatures on pushed shibboleth attributes and to retrieve pulled ACs from LDAP.
The above [directive N1] is for Apache 1.3. If you are using Apache 2.0, then
refer to Step 3 of this cookbook and change this directive accordingly.
Step M4: Change Shibboleth Target Configuration File AAP.xml
AAP.xml can be found at </opt/Shibboleth-target-1.2/etc/Shibboleth/> on the Shibboleth target computer. In this file, add two new entries into it:
<AttributeRule Name="urn:mace:dir:attribute-def:dn"
Header="User-Distinguished-Name" Alias="dn">
<AnySite>
<AnyValue/>
</AnySite>
</AttributeRule>
<AttributeRule Name="urn:mace:dir:attribute-def:attributeCertificateAttribute"
Header="attributeCertificateAttribute">
<AnySite>
<AnyValue/>
</AnySite>
</AttributeRule>
This will allow the Shibboleth target site to accept two new attributes dn and attributeCertificateAttribute from Shibboleth origin sites.
Please note: for attribute dn, the Header in this entry must be set as "User-Distinguished-Name"; for attribute attributeCertificateAttribute, the Header must be set as "attributeCertificateAttribute". This is required by the PERMIS SAAM to operate on X.509 ACs.
Step M5: Change Shibboleth Origin Configuration File resolver.ldap.xml
This file can be found at <$TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/> in the Shibboleth origin site computer, where TOMCAT_HOME should be your Tomcat home directory. Add the following two entries into it:
<SimpleAttributeDefinition id="urn:mace:dir:attribute-def:dn">
<DataConnectorDependency
requires="directory"/>
</SimpleAttributeDefinition>
<SimpleAttributeDefinition
id="urn:mace:dir:attribute-def:attributeCertificateAttribute"
valueHandler="edu.internet2.middleware.shibboleth.aa.attrresolv.provider.Base64ValueHandler">
<DataConnectorDependency
requires="directory"/>
</SimpleAttributeDefinition>
In the same file, modify the JNDIDirectoryDataConnector entry as follows:
<JNDIDirectoryDataConnector id="directory">
<Search filter="uid=%PRINCIPAL%">
<ControlssearchScope="SUBTREE_SCOPE"returningObjects="false"/>
</Search>
<Property name="java.naming.factory.initial"
value="com.sun.jndi.ldap.LdapCtxFactory"
/>
<Property name="java.naming.provider.url"
value="ldap://sec.cs.kent.ac.uk/c=gb"/>
<Property name="java.naming.ldap.attributes.binary"
value="attributeCertificateAttribute" />
</JNDIDirectoryDataConnector>
Note
in the above entry that uid should be
used as the search filter and the LDAP should be ldap://sec.cs.kent.ac.uk/c=gb so the LDAP at the
Please note: in order to make use of resolver.ldap.xml, make sure that in the Shibboleth configuration file origin.xml the following entry is present:
resolverConfig="/conf/resolver.ldap.xml"
Step M6: Change Shibboleth Origin Configuration File arp.site.xml
This file arp.site.xml can be found at <$TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/arps/> in the Shibboleth origin site computer. Add the following two entries into it:
<Attribute
name="urn:mace:dir:attribute-def:attributeCertificateAttribute">
<AnyValue
release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:dn">
<AnyValue
release="permit"/>
</Attribute>
Steps M5 and M6 will allow the Shibboleth origin site to release the dn and attributeCertificateAttribute attributes to the target site.
After the above configurations, restart Shibboleth at both the origin site and target site and replay the testing step 9 above. You should have accessed the protected page using PERMIS authorization based on an attributeCertificateAttribute attribute instead of a permisRole attribute.
3.4 Using both attributes and X.509 ACs with the PERMIS SAAM
You can use both attributes and X.509 ACs with the PERMIS SAAM at the same time. During the above Step 4 to Step 6 or Step M4 to Step M6, configure Shibboleth to let permisRole, attributeCertificateAttribute and dn be released and accepted in Shibboleth, then both the values of permisRole and attributeCertificateAttribute will be passed to PERMIS, in which case both the roles contained in permisRole and attributeCertificateAttribute will be used by PERMIS to make an access control decision for the user.
3.5 Using PERMIS SAAM with a digitally signed policy AC
In the above Section 2 Installation Steps, in Step 3, we assume that you were using an XML file to hold the PERMIS policy on the Shibboleth target machine, and the configurations in the Apache server for the PERMIS policy were as follows:
PermisPolicyLocation
APACHE_HOME/saam/policy1.xml----------------[directive N4]
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]
PERMIS
can also use digitally signed policies for added security. If you would
prefer to use digitally signed policies, these should be stored as X.509
attribute certificates in the attributeCertificateAttribute stored in an LDAP
server. In this case, the configurations in the Apache server for the signed
policy stored in LDAP are as follows:
PermisPolicyIdentifier
1.2.826.0.1.3344810.6.0.0.11----------------------[directive N2]
PermisPolicyIssuer cn=A Permis
TestUser,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]
The directives have the following meanings:
The
PermisPolicyLocation directive should contain the URL of the LDAP server.
The PermisPolicyIdentifier directive should contain the unique policy identifier(OID) set when the policy was created.
The PermisPolicyIssuer directive should contain the policy's source of authority(SOA) i.e. the DN of the person who signed the
policy.
The above 3 directives are used to locate the policy in the LDAP server.
The PermisRootCA directive should point to a PKC certificate that can be used
to verify if a users X.509 certificate has been signed by the correct
certificate issuing authority (CA).
The PermisACAttribute directive should contain the name for an LDAP or
Shibboleth attribute that contains an X.509 attribute certificate.
The PermisPKCAttribute directive should contain the name for an LDAP or
Shibboleth attribute that contains an X.509 public key certificate.
The PermisACAttribute and PermisPKCAttribute values are used to parse and
verify the digitally signed attribute certificate containing the PERMIS policy.
3.6 PERMIS in Pull Mode
Shibboleth
PERMIS normally works in push mode, meaning that Shibboleth pushes plain text
attributes or X.509 ACs to PERMIS. PERMIS can also
work in Attribute Certificate Pull Mode, in which case PERMIS will pull all the
X.509 ACs that it needs from all
the configured LDAP servers and Shibboleth will not provide any
attributes or ACs to PERMIS. To use PERMIS in AC pull
mode for the Apache locations one new directive is needed in the locations in
the Apache configuration file: PermisPullMode.
In
this working mode the Apache configurations for the PERMIS SAAM are as follows:
LoadModule mod_shib
/opt/shibboleth-target-1.2/libexec/mod_shib_13.so----[directive 1]
LoadModule mod_shib
/opt/shibboleth-target-1.2/libexec/mod_shib_13.so----[directive 1]
LoadModule mod_permis
APACHE_HOME/libexec/mod_permis_13.so---------------[directive N1]
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: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]
... ... (other directives)
<Location /secure>
AuthType shibboleth----------------------------------------------------[directive
2]
PermisAuthorization----------------------------------------------------[directive
N6]
PermisPullMode---------------------------------------------------------[directive
N7]
ShibRequireSession On
require valid-user
</Location>
In this working mode, the authenticated user DN is passed from the Shibboleth origin site via the Shibboleth target site to PERMIS, PERMIS retrieves the attribute certificates for the user from the LDAP repository(ies) specified by PermisPolicyLocation and PermisACLocation directive(s) in the Apache configuration file, and by the repository policy section in the PERMIS policy file.
Please note that if an XML policy file is used then there must exist either a PermisACLocation attribute in the Apache configuration file or a pre-defined repository in the PERMIS policy, otherwise the SAAM module will not be able to pull attributes.
The above [directive N1] is for Apache 1.3. If you are using Apache 2.0, then refer to Step 3 of this cookbook and change this directive accordingly.
PERMIS AC Repository Locations
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 an AC LDAP repository location:
LoadModule mod_shib
/opt/shibboleth-target-1.2/libexec/mod_shib_13.so----[directive 1]
LoadModule mod_permis
APACHE_HOME/libexec/mod_permis_13.so---------------[directive N1]
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: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]
PermisACLocation
ldap://site1.ac.uk/-------------------------------------[directive N11]
... ... (other directives)
<Location /secure>
AuthType shibboleth----------------------------------------------------[directive
2]
PermisAuthorization----------------------------------------------------[directive
N6]
PermisPullMode---------------------------------------------------------[directive
N7]
ShibRequireSession On
require valid-user
</Location>
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 N11 and N12].
Note. If the PermisACLocation directive is not specified with the PermisPullMode directive, then PERMIS will try to pull the X.509 Attribute Certificates from the same repository as the PermisPolicyLocation [directive N4] (if this directive contains a plaintext XML policy then no attributes can be pulled), or from the repositories specified by the RepositoryPolicy element in the PERMIS Policy. If both the PermisACLocation directive and the RepositoryPolicy element are specified, then PERMIS will fetch ACs from all valid locations.
The above [directive N1] is for Apache 1.3. If you are using Apache 2.0, then refer to Step 3 of this cookbook and change this directive accordingly.
(2) To configure AC LDAP locations in the PERMIS policy file.
When using SAAM you can specify a set of LDAP repositories to be used in pull mode inside your PERMIS policy. This can be accomplished by adding a “RepositoryPolicy” XML element to the main body of the XML document. The “RepositoryPolicy” element is a container for a set of “Repository” elements each of which should contain the URL for a single LDAP server.
In the PERMIS policy file, add a new RepositoryPolicy element:
<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 RepositoryPolicy XML element inside the PERMIS policy file.
Note that the PermisACLocation directives and the RepositoryPolicy element inside the PERMIS policy are ignored if the PermisPullMode directive [directive N7] in the Apache configuration file is missing.
Support and Contact Points
If you have any further queries regarding PERMIS SAAM, please contact either:
permis-users@jiscmail.ac.uk
or
permis-dev@jiscmail.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.