Fig-1: ZXID, via mod_auth_saml, adds to Apache httpd Single Sign-On (SSO), Attribute Broker, and XACML PEP Capabilities that can be used by existing static and dynamic content without alteration.
While I am not a guru in Apache set ups and others will do this much better, not to speak of the official documentation, I still find that to ensure initial success of the new installer, some help may be in order.
Consider this receipe only one of many possible setups and not necessarily even the best. The receipe worked for me in August 2006. If you come much later, things may have changed.
This Apache setup aims to illustrate
CGI invocation of zxid C binary
mod_php5 invocation of zxid.php
mod_perl invocation of zxid.pl
CGI invocation of zxid.pl (alternative to mod_perl)
Support mod_auth_saml
If you are looking for mod_auth_saml specific instructions, please read mod_auth_saml.pd
Fig-1: ZXID, via mod_auth_saml, adds to Apache httpd Single Sign-On (SSO), Attribute Broker, and XACML PEP Capabilities that can be used by existing static and dynamic content without alteration.
You may also install from binaries, but I feel the compilation route is only reliable way to have reproducible results.
Download from: http://httpd.apache.org/download.cgi
For PHP it is critical that --enable-so is supplied as that seems to be the only documented (supported?) installation route. PHP recommends (Aug 2006) against using Apache 2 threaded MPM. My stock perl does not support threads either, I guess the prefork MPM route is fine.
tar xvjf /t/httpd-2.2.3.tar.bz2 ./configure --prefix=/apps/apache/2.2.3 --with-mpm=prefork --enable-so --enable-cgi --disable-cgid --enable-ssl --with-ssl=/apps/openssl/std
I got following configure error
checking for SSL_set_cert_store... no
This seems to be documented as bug http://issues.apache.org/bugzilla/show_bug.cgi?id=39913, but no solution was known as of Aug 2006. Further investigation shows that httpd-2.2.3/modules/ssl/README has following
o per-directory SSLCACertificate{File,Path} is now thread-safe but
requires SSL_set_cert_store patch to OpenSSL
but fails to provide the patch or give any hint as to how to obtain it.
Apparently hacking the configure script to remove all references to the offending variable in question is the only way forward. Look at config.log to identify the places to hack. Iterate ./configure script until it works and then say
make
A couple of linking failures dues to missing -lz happen. Just run the links manually, supplying the -lz flag. Sheesh, apache is supposed to be stable software.
make install
From http://ftp.funet.fi/pub/CPAN/src/
This can be usually skipped if your stock perl is 5.8 series and nonthreaded and you are happy with prefork MPM. Try
perl -V:useithreads -V:usemultiplicity
If it says
useithreads='undef'; usemultiplicity='undef';
then its fine for using prefork MPM.
To compile perl you would
./Configure -prefix=/apps/perl/5.8.8 -des -Dusethreads -Doptimize='-g' -Dusedevel make && make test && make install
From http://perl.apache.org/dist/
Install instructions: http://perl.apache.org/docs/2.0/user/install/install.html
perl Makefile.PL MP_APXS=/apps/apache/std/bin/apxs MP_DEBUG=1 make make test # Seems to fail because wants to create core files and I do not let it to! make install # installs stuff to perl lib directory as well as apache modules directory
You can read futher at http://perl.apache.org/docs/2.0/user/intro/start_fast.html
From php.net
Install instructions: http://www.php.net/manual/en/install.unix.apache2.php
./configure --prefix=/apps/php/5.1.6 --with-apxs2=/apps/apache/std/bin/apxs --with-openssl=/apps/openssl/std --with-zlib --with-curl=/apps --enable-soap --with-libxml-dir=/apps make make install
These configuration steps are to enable all ZXID Apache related functionality, including mod_auth_saml, mod_perl, mod_php, and CGI.
Allow zxid to be triggered as CGI (the trick is SetHandler inside
Allow zxid.pl to be triggered by mod_perl. The trick is
AddHandler perl-script .pl
PerlResponseHandler ModPerl::Registry
PerlOptions +ParseHeaders
Allow zxid.php to be triggered by mod_php5. Trick is
AddType application/x-httpd-php .php .phtml
Enable the mod_auth_saml for some directories
Set port number and domain
Enable SSL operation
Once you have edited the Apache config files, you say
/apps/apache/std/bin/apachectl restart tail -f tmp/err-httpd & # Apache errorlog, per configuration
to get apache running. Below are the edits I applied to my apache config files (in /apps/apache/std/conf directory if you followed this receipe). It's a shame the apache config wizardry is so bloated that the diff does not fit on one page.
diff -u httpd.conf.orig httpd.conf --- httpd.conf.orig 2006-08-31 19:23:42.000000000 -0400 +++ httpd.conf 2006-08-31 20:31:17.000000000 -0400 @@ -37,7 +37,8 @@ # prevent Apache from glomming onto all bound IP addresses. # #Listen 12.34.56.78:80 -Listen 80 +##Listen 80 +Listen 8080 # # Dynamic Shared Object (DSO) Support @@ -51,6 +52,8 @@ # Example: # LoadModule foo_module modules/mod_foo.so # +LoadModule perl_module modules/mod_perl.so +LoadModule php5_module modules/libphp5.so# @@ -98,7 +101,8 @@ # documents. By default, all requests are taken from this directory, but # symbolic links and aliases may be used to point to other locations. # -DocumentRoot "/apps/apache/2.2.3/htdocs" +##DocumentRoot "/apps/apache/2.2.3/htdocs" +DocumentRoot "/home/sampo/zxid" # # Each directory to which Apache has access can be configured with respect @@ -125,7 +129,8 @@ # # This should be changed to whatever you set DocumentRoot to. # - +## + # # Possible values for the Options directive are "None", "All", # or any combination of: @@ -138,7 +143,13 @@ # http://httpd.apache.org/docs/2.2/mod/core.html#options # for more information. # - Options Indexes FollowSymLinks + ##Options Indexes FollowSymLinks + Options All + + AddHandler cgi-script .cgi + AddHandler perl-script .pl + PerlResponseHandler ModPerl::Registry + PerlOptions +ParseHeaders # # AllowOverride controls what directives may be placed in .htaccess files. @@ -155,6 +166,10 @@ ++SetHandler cgi-script + + # # DirectoryIndex: sets the file that Apache will serve if a directory # is requested. @@ -180,14 +195,16 @@ # logged here. If you *do* define an error logfile for a# container, that host's errors will be logged there and not here. # -ErrorLog logs/error_log +##ErrorLog logs/error_log +ErrorLog /home/sampo/zxid/tmp/err-httpd # # LogLevel: Control the number of messages logged to the error_log. # Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. # -LogLevel warn +##LogLevel warn +LogLevel debug # @@ -209,13 +226,14 @@ # define per- access logfiles, transactions will be # logged therein and *not* in this file. # - CustomLog logs/access_log common + ##CustomLog logs/access_log common # # If you prefer a logfile with access, agent, and referer information # (Combined Logfile Format) you can use the following directive. # #CustomLog logs/access_log combined + CustomLog /home/sampo/zxid/tmp/log.httpd combined @@ -245,7 +263,7 @@ # client. The same rules about trailing "/" apply to ScriptAlias # directives as to Alias. # - ScriptAlias /cgi-bin/ "/apps/apache/2.2.3/cgi-bin/" + ##ScriptAlias /cgi-bin/ "/apps/apache/2.2.3/cgi-bin/" @@ -303,7 +321,7 @@ # AddType application/x-compress .Z AddType application/x-gzip .gz .tgz - +AddType application/x-httpd-php .php .phtml # # AddHandler allows you to map certain file extensions to "handlers": # actions unrelated to filetype. These can be either built into the server @@ -394,7 +412,7 @@ #Include conf/extra/httpd-default.conf # Secure (SSL/TLS) connections -#Include conf/extra/httpd-ssl.conf +Include conf/extra/httpd-ssl.conf # # Note: The following must must be present to support # starting without SSL on platforms with no /dev/random equivalent diff -u httpd-ssl.conf.orig httpd-ssl.conf --- httpd-ssl.conf~ 2006-08-31 18:24:09.000000000 -0400 +++ httpd-ssl.conf 2006-08-31 19:35:53.000000000 -0400 @@ -22,9 +22,9 @@ # Manual for more details. # #SSLRandomSeed startup file:/dev/random 512 -#SSLRandomSeed startup file:/dev/urandom 512 +SSLRandomSeed startup file:/dev/urandom 512 #SSLRandomSeed connect file:/dev/random 512 -#SSLRandomSeed connect file:/dev/urandom 512 +SSLRandomSeed connect file:/dev/urandom 512 # @@ -34,7 +34,7 @@ # Note: Configurations that use IPv6 but not IPv4-mapped addresses need two # Listen directives: "Listen [::]:443" and "Listen 0.0.0.0:443" # -Listen 443 +Listen 5443 ## ## SSL Global Context @@ -71,14 +71,16 @@ ## SSL Virtual Host Context ## -+ # General setup for the virtual host -DocumentRoot "/apps/apache/2.2.3/htdocs" -ServerName www.example.com:443 +##DocumentRoot "/apps/apache/2.2.3/htdocs" +DocumentRoot "/home/sampo/zxid" +##ServerName www.example.com:443 +ServerName sp1.zxidsp.org:443 ServerAdmin you@example.com -ErrorLog /apps/apache/2.2.3/logs/error_log -TransferLog /apps/apache/2.2.3/logs/access_log +##ErrorLog /apps/apache/2.2.3/logs/error_log +##TransferLog /apps/apache/2.2.3/logs/access_log # SSL Engine Switch: # Enable/Disable SSL for this virtual host. @@ -96,15 +98,16 @@ # in mind that if you have both an RSA and a DSA certificate you # can configure both in parallel (to also allow the use of DSA # ciphers, etc.) -SSLCertificateFile /apps/apache/2.2.3/conf/server.crt +##SSLCertificateFile /apps/apache/2.2.3/conf/server.crt #SSLCertificateFile /apps/apache/2.2.3/conf/server-dsa.crt +SSLCertificateFile /home/sampo/zxid/zxid.pem # Server Private Key: # If the key is not combined with the certificate, use this # directive to point at the key file. Keep in mind that if # you've both a RSA and a DSA private key you can configure # both in parallel (to also allow the use of DSA ciphers, etc.) -SSLCertificateKeyFile /apps/apache/2.2.3/conf/server.key +##SSLCertificateKeyFile /apps/apache/2.2.3/conf/server.key #SSLCertificateKeyFile /apps/apache/2.2.3/conf/server-dsa.key # Server Certificate Chain: @@ -225,7 +228,7 @@ # Per-Server Logging: # The home of a custom SSL log file. Use this when you want a # compact non-error SSL logfile on a virtual host basis. -CustomLog /apps/apache/2.2.3/logs/ssl_request_log \ - "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" +#CustomLog /apps/apache/2.2.3/logs/ssl_request_log \ +# "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
Check sp1.zxidsp.org resolves
ping sp1.zxidsp.org
Start Apache httpd using
apachectl restart
At this stage you should observe carefully for any unresolved symbols or missing shared libraries (.so) (or dynamic link libraries, DLLs). If you see any, you need to resolve them, e.g. by setting LD_LIBRARY_PATH environment variable.
Now, use browser to access following URLs to try your accomplishments out:
https://sp1.zxidsp.org:5443/README.zxid tests (tests simple file access and that the server works at all)
https://sp1.zxidsp.org:5443/zxid?o=E (tests the SP CGI written in C)
https://sp1.zxidsp.org:5443/zxid.pl?o=E (tests the SP mod_perl way)
https://sp1.zxidsp.org:5443/zxid.php?o=E (tests the SP mod_php5 way)
If any of the above does not work, be sure to inspect the apache logs (be sure to replace /home/sampo with whatever makes sense):
tail -f /home/sampo/zxid/tmp/err-httpd
If you can't get any access at all, be sure you do not have the mini_httpd or some other process running on the same port.
Also make sure the execute permission is set for any CGI scripts, e.g:
chmod a+x zxid.pl
*** As of 20080924 the XACML PEP functionality has not been implemented. We expect progress within weeks. The following description acts as a specification for our upcoming implementation.
Fig-2: Liberty IGF Compliant Attribute Broker fetches the needed attributes from available providers and populates them to the subprocess environment.
As can be seen in the accompanying figure, the provision of attributes to the applications in the Apache Subprocess Environment (CGI, mod_perm, mod_php, etc.) is handled as follows:
Configure attribute needs and names (this corresponds to CARML declaration)
Configure attribute sources (this corresponds to AAPML declaration)
Configure source mappings
Filter for needs (and optional wants)
Map to application domain
Provide attributes in to subprocess environment
Comply with obligations (large part of this responsibility rests with the subprocesses and can not be automatically enforced)
*** This is provisory specification
NOT IMPLEMENTED YET!
The Attribute Broker configuration in Apache set-up is per
Example
<Location /protected> ZXIDConf "NEED=CN$GUI$40000000$none$ext" ZXIDConf "NEED=age$adult-content$100000$log-upon-sso,report-to-dashboard-if-avail$ext" ZXIDConf "WANT=birthday$horoscope$40000000$log-upon-sso,must-report-to-dashboard$ext" ZXIDConf "WANT=street,l,st,zip,c$ship$40000000$log-upon-sso,report-to-dashboard-if-avail$ext" </Location>
NOT IMPLEMENTED YET!
NEED specification expresses attributes that are required for the application to work. Attribute names are in the Common Namespace (often same as subprocess environment application namespace). Inavailability of the attributes aborts application processing.
NEED=A,B$usage$retention$oblig$ext
Names of attributes (comma separated list) needed by subprocess environment
The promised usage of the attributes (feeds out to CARML declaration). Specific usage enumerators or policy language are still To Be Defined.
The data retention policy that will be applied to these attributes if they are received. Specific enumerators or language are still To Be Defined. The example illustrates retention in seconds.
The obligations that will be complied to WRT these attributes if they are received. Specific enumerators or language are still To Be Defined.
Extension fields to describe attribute policies in more detail.
NOT IMPLEMENTED YET!
WANT specification expresses attributes that are optional, but useful, for the application. Inavailability of the attributes may cause reduced application functionality or the application querying the missing attributes directly from the user. WANT specification has same syntax as NEED specification. Inavailability of the attribute has no consequence or may cause default to be supplied.
WANT=A,B$usage$retention$oblig$ext$default
Names of attributes (comma separated list) needed by subprocess environment. If star (*) is specified, all available attributes are requested.
The promised usage of the attributes (feeds out to CARML declaration). Specific usage enumerators or policy language are still To Be Defined.
The data retention policy that will be applied to these attributes if they are received. Specific enumerators or language are still To Be Defined.
The obligations that will be complied to WRT these attributes if they are received. Specific enumerators or language are still To Be Defined.
Extension fields to describe attribute policies in more detail.
Optional default value to use in case the attribute is not available.
NOT IMPLEMENTED YET!
Attribute Source (ATTRSRC for short) specification indicates a potential source of attribute data and the mechanics for retreiving them. Each attribute originating from a determined source is in namespace of that source (source namespace). This avoids attribute naming conflicts and provides for clean attribute renaming framework. If an attribute is not renamed, then it is passed to the common namespace by just dropping the namespace prefix.
ATTRSRC=namespace$A,B$weight$accessparamURL$AAPMLref$otherLim$ext
Namespace string assigned to this attribute source.
List of attributes available from this source
Weighting factor (integer) determining the prioirity of this source. Less indicates higher preference.
Reference to AAPML declaration about policies applying to this attribute source
Description of additional policies applying to this attribute source
Extensions
NOT IMPLEMENTED YET!
+INMAP+ specification provides for various input attribute renaming and input attribute value decoding operations.
INMAP=src$A$rule$b$ext
Source namespace of the attribute
Attribute name in the source namespace
Attribute name in common namespace (if omitted, same as +A+)
transformation rule:
Just renames the attribute. Value is passed intact.
Decode the attribute value accoring to Feide (Norway) rules. Also rename if +b+ provided.
Encode the attribute value accoring to Feide (Norway) rules. Also rename if +b+ provided.
Decode the attribute value accoring to safebase64-RFC1952 rules ([RFC3548], [RFC1952]). Also rename if +b+ provided.
Encode the attribute value accoring to RFC1952-safebase64 rules ([RFC1952], [RFC3548]). Also rename if +b+ provided.
Decode the attribute value according to safebase64 [RFC3548] rule (NZ). Also rename if +b+ provided.
Encode the attribute value according to safebase64 [RFC3548] rule (NZ). Also rename if +b+ provided.
Extended argument that may be used by some rules.
SSO derived attributes
Concatenation of affid and idpnid like: "affididpnid"
NOT IMPLEMENTED YET!
+OUTMAP+ specification provides for various attribute renaming and value encoding operations just before passing attributes to the subprocess environment (i.e. what CGI scripts see). Syntax and available operations are the same as for INMAP.
OUTMAP=src$A$rule$b$ext
NOT IMPLEMENTED YET!
By default only attributes listed in NEED and WANT specifications are passed thru, and even then only if the available usage policies are acceptable. However, if additional attributes are available, they can be accepted using WANT specification with "*". In this case, some attributes can be filtered out using SUPPRESS directive (infact SUPPRESS applies inconditionally to all attributes just before out-map stage):
SUPPRESS=A,B,C
*** As of 20080924 the XACML PEP functionality has not been implemented. We expect progress within weeks.
Important: You need a functioning XACML PDP (Policy Decision Point to use this functionality. ZXID does not include such PDP - you need aquire and configure a commercial (e.g. Symlabs XAML PDP) or third party open source PDP.
The attributes gathered by the Attribute Broker phase are available for authorization decisions. The local authorization is applied before, and after, the XACML authorization, if any.
Explicit Deny stops processing
Explicit Allow moves to next phase
Lack of Allow or Deny at end of phase moves to next phase
Lack of Allow after all phases is Deny
The authorization module can authorize access locally based on
List of approved user names
Role attribute
Authorization token
The attributes gathered by the Attribute Broker phase are available for formulating the XAML request.
Since the XAML PDP may expect attributes names differently from the Common Namespace, an additional mapping directive is provided.
Subject Attributes
Resource Attributes
Other Attributes?
If you have any trouble, please do not hesitate to contact the author.