README.zxid-tas3
================
$Id: README.zxid-tas3,v 1.4 2009-10-18 12:39:10 sampo Exp $
ZXID is general purpose SSO and Identity Web Services project, see zxid.org
TAS3 - Trustable Architecture for Secure Shared Services - is an European
FP7 research project that has chosen to use SAML 2.0 and ID-WSF 2.0
and is using ZXID as one implementation of these technologies. See tas3.eu
The research leading to these results has received funding from the
European Community's Seventh Framework Programme (FP7/2007-2013) under
grant agreement number 216287 (TAS3 - Trusted Architecture for Securely
Shared Services - www.tas3.eu).
Since ZXID is important for TAS3 and vice versa, ZXID Makefile contains
some targets for producing ZXID specific packages
make tas3maspkg # T3-SSO-ZXID-MODAUTHSAML-V.VV.zip
make tas3phppkg # T3-SSO-ZXID-PHP-V.VV.zip
make tas3javapkg # T3-SSO-ZXID-JAVA-V.VV.zip
make tas3idppkg # T3-IDP-ZXID-V.VV.zip
make tas3rel # build all of the above
make tas3copyrel # scp release packages
https://portal.tas3.eu/pool/ -- Download from here
http://idpdemo.tas3.eu/cot/ -- Register your metadata here
http://idpdemo.tas3.eu/zxididp?o=B -- Publicly available TAS3 demo IdP
<<dia: tas3-integration,,:bg,fg,comp,api,zxmod:: API and modules for SSO and web service call.>>
For help, I recommend joining the ZXID mailing
list zxid.user@lists.unh.edu
at http://listproc.unh.edu/archives/zxid.user/
You can also see TAS3 Architecture Video
http://www.youtube.com/watch?v=QXQ7bbOULYc
http://zxid.org/tas3/ArchitectureExplained_3_4_1.avi
--Sampo
T3-ZXID-LINUX-X86 Install
-------------------------
T3-ZXID-LINUX-X86 package contains binaries for Linux x86 platforms.
It was produced by compiling the source code in T3-ZXID-SRC.
To obtain latest version of the T3-ZXID-LINUX-X86 package please
check https://portal.tas3.eu/pool/ (login needed).
1. Download and unzip the package
unzip T3-ZXID-LINUX-X86_1.03.zip
cd T3-ZXID-LINUX-X86_1.03
2. Check that your system has all the dependency libraries
installed:
ldd zxididp
linux-gate.so.1 => (0xb7818000)
libpthread.so.0 => /lib/libpthread.so.0 (0xb77d6000)
libcurl.so.3 => not found
libssl.so.0.9.8 => /usr/lib/libssl.so.0.9.8 (0xb7792000)
libcrypto.so.0.9.8 => /usr/lib/libcrypto.so.0.9.8 (0xb766a000)
libz.so.1 => /lib/libz.so.1 (0xb7656000)
libc.so.6 => /lib/libc.so.6 (0xb7512000)
/lib/ld-linux.so.2 (0xb7819000)
libdl.so.2 => /lib/libdl.so.2 (0xb750e000)
Here you can see that libcurl.so.3 was not found. To remedy
such dependencies you may need to adjust LD_LIBRARY_PATH
or you may need to simply install the dependency packages
Debian / Ubuntu Redhat
------------------------------ -------------------------
sudo apt-get install libcurl sudo yum install libcurl
sudo apt-get install openssl sudo yum install openssl
sudo apt-get install libz sudo yum install libz
Then recheck with ldd that all libraries are found.
3. Copy maintenance utilities to a directory in your PATH
sudo cp zxcot zxpasswd zxmkdirs.sh zxlogview zxdecode /usr/local/bin
4. Copy zxididp and SP demos to document root of your web server
cp zxididp zxidhlo.php /srv/www/htdocs # OpenSUSE 10.2
The document root directory is distribution and/or web server
and/or local configuration specific. You should know where
it is.
Configuring and using zxididp is further documented in
zxid-idp.pd file or on web site http://zxid.org/html/zxid-idp.html
5. Copy PHP libraries to expected place
sudo mkdir -p `php-config --extension-dir`
sudo cp php/php_zxid.so `php-config --extension-dir`
If you do not intend to use PHP, you can skip this step.
The PHP usage is further documented in
php/README.zxid-php: PHP specific README
zxid-php.pd: Using ZXID from PHP
zxidhlo.php: Example code
Web site: http://zxid.org/html/zxid-php.html
6. Copy Java libraries to expected place
If you do not intend to use Java, you can skip this step.
Here the tricky part is knowing what "the expected place" is.
This will depend on how you configure your servlet engine.
You will need to investigate your own configuration and
tweak the following accordingly:
sudo cp zxidjava/libzxidjni.so /usr/local/apache-tomcat-5.5.20/bin/
sudo cp -r zxidjava /usr/local/apache-tomcat-5.5.20/webapps/your-servlet-dir
To get things to work you may need to perform detctive work
to understand where Java is looking for them or adjust SERVLET_PATH
and/or LD_LIBRARY_PATH. zxid-java.pd has entire section of
documentation dedicated to solving these issues.
The Java usage is further documented in
zxidjava/README.zxid-java Java specific README
zxid-java.pd Using ZXID from Java
zxidsrvlet.java Ready to use SSO servlet
zxidappdemo.java Example code for using SSO servlet
zxidhlo.java Example code for direct SSO integration
Web site: http://zxid.org/html/zxid-java.html
7. Copy Apache SSO support module to the right place
sudo cp mod_auth_saml.so /usr/local/httpd/modules
You will need to determine where your distribution has
installed the Apache httpd and adjust the path accordingly.
Once you think you got it right, you can check with
command
httpd -M
the following line should appear in the output
auth_saml_module (shared)
Despite the name, it indicates that mod_auth_saml has
loaded successfully.
> N.B. Linux distributions often rename httpd as apache2 and
> install it in a location different than where apache httpd
> source code distribution would install by default. For
> example, on Ubuntu the modules directory seems to be
> /usr/lib/apache2/modules
8. Copy include files and libraries to where your development
environment can find them:
sudo cp libzxid.a /usr/local/lib
sudo cp -r include/zx /usr/local/include
This step is only needed if you plan to compile programs
to use zxid. If that is your plan and skillset, you may
prefer to install zxid from source anyway.
9. Create directory hierarchy
Before you run these commands, you need to find out what user
your httpd runs as. Here we have assumed user "apache". Adjust
as needed.
sudo zxmkdirs.sh # For the SP
chown -R apache /var/zxid
su apache
echo NICE_NAME=Your SP Branding >/var/zxid/zxid.conf
echo ORG_NAME=Your Organization >>/var/zxid/zxid.conf
echo ORG_URL=http://your.org/ >>/var/zxid/zxid.conf
echo URL=https://sp1.zxidsp.org:8443/zxidhlo >>/var/zxid/zxid.conf
zxmkdirs.sh /var/zxid/idp # For the IdP
echo NICE_NAME=Your IdP Branding >/var/zxid/idpzxid.conf
echo ORG_NAME=Your IdP Organization >>/var/zxid/idpzxid.conf
echo ORG_URL=http://youridp.org/ >>/var/zxid/idpzxid.conf
echo URL=https://idp1.zxid.org:8443/zxididp >>/var/zxid/idpzxid.conf
echo IDP_ENA=1 >>/var/zxid/idpzxid.conf
echo AS_ENA=1 >>/var/zxid/idpzxid.conf
echo PDP_ENA=1 >>/var/zxid/idpzxid.conf
In the above, the configuration files for SP and IdP were created. Some
configuration options are actually set in the source code of the respective
applications. In the config files you MUST set
NICE_NAME:: Used for user interface purposes (displayed to user) to identify the site.
ORG_NAME:: The name of the legal entity responsible for the site, shown to user.
ORG_URL:: Institutional web site of the legal entity, shown to user.
URL:: Entity Id of the web site. For demo, set them as shown (often set in source).
10. Create certificates
There are two ways to obtain certificates: (a) Allow ZXID to generate them
for you, and (b) obtain and install commercial certificates.
a. Using auto generated certificates
i. For SP certificates, run
zxcot -m
and observe that the output has two large base64 blobs. They
are inside <ds:X509Certificate> XML elements. zxcot -m generates
metadata for the SP. In doing so, it will also generate the
certificates on the fly if they do not exist. If the filesystem
permissions are incorrect, it will fail to generate the certificates.
This is why the `chown -R apache /var/zxid' command was issued
in the previous step (9). Check the permissions with
ls -alF /var/zxid/pem
Keep running zxcot -m until you get it to output the certificates.
ii. For IdP certificates, run
zxcot -ci -m
Again, the certificates are generated on the fly. If not, check
permissions with
ls -alF /var/zxid/idppem
N.B. This assumes the IdP is configured to use the default
PATH /var/zxid/idp (-ci is shorthand for this). If this is
not the case, you will need to supply the PATH explicitly:
zxcot -c 'PATH=/your/idp/path/&IDP_ENA=1' -m
Similarily, if any config options (that affect metadata) are
specified in source code rather than in zxid.conf file,
you would need to supply them to zxcot using the -c option.
b. Installing previously obtained certificates
We assume you have the certificate in file cert.pem and the
private key in priv.pem.
i. For SP
sudo su
cat cert.pem priv.pem >/var/zxid/pem/ssl-nopw-cert.pem # put both in one file
cp /var/zxid/pem/ssl-nopw-cert.pem /var/zxid/pem/sign-nopw-cert.pem
cp /var/zxid/pem/ssl-nopw-cert.pem /var/zxid/pem/enc-nopw-cert.pem
cp /var/zxid/pem/ssl-nopw-cert.pem /var/zxid/pem/logenc-nopw-cert.pem
cp /var/zxid/pem/ssl-nopw-cert.pem /var/zxid/pem/logsign-nopw-cert.pem
chmod 600 /var/zxid/pem/*
# end su
Check with
zxcot -m
ii. For IdP
sudo su
cat cert.pem priv.pem >/var/zxid/idppem/ssl-nopw-cert.pem # put both in one file
cp /var/zxid/idppem/ssl-nopw-cert.pem /var/zxid/idppem/sign-nopw-cert.pem
cp /var/zxid/idppem/ssl-nopw-cert.pem /var/zxid/idppem/enc-nopw-cert.pem
cp /var/zxid/idppem/ssl-nopw-cert.pem /var/zxid/idppem/logenc-nopw-cert.pem
cp /var/zxid/idppem/ssl-nopw-cert.pem /var/zxid/idppem/logsign-nopw-cert.pem
chmod 600 /var/zxid/idppem/*
# end su
Check with
zxcot -ci -m
T3-IDP-ZXID Install
-------------------
Prerequisite:: you must have CGI capable web server, such as mini_httpd, Apache, or IIS.
See also: zxid-idp.pd for more comprehensive documantation
N.B: T3-IDP-ZXID package has been merged with T3-ZXID-LINUX-X86 package, see above.
1. Download and unzip the package
2. ldd zxididp
3. Copy zxididp to document root of your web server
cp zxididp /srv/www/htdocs # OpenSUSE 10.2
4. Create directory hierarchy and initial config
mkdir /var/zxid
chown webuser /var/zxid
su webuser
zxmkdirs.sh /var/zxid/idp
ls -alFR /var/zxid
5. Create configuration file /var/zxid/idpzxid.conf
URL=http://idp.tas3.pt:8081/zxididp
PDP_ENA=1
6. Create a user
mkdir /var/zxid/idpuid/koerkki
echo -n salainen >/var/zxid/idpuid/koerkki/.pw
7. Configure web server to run the zxididp as a CGI script.
On Apache edit httpd.conf (often in /etc/apache2/httpd.conf)
<Location "/zxididp">
Options ExecCGI
SetHandler cgi-script
</Location>
8. Test it
tail -f /var/tmp/zxid.stderr
tail -f /var/log/apache2/error_log
http://idp.tas3.pt:8081/zxididp?o=B
T3-ZXID-SRC Compile and Install
-------------------------------
After unzipping the package, unpack the tarball contained therein, and
read INSTALL.zxid contained in the tarball.
Mapping between TAS3 API and ZXID API
-------------------------------------
* Use zxidjava/libzxidjni.so instead of tas3jni.so
* import zxidjava.*; instead of import tas3.*;
* System.loadLibrary("tas3jni.so"); should become
System.loadLibrary("zxidjava/libzxidjni.so");
* In class names replace "tas3" with "zxidjni", for example
tas3.wsp_validate()
becomes
zxidjni.wsp_validate()
--Sampo